primcli 1.29.0 → 1.31.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-BKso8oJu.js";
+import { S as normalizeApiBaseUrl, c as resolveConfigEnvironment, i as loadCliConfig } from "../cli-config-BvflSzQe.js";
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";

package/man/primitive.1

@@ -27,6 +27,30 @@ receives existing webhook events without a public endpoint. It prints complete
 JSONL bodies on stdout and status on stderr. Use saved login credentials or
 PRIMITIVE_API_KEY. A private default destination is saved per API host and account.
 .PP
+.B primitive listen --notify-session UUID --sender person@example.com
+queues external email metadata into one exact loaded native Codex session.
+Requires an existing private native local-session Unix socket and a connected-agent
+credential. This mode requires WebSocket and the shared saved subscription;
+--transport poll and a custom --subscription are rejected. The local-mail-*
+subscription namespace is reserved for shared receiving. No runtime is launched. Repeat --sender or use comma-separated exact
+addresses. Routine authenticated status interactions do not notify the session.
+.PP
+.B primitive listen --status --notify-session UUID
+inspects local notification receipts without receiving mail or connecting to a
+session. Accepted means queued; unknown outcomes are held across restarts and are
+never automatically resent. Inspect the exact session before a manual resend.
+Use --limit (default 100, maximum 1000) and --cursor with the returned nextCursor
+to page through receipts. Notification subscriptions accept email.received only;
+--once counts a candidate processed during this invocation, including filtered
+or routine email, not a model wake. Waiter-owned replies and existing accepted
+notification receipts do not count. Inbound IDs are saved before server
+acknowledgement; pending authentication or parsing retries exact IDs locally.
+.PP
+Connected chat, exact-parent emails wait, and native notifications share one
+receiver per local installation, API environment, and credential. A remaining
+foreground participant can resume receiving after the owner exits. Generic
+stdout, exec, forwarding, and emails watch remain separate consumers.
+.PP
 .B primitive listen init --language python
 creates a Python starter in a new primitive-listener directory. Generation is
 offline and refuses to overwrite files. Change into that directory and run
@@ -144,6 +168,23 @@ Print the generated API operation manifest.
 .TP
 .B primitive describe COMMAND_OR_OPERATION
 Describe a generated API operation, including request and response schemas.
+
+.SS Waiting with connected credentials
+.B primitive emails wait --reply-to-sent-email-id <sent-id> --from peer@example.com
+waits on an existing send without resending it. The receiving address comes
+from the sent record; an optional --to must match. Existing replies are included
+by default, and --since narrows the window. Only authenticated, exactly threaded
+plain replies are returned; interaction attachments remain pending for inspection.
+JSONL contains matching email details; --table prints compact rows. Timeout exits
+1. Connected waits share one local address event receiver and use exact-parent
+search for recovery; they never scan inbox history. Organization credentials
+retain the existing search-based wait behavior.
+.PP
+Connected chat authenticates the reply receiver before sending and records a
+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.
+
 .SH GLOBAL OPTIONS
 .TP
 .B --api-key KEY
@@ -154,6 +195,39 @@ Print command duration to standard error after completion.
 .TP
 .B --help
 Show command help.
+.SH EXIT STATUS
+.B primitive chat,
+.B primitive chat reply,
+.B primitive send
+and
+.B primitive reply
+share one outcome vocabulary. With
+.B --json
+the outcome is the
+.B outcome
+field of an envelope printed for every result.
+.TP
+.B 0
+.BR replied ,
+.B sent
+(accepted for delivery; queued counts) or
+.B already_sent
+(an identical earlier send, including HTTP 410 sent_email_deleted; nothing new went out).
+.TP
+.B 1
+.BR not_sent :
+the API rejected the request, the command failed before sending, or the send record has status agent_failed, gate_denied or canceled.
+.TP
+.B 2
+Invalid flags or arguments. Nothing was sent.
+.TP
+.B 3
+.BR sent_awaiting_reply :
+chat sent the message but no reply arrived before the timeout. Wait; do not resend.
+.TP
+.B 4
+.BR uncertain :
+transport error, conflict, server error, or a send record with status unknown. The message may have gone out; check sent history before retrying.
 .SH ENVIRONMENT
 .TP
 .B PRIMITIVE_API_KEY

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primcli",
-  "version": "1.29.0",
+  "version": "1.31.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,
@@ -50,10 +50,10 @@
         "description": "Manage your account settings, storage, and webhook secret"
       },
       "agent-connections": {
-        "description": "Remove revoked agent connections with an organization owner or admin login. This preserves mail and does not stop the external runtime."
+        "description": "Claim a private invitation from stdin or remove a revoked connection with an owner/admin login."
       },
       "agent": {
-        "description": "Agent signup and authentication API operations"
+        "description": "Connect an existing agent privately, manage its contacts, or use agent signup operations."
       },
       "credits": {
         "description": "Redeem credit codes and check the organization credit balance"
@@ -129,7 +129,13 @@
         "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 existing webhook events locally. Run primitive listen for JSONL, use --exec for a short durable acceptance hook, or --forward-to for an existing local webhook handler."
+        "description": "Receive events locally as JSONL, use --exec or --forward-to, or notify an exact loaded native session with --notify-session and approved --sender addresses. Use --status --notify-session to inspect durable notification receipts."
+      },
+      "contacts": {
+        "description": "Shared organization contacts. Use list, get, add, update, or remove; edits use conditional versions."
+      },
+      "agent:contacts": {
+        "description": "Contacts and notification preferences for one agent address. Connected profiles default to their own address."
       }
     },
     "topicSeparator": " "
@@ -160,13 +166,15 @@
     "@oclif/plugin-autocomplete": "^3.2.45",
     "@oclif/plugin-help": "^6.2.44",
     "@oclif/plugin-warn-if-update-available": "^3.1.65",
-    "viem": "^2.21.0"
+    "viem": "^2.21.0",
+    "ws": "^8.21.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",
     "@primitivedotdev/api-core": "workspace:*",
     "@primitivedotdev/sdk": "workspace:*",
     "@types/node": "^22.10.2",
+    "@types/ws": "^8.18.1",
     "@vitest/coverage-v8": "^4.1.11",
     "oclif": "^4.23.0",
     "tsdown": "^0.21.10",