primcli 1.32.0 → 1.33.0

package/dist/oclif/root-signup-hint.js

@@ -1,4 +1,4 @@
-import { S as normalizeApiBaseUrl, c as resolveConfigEnvironment, i as loadCliConfig } from "../cli-config-BvflSzQe.js";
+import { S as normalizeApiBaseUrl, c as resolveConfigEnvironment, i as loadCliConfig } from "../cli-config-Cv2-NAOd.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";

package/man/primitive.1

@@ -90,6 +90,44 @@ expose local webhook delivery on API hosts where it is enabled. Each command
 makes one API request. Use their --help output for the input fields. Consumers
 deduplicate event IDs and report the outcome with the returned attempt and lease.
 Queue retention does not extend source-content retention; inspect gap counts.
+.SH AGENT LOOP
+Every inbound email carries reply state:
+.B awaiting
+is
+.B you
+when the latest message in its thread is inbound and
+.B them
+when you replied last (queued and scheduled replies count).
+.B primitive inbox next
+prints the oldest email awaiting you with its conversation, and
+.B primitive reply --id ID
+answers it, after which the next call moves on:
+.PP
+.RS
+.nf
+primitive inbox next
+primitive reply --id ID --body TEXT
+primitive inbox next
+.fi
+.RE
+.PP
+Automated mail (bounces, mailer-daemon, postmaster, mail from the very address it was delivered to, delivery reports, Auto-Submitted, X-Auto-Response-Suppress, bulk and list mail) is skipped unless
+.B --include-automated
+is given. The server decides this when the mail arrives and filters on it, so the call does not slow down as unanswered automated mail accumulates; a server without that filter fails with
+.B automated_filter_unsupported
+instead of scanning.
+.B --wait
+blocks until something awaits you, taking the inbox position before checking so no arrival is missed;
+.B --timeout
+bounds it.
+.B --json
+prints a stable envelope.
+.PP
+It is not a work queue: nothing is claimed, so two agents on one inbox get the same email until one replies.
+.PP
+Exit status of
+.BR "primitive inbox next" :
+0 an email awaits you; 1 error (including reply_state_unsupported from a server without reply state); 2 invalid flags; 5 nothing awaits you.
 .SH AUTHENTICATION
 .PP
 Commands use saved OAuth credentials from
@@ -121,7 +159,10 @@ to remove local credentials, pending email-code auth state, and stale credential
 .PP
 Run
 .B primitive whoami
-to verify which account the CLI is authenticated as.
+to verify account authentication. With PRIMITIVE_AGENT_PROFILE selected, it
+prints saved connected identity offline, without claiming live authentication
+or receiving readiness. Use listen --status --notify-session UUID to inspect
+the exact receiver under the same profile.
 .SH COMMON COMMANDS
 .TP
 .B primitive send --to ADDRESS --subject SUBJECT --body TEXT
@@ -140,7 +181,14 @@ Verify DNS records for a pending domain claim.
 Download DNS records as a BIND-format zone file.
 .TP
 .B primitive emails latest
-Show recent inbound emails.
+Show recent inbound emails, with whose turn it is (AWAITING) and the reply count.
+.TP
+.B primitive emails latest --awaiting you
+Show only inbound emails waiting on your reply.
+.TP
+.B primitive inbox next
+Show the oldest email awaiting your reply, its conversation, and the reply command. See
+.BR "AGENT LOOP" .
 .TP
 .B primitive functions init NAME
 Scaffold a Primitive Function.
@@ -185,6 +233,27 @@ stable idempotency key. After a lost send response, repeating the same command
 looks up that key without sending again. Timed-out exact-parent waits retain
 their claim for resume. A plain reply does not prove task completion.
 
+.SS Explicit communication signals
+.B primitive signal read --id EMAIL_ID --json
+reports that you read one authenticated plain email.
+.B primitive signal ack --id EMAIL_ID --status received --json
+reports acknowledgement; supported statuses are received, will_process, and
+will_not_process. Choose the state you actually intend.
+.B primitive signal working --id EMAIL_ID --expires-in 30 --json
+and
+.B primitive signal typing --id EMAIL_ID --expires-in 30 --json
+report temporary activity. Both default to 30 seconds; typing allows 1-30
+seconds and working allows 1-60. These commands require a saved connected
+profile selected with PRIMITIVE_AGENT_PROFILE and pin its sender identity.
+.PP
+Read and acknowledgement deduplicate by parent, kind and acknowledgement status.
+Unexpired activity deduplicates; a new explicit invocation after a known outcome
+expires may send fresh activity. Unknown sends must reconcile before renewal;
+expired unsent activity is never replayed. No automatic signal or task authority
+is granted. Signal and interaction parents are refused to prevent reply loops.
+JSON outcomes are sent, already_sent, expired (exit 0), not_sent (exit 1), and
+uncertain (exit 4). Ordinary CLI argument errors exit 2.
+
 .SH GLOBAL OPTIONS
 .TP
 .B --api-key KEY

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primcli",
-  "version": "1.32.0",
+  "version": "1.33.0",
   "description": "Official Primitive CLI: deploy Primitive Functions, send and inspect mail, manage endpoints, all from the terminal. Wraps the @primitivedotdev/sdk runtime client with one-shot commands.",
   "type": "module",
   "sideEffects": false,
@@ -53,7 +53,7 @@
         "description": "Claim a private invitation from stdin or remove a revoked connection with an owner/admin login."
       },
       "agent": {
-        "description": "Connect an existing agent privately, manage its contacts, or use agent signup operations."
+        "description": "Connect an invited session, enroll a new session using a saved owner login, disconnect one saved profile, or manage contacts and signup."
       },
       "credits": {
         "description": "Redeem credit codes and check the organization credit balance"
@@ -65,7 +65,7 @@
         "description": "Create and manage agent registries, publish and resolve agents by handle, and moderate publication requests"
       },
       "inbox": {
-        "description": "Check inbound email setup and processing readiness. Prefer `primitive inbox setup` for a guided setup path and `primitive inbox status` for the readiness table."
+        "description": "Check inbound email setup and readiness, and work through mail awaiting your reply. Prefer `primitive inbox setup` for a guided setup path, `primitive inbox status` for the readiness table, and `primitive inbox next` for the oldest email awaiting your reply."
       },
       "emails": {
         "description": "List, inspect, and wait for received emails. Prefer task aliases like `primitive emails list`, `primitive emails get`, `primitive emails latest`, `primitive emails wait`, and `primitive emails watch`; generated API names remain available for compatibility."
@@ -129,13 +129,16 @@
         "description": "Schedule and send wake commands to your own functions over signed email, and manage which senders may wake them. Use `primitive wake schedules list|create|get|update|delete|run`, `primitive wake authorizations list|create|update|delete`, and `primitive wake dispatches list`."
       },
       "listen": {
-        "description": "Receive events locally as JSONL, use --exec or --forward-to, or notify an exact loaded native session using --notify-session with --contacts or approved --sender addresses. Add --contact-requests for owner-enabled structured first-contact intake. Use --status --notify-session to inspect durable notification receipts."
+        "description": "Receive events locally as JSONL with JSON status responses by default; --json is accepted explicitly. Use --exec or --forward-to, or deliver external mail events as tool output, never user messages, to an exact loaded native session using --notify-session with --contacts or approved --sender addresses. Add --email-id to --status to explain one received email. Add --contact-requests for owner-enabled structured first-contact intake. Use --background for independent receiving, --status --notify-session for current receiver health and durable receipts, or --stop --notify-session to stop only that receiver."
       },
       "contacts": {
-        "description": "Shared organization contacts plus structured request, accept, and wait commands for connected agents. Directory list, get, add, update, and remove use conditional versions."
+        "description": "Shared organization contacts plus structured request, accept, and wait commands for connected agents. Directory list, get, add, update, and remove use conditional versions. Commands return JSON by default and accept explicit --json."
       },
       "agent:contacts": {
-        "description": "Contacts and notification preferences for one agent address. Connected profiles default to their own address."
+        "description": "Contacts and notification preferences for one agent address. Connected profiles default to their own address. Commands return JSON by default and accept explicit --json."
+      },
+      "agent:notes": {
+        "description": "Read and maintain organization address notes. Connected profiles default to their own address and can write only their own notes. Use agent notes list|get|set|delete; new notes are private, and updates preserve visibility unless explicitly changed. Commands return JSON by default."
       }
     },
     "topicSeparator": " "