@primitivedotdev/cli 0.31.6 → 0.31.8

package/bin/run.js

@@ -7,5 +7,10 @@ import { restartWithProxyEnvIfNeeded } from "../dist/oclif/proxy-auto-detect.js"
 // process.env inside this process is too late for built-in fetch.
 restartWithProxyEnvIfNeeded();
 
+const { writeLoggedOutSignupHintIfNeeded } = await import(
+  "../dist/oclif/root-signup-hint.js"
+);
+writeLoggedOutSignupHintIfNeeded();
+
 const { execute } = await import("@oclif/core");
 await execute({ dir: import.meta.url });

package/dist/oclif/index.js

@@ -655,6 +655,7 @@ var sdk_gen_exports = /* @__PURE__ */ __exportAll({
 	getSendPermissions: () => getSendPermissions,
 	getSentEmail: () => getSentEmail,
 	getStorageStats: () => getStorageStats,
+	getThread: () => getThread,
 	getWebhookSecret: () => getWebhookSecret,
 	listDeliveries: () => listDeliveries,
 	listDomains: () => listDomains,
@@ -1579,6 +1580,33 @@ const getSentEmail = (options) => (options.client ?? client).get({
 	...options
 });
 /**
+* Get a conversation thread by id
+*
+* Returns a conversation thread: its metadata plus the inbound
+* and outbound messages that belong to it, interleaved in time
+* order (oldest first). A thread spans both received emails and
+* your sends, so an agent can reconstruct an entire back-and-forth
+* from one call instead of walking reply headers.
+*
+* Each message carries a `direction` (`inbound` | `outbound`) and
+* an `id`; fetch the full message via `/emails/{id}` or
+* `/sent-emails/{id}` accordingly. Bodies are omitted here to keep
+* the thread view lightweight.
+*
+* Discover a thread id from the `thread_id` field on any email or
+* sent-email (list or detail). The message list is capped; compare
+* `message_count` against `messages.length` to detect truncation.
+*
+*/
+const getThread = (options) => (options.client ?? client).get({
+	security: [{
+		scheme: "bearer",
+		type: "http"
+	}],
+	url: "/threads/{id}",
+	...options
+});
+/**
 * List functions
 *
 * Returns every active (non-deleted) function in the org, newest
@@ -1929,6 +1957,10 @@ const openapiDocument = {
 			"name": "Sending",
 			"description": "Send outbound emails through the Primitive API"
 		},
+		{
+			"name": "Threads",
+			"description": "Conversation threads spanning received and sent emails"
+		},
 		{
 			"name": "Endpoints",
 			"description": "Manage webhook endpoints that receive email events"
@@ -3424,6 +3456,27 @@ const openapiDocument = {
 				"404": { "$ref": "#/components/responses/NotFound" }
 			}
 		} },
+		"/threads/{id}": {
+			"parameters": [{ "$ref": "#/components/parameters/ResourceId" }],
+			"get": {
+				"operationId": "getThread",
+				"summary": "Get a conversation thread by id",
+				"description": "Returns a conversation thread: its metadata plus the inbound\nand outbound messages that belong to it, interleaved in time\norder (oldest first). A thread spans both received emails and\nyour sends, so an agent can reconstruct an entire back-and-forth\nfrom one call instead of walking reply headers.\n\nEach message carries a `direction` (`inbound` | `outbound`) and\nan `id`; fetch the full message via `/emails/{id}` or\n`/sent-emails/{id}` accordingly. Bodies are omitted here to keep\nthe thread view lightweight.\n\nDiscover a thread id from the `thread_id` field on any email or\nsent-email (list or detail). The message list is capped; compare\n`message_count` against `messages.length` to detect truncation.\n",
+				"tags": ["Threads"],
+				"responses": {
+					"200": {
+						"description": "Thread detail",
+						"content": { "application/json": { "schema": { "allOf": [{ "$ref": "#/components/schemas/SuccessEnvelope" }, {
+							"type": "object",
+							"properties": { "data": { "$ref": "#/components/schemas/Thread" } }
+						}] } } }
+					},
+					"400": { "$ref": "#/components/responses/ValidationError" },
+					"401": { "$ref": "#/components/responses/Unauthorized" },
+					"404": { "$ref": "#/components/responses/NotFound" }
+				}
+			}
+		},
 		"/functions": {
 			"get": {
 				"operationId": "listFunctions",
@@ -5291,7 +5344,12 @@ const openapiDocument = {
 					},
 					"raw_size_bytes": { "type": ["integer", "null"] },
 					"webhook_status": { "$ref": "#/components/schemas/EmailWebhookStatus" },
-					"webhook_attempt_count": { "type": "integer" }
+					"webhook_attempt_count": { "type": "integer" },
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this message belongs to. Fetch\n`/threads/{thread_id}` for the full ordered thread. NULL on\nmessages received before threading was enabled.\n"
+					}
 				},
 				"required": [
 					"id",
@@ -5510,6 +5568,19 @@ const openapiDocument = {
 						"type": ["string", "null"],
 						"format": "uuid",
 						"description": "The `sent_emails.id` of the outbound this inbound was a\nreply to, when resolvable. Set at inbound ingest by\nmatching the parsed In-Reply-To (or References, as a\nfallback) against `sent_emails.message_id` in the same\norg. The mirror of `sent_emails.in_reply_to_email_id` for\nthe inbound side of a thread. NULL when the inbound is\nnot a threaded reply to one of your sends, when neither\nheader survived the path through intermediate MTAs, or on\ninbound received before this auto-link landed.\n"
+					},
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this message belongs to. Inbound and\noutbound messages in the same conversation share a\n`thread_id`; fetch `/threads/{thread_id}` for the full\nordered thread. Assigned at ingest. NULL on messages\nreceived before threading was enabled (until backfilled).\n"
+					},
+					"parsed": {
+						"allOf": [{ "$ref": "#/components/schemas/ParsedEmailData" }],
+						"description": "Parsed MIME content (addresses, threading headers,\nattachment metadata), matching the `email.parsed` object\non the webhook payload so one parser handles both the\nwebhook and this endpoint. The top-level `body_text` /\n`body_html` fields above are the same values as\n`parsed.body_text` / `parsed.body_html`, retained for\nbackward compatibility.\n"
+					},
+					"auth": {
+						"allOf": [{ "$ref": "#/components/schemas/EmailAuth" }],
+						"description": "SPF / DKIM / DMARC verdicts computed at ingest, matching\nthe `email.auth` object on the webhook payload. Use these\nto decide how much to trust a message before acting on\ninstructions it contains.\n"
 					}
 				},
 				"required": [
@@ -5523,7 +5594,9 @@ const openapiDocument = {
 					"webhook_attempt_count",
 					"from_email",
 					"to_email",
-					"replies"
+					"replies",
+					"parsed",
+					"auth"
 				]
 			},
 			"EmailDetailReply": {
@@ -5556,6 +5629,241 @@ const openapiDocument = {
 					"created_at"
 				]
 			},
+			"EmailAddress": {
+				"type": "object",
+				"description": "A parsed RFC 5322 address with optional display name.",
+				"properties": {
+					"name": {
+						"type": ["string", "null"],
+						"description": "Display name, when present (e.g. `Alice Example`)."
+					},
+					"address": {
+						"type": "string",
+						"description": "Bare email address (e.g. `alice@example.com`)."
+					}
+				},
+				"required": ["address"]
+			},
+			"EmailAttachment": {
+				"type": "object",
+				"description": "Metadata for one attachment. The bytes are not inline; download\nall attachments for a message as a gzipped tarball via\n`/emails/{id}/attachments.tar.gz`. `sha256` lets you verify a\nspecific part after extraction.\n",
+				"properties": {
+					"filename": { "type": ["string", "null"] },
+					"content_type": { "type": ["string", "null"] },
+					"size_bytes": { "type": "integer" },
+					"sha256": { "type": ["string", "null"] },
+					"part_index": {
+						"type": "integer",
+						"description": "Zero-based index of this part within the message."
+					}
+				},
+				"required": ["size_bytes"]
+			},
+			"ParsedEmailData": {
+				"type": "object",
+				"description": "Parsed MIME content for an inbound email. Mirrors the\n`email.parsed` object on the webhook payload so a single parser\nhandles both surfaces. `status` is `complete` when parsing\nsucceeded; on `failed` the body/address/attachment fields are\nabsent and `error` describes why.\n",
+				"properties": {
+					"status": {
+						"type": "string",
+						"enum": ["complete", "failed"]
+					},
+					"body_text": {
+						"type": ["string", "null"],
+						"description": "Plain-text body. Present when `status` is `complete`."
+					},
+					"body_html": {
+						"type": ["string", "null"],
+						"description": "HTML body. Present when `status` is `complete`."
+					},
+					"reply_to": {
+						"type": ["array", "null"],
+						"items": { "$ref": "#/components/schemas/EmailAddress" },
+						"description": "Parsed `Reply-To` header addresses."
+					},
+					"cc": {
+						"type": ["array", "null"],
+						"items": { "$ref": "#/components/schemas/EmailAddress" },
+						"description": "Parsed `Cc` header addresses."
+					},
+					"bcc": {
+						"type": ["array", "null"],
+						"items": { "$ref": "#/components/schemas/EmailAddress" },
+						"description": "Parsed `Bcc` header addresses (rarely present on inbound)."
+					},
+					"to_addresses": {
+						"type": ["array", "null"],
+						"items": { "$ref": "#/components/schemas/EmailAddress" },
+						"description": "Parsed `To` header addresses."
+					},
+					"in_reply_to": {
+						"type": ["array", "null"],
+						"items": { "type": "string" },
+						"description": "Message-IDs from the `In-Reply-To` header."
+					},
+					"references": {
+						"type": ["array", "null"],
+						"items": { "type": "string" },
+						"description": "Message-IDs from the `References` header."
+					},
+					"attachments": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/EmailAttachment" },
+						"description": "Attachment metadata. Empty array when none."
+					},
+					"error": {
+						"type": ["object", "null"],
+						"description": "Present (non-null) only when `status` is `failed`. When\npresent, all three fields are populated, so a consumer can\nbranch on `code` without defensive null checks.\n",
+						"properties": {
+							"code": {
+								"type": "string",
+								"description": "Stable failure code (e.g. `PARSE_FAILED`)."
+							},
+							"message": { "type": "string" },
+							"retryable": { "type": "boolean" }
+						},
+						"required": [
+							"code",
+							"message",
+							"retryable"
+						]
+					}
+				},
+				"required": ["status"]
+			},
+			"DkimSignature": {
+				"type": "object",
+				"description": "One DKIM signature found on the message, with its verdict.",
+				"properties": {
+					"domain": { "type": "string" },
+					"selector": { "type": "string" },
+					"result": {
+						"type": "string",
+						"description": "Verification result (e.g. `pass`, `fail`, `none`)."
+					},
+					"aligned": {
+						"type": "boolean",
+						"description": "Whether the signing domain aligns with the From domain (for DMARC)."
+					},
+					"keyBits": { "type": ["integer", "null"] },
+					"algo": { "type": ["string", "null"] }
+				},
+				"required": [
+					"domain",
+					"selector",
+					"result",
+					"aligned"
+				]
+			},
+			"EmailAuth": {
+				"type": "object",
+				"description": "SPF / DKIM / DMARC verdicts computed at ingest. Mirrors the\n`email.auth` object on the webhook payload. Field names are\ncamelCase to match that payload exactly. For messages received\nbefore auth was recorded, the verdicts default to `none`.\n",
+				"properties": {
+					"spf": {
+						"type": "string",
+						"description": "SPF result (e.g. `pass`, `fail`, `softfail`, `none`)."
+					},
+					"dmarc": {
+						"type": "string",
+						"description": "DMARC result (e.g. `pass`, `fail`, `none`)."
+					},
+					"dmarcPolicy": {
+						"type": ["string", "null"],
+						"description": "Published DMARC policy (`none`, `quarantine`, `reject`)."
+					},
+					"dmarcFromDomain": {
+						"type": ["string", "null"],
+						"description": "The From-header domain DMARC was evaluated against."
+					},
+					"dmarcSpfAligned": { "type": "boolean" },
+					"dmarcDkimAligned": { "type": "boolean" },
+					"dmarcSpfStrict": { "type": ["boolean", "null"] },
+					"dmarcDkimStrict": { "type": ["boolean", "null"] },
+					"dkimSignatures": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/DkimSignature" }
+					}
+				},
+				"required": [
+					"spf",
+					"dmarc",
+					"dmarcSpfAligned",
+					"dmarcDkimAligned",
+					"dkimSignatures"
+				]
+			},
+			"Thread": {
+				"type": "object",
+				"description": "A conversation thread: its metadata plus the inbound and\noutbound messages that belong to it, interleaved oldest-first.\nMembership is the stored `thread_id` on each message. Bodies are\nomitted here to keep the thread view lightweight; fetch\n`/emails/{id}` or `/sent-emails/{id}` for a single message's\nfull content.\n",
+				"properties": {
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"subject": {
+						"type": ["string", "null"],
+						"description": "Normalized subject of the thread (Re/Fwd prefixes stripped)."
+					},
+					"root_message_id": {
+						"type": ["string", "null"],
+						"description": "Message-ID of the conversation root, when known."
+					},
+					"message_count": {
+						"type": "integer",
+						"description": "Total messages in the thread. `messages` is capped (most\nrecent first, then re-sorted oldest-first), so\n`message_count > messages.length` signals truncation.\n"
+					},
+					"first_message_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"last_message_at": {
+						"type": ["string", "null"],
+						"format": "date-time"
+					},
+					"created_at": {
+						"type": "string",
+						"format": "date-time"
+					},
+					"messages": {
+						"type": "array",
+						"items": { "$ref": "#/components/schemas/ThreadMessage" }
+					}
+				},
+				"required": [
+					"id",
+					"message_count",
+					"created_at",
+					"messages"
+				]
+			},
+			"ThreadMessage": {
+				"type": "object",
+				"description": "One message in a thread (inbound or outbound).",
+				"properties": {
+					"direction": {
+						"type": "string",
+						"enum": ["inbound", "outbound"],
+						"description": "`inbound` for a received email (`/emails/{id}`), `outbound`\nfor a send (`/sent-emails/{id}`). Use it with `id` to fetch\nfull content from the right endpoint.\n"
+					},
+					"id": {
+						"type": "string",
+						"format": "uuid"
+					},
+					"message_id": { "type": ["string", "null"] },
+					"from": { "type": ["string", "null"] },
+					"to": { "type": ["string", "null"] },
+					"subject": { "type": ["string", "null"] },
+					"status": {
+						"type": ["string", "null"],
+						"description": "Lifecycle status (an EmailStatus or SentEmailStatus value, per `direction`)."
+					},
+					"timestamp": {
+						"type": ["string", "null"],
+						"format": "date-time",
+						"description": "received_at for inbound, created_at for outbound."
+					}
+				},
+				"required": ["direction", "id"]
+			},
 			"SendMailAttachment": {
 				"type": "object",
 				"additionalProperties": false,
@@ -5772,6 +6080,11 @@ const openapiDocument = {
 						"format": "uuid",
 						"description": "Reference to the inbound `emails.id` that this send\nreplied to, when known. Populated when the caller used\n/emails/{id}/reply or when /send-mail's `in_reply_to`\nmatched a stored inbound message_id in the same org.\n"
 					},
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this send belongs to. A reply inherits\nthe thread of the inbound it answers; a fresh send starts a\nnew thread. Fetch `/threads/{thread_id}` for the full\nordered thread (inbound + outbound interleaved). NULL on\ngate-denied sends and on sends created before threading was\nenabled.\n"
+					},
 					"queue_id": {
 						"type": ["string", "null"],
 						"description": "Message identifier assigned by Primitive's outbound\nrelay once the agent accepts the message. Null on\nqueued, gate_denied, and agent_failed rows.\n"
@@ -8873,6 +9186,218 @@ const operationManifest = [
 					"type": ["string", "null"],
 					"format": "uuid",
 					"description": "The `sent_emails.id` of the outbound this inbound was a\nreply to, when resolvable. Set at inbound ingest by\nmatching the parsed In-Reply-To (or References, as a\nfallback) against `sent_emails.message_id` in the same\norg. The mirror of `sent_emails.in_reply_to_email_id` for\nthe inbound side of a thread. NULL when the inbound is\nnot a threaded reply to one of your sends, when neither\nheader survived the path through intermediate MTAs, or on\ninbound received before this auto-link landed.\n"
+				},
+				"thread_id": {
+					"type": ["string", "null"],
+					"format": "uuid",
+					"description": "Conversation thread this message belongs to. Inbound and\noutbound messages in the same conversation share a\n`thread_id`; fetch `/threads/{thread_id}` for the full\nordered thread. Assigned at ingest. NULL on messages\nreceived before threading was enabled (until backfilled).\n"
+				},
+				"parsed": {
+					"allOf": [{
+						"type": "object",
+						"description": "Parsed MIME content for an inbound email. Mirrors the\n`email.parsed` object on the webhook payload so a single parser\nhandles both surfaces. `status` is `complete` when parsing\nsucceeded; on `failed` the body/address/attachment fields are\nabsent and `error` describes why.\n",
+						"properties": {
+							"status": {
+								"type": "string",
+								"enum": ["complete", "failed"]
+							},
+							"body_text": {
+								"type": ["string", "null"],
+								"description": "Plain-text body. Present when `status` is `complete`."
+							},
+							"body_html": {
+								"type": ["string", "null"],
+								"description": "HTML body. Present when `status` is `complete`."
+							},
+							"reply_to": {
+								"type": ["array", "null"],
+								"items": {
+									"type": "object",
+									"description": "A parsed RFC 5322 address with optional display name.",
+									"properties": {
+										"name": {
+											"type": ["string", "null"],
+											"description": "Display name, when present (e.g. `Alice Example`)."
+										},
+										"address": {
+											"type": "string",
+											"description": "Bare email address (e.g. `alice@example.com`)."
+										}
+									},
+									"required": ["address"]
+								},
+								"description": "Parsed `Reply-To` header addresses."
+							},
+							"cc": {
+								"type": ["array", "null"],
+								"items": {
+									"type": "object",
+									"description": "A parsed RFC 5322 address with optional display name.",
+									"properties": {
+										"name": {
+											"type": ["string", "null"],
+											"description": "Display name, when present (e.g. `Alice Example`)."
+										},
+										"address": {
+											"type": "string",
+											"description": "Bare email address (e.g. `alice@example.com`)."
+										}
+									},
+									"required": ["address"]
+								},
+								"description": "Parsed `Cc` header addresses."
+							},
+							"bcc": {
+								"type": ["array", "null"],
+								"items": {
+									"type": "object",
+									"description": "A parsed RFC 5322 address with optional display name.",
+									"properties": {
+										"name": {
+											"type": ["string", "null"],
+											"description": "Display name, when present (e.g. `Alice Example`)."
+										},
+										"address": {
+											"type": "string",
+											"description": "Bare email address (e.g. `alice@example.com`)."
+										}
+									},
+									"required": ["address"]
+								},
+								"description": "Parsed `Bcc` header addresses (rarely present on inbound)."
+							},
+							"to_addresses": {
+								"type": ["array", "null"],
+								"items": {
+									"type": "object",
+									"description": "A parsed RFC 5322 address with optional display name.",
+									"properties": {
+										"name": {
+											"type": ["string", "null"],
+											"description": "Display name, when present (e.g. `Alice Example`)."
+										},
+										"address": {
+											"type": "string",
+											"description": "Bare email address (e.g. `alice@example.com`)."
+										}
+									},
+									"required": ["address"]
+								},
+								"description": "Parsed `To` header addresses."
+							},
+							"in_reply_to": {
+								"type": ["array", "null"],
+								"items": { "type": "string" },
+								"description": "Message-IDs from the `In-Reply-To` header."
+							},
+							"references": {
+								"type": ["array", "null"],
+								"items": { "type": "string" },
+								"description": "Message-IDs from the `References` header."
+							},
+							"attachments": {
+								"type": "array",
+								"items": {
+									"type": "object",
+									"description": "Metadata for one attachment. The bytes are not inline; download\nall attachments for a message as a gzipped tarball via\n`/emails/{id}/attachments.tar.gz`. `sha256` lets you verify a\nspecific part after extraction.\n",
+									"properties": {
+										"filename": { "type": ["string", "null"] },
+										"content_type": { "type": ["string", "null"] },
+										"size_bytes": { "type": "integer" },
+										"sha256": { "type": ["string", "null"] },
+										"part_index": {
+											"type": "integer",
+											"description": "Zero-based index of this part within the message."
+										}
+									},
+									"required": ["size_bytes"]
+								},
+								"description": "Attachment metadata. Empty array when none."
+							},
+							"error": {
+								"type": ["object", "null"],
+								"description": "Present (non-null) only when `status` is `failed`. When\npresent, all three fields are populated, so a consumer can\nbranch on `code` without defensive null checks.\n",
+								"properties": {
+									"code": {
+										"type": "string",
+										"description": "Stable failure code (e.g. `PARSE_FAILED`)."
+									},
+									"message": { "type": "string" },
+									"retryable": { "type": "boolean" }
+								},
+								"required": [
+									"code",
+									"message",
+									"retryable"
+								]
+							}
+						},
+						"required": ["status"]
+					}],
+					"description": "Parsed MIME content (addresses, threading headers,\nattachment metadata), matching the `email.parsed` object\non the webhook payload so one parser handles both the\nwebhook and this endpoint. The top-level `body_text` /\n`body_html` fields above are the same values as\n`parsed.body_text` / `parsed.body_html`, retained for\nbackward compatibility.\n"
+				},
+				"auth": {
+					"allOf": [{
+						"type": "object",
+						"description": "SPF / DKIM / DMARC verdicts computed at ingest. Mirrors the\n`email.auth` object on the webhook payload. Field names are\ncamelCase to match that payload exactly. For messages received\nbefore auth was recorded, the verdicts default to `none`.\n",
+						"properties": {
+							"spf": {
+								"type": "string",
+								"description": "SPF result (e.g. `pass`, `fail`, `softfail`, `none`)."
+							},
+							"dmarc": {
+								"type": "string",
+								"description": "DMARC result (e.g. `pass`, `fail`, `none`)."
+							},
+							"dmarcPolicy": {
+								"type": ["string", "null"],
+								"description": "Published DMARC policy (`none`, `quarantine`, `reject`)."
+							},
+							"dmarcFromDomain": {
+								"type": ["string", "null"],
+								"description": "The From-header domain DMARC was evaluated against."
+							},
+							"dmarcSpfAligned": { "type": "boolean" },
+							"dmarcDkimAligned": { "type": "boolean" },
+							"dmarcSpfStrict": { "type": ["boolean", "null"] },
+							"dmarcDkimStrict": { "type": ["boolean", "null"] },
+							"dkimSignatures": {
+								"type": "array",
+								"items": {
+									"type": "object",
+									"description": "One DKIM signature found on the message, with its verdict.",
+									"properties": {
+										"domain": { "type": "string" },
+										"selector": { "type": "string" },
+										"result": {
+											"type": "string",
+											"description": "Verification result (e.g. `pass`, `fail`, `none`)."
+										},
+										"aligned": {
+											"type": "boolean",
+											"description": "Whether the signing domain aligns with the From domain (for DMARC)."
+										},
+										"keyBits": { "type": ["integer", "null"] },
+										"algo": { "type": ["string", "null"] }
+									},
+									"required": [
+										"domain",
+										"selector",
+										"result",
+										"aligned"
+									]
+								}
+							}
+						},
+						"required": [
+							"spf",
+							"dmarc",
+							"dmarcSpfAligned",
+							"dmarcDkimAligned",
+							"dkimSignatures"
+						]
+					}],
+					"description": "SPF / DKIM / DMARC verdicts computed at ingest, matching\nthe `email.auth` object on the webhook payload. Use these\nto decide how much to trust a message before acting on\ninstructions it contains.\n"
 				}
 			},
 			"required": [
@@ -8886,7 +9411,9 @@ const operationManifest = [
 				"webhook_attempt_count",
 				"from_email",
 				"to_email",
-				"replies"
+				"replies",
+				"parsed",
+				"auth"
 			]
 		},
 		"sdkName": "getEmail",
@@ -9016,7 +9543,12 @@ const operationManifest = [
 							null
 						]
 					},
-					"webhook_attempt_count": { "type": "integer" }
+					"webhook_attempt_count": { "type": "integer" },
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this message belongs to. Fetch\n`/threads/{thread_id}` for the full ordered thread. NULL on\nmessages received before threading was enabled.\n"
+					}
 				},
 				"required": [
 					"id",
@@ -9277,7 +9809,12 @@ const operationManifest = [
 							null
 						]
 					},
-					"webhook_attempt_count": { "type": "integer" }
+					"webhook_attempt_count": { "type": "integer" },
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this message belongs to. Fetch\n`/threads/{thread_id}` for the full ordered thread. NULL on\nmessages received before threading was enabled.\n"
+					}
 				},
 				"required": [
 					"id",
@@ -11523,6 +12060,11 @@ const operationManifest = [
 						"format": "uuid",
 						"description": "Reference to the inbound `emails.id` that this send\nreplied to, when known. Populated when the caller used\n/emails/{id}/reply or when /send-mail's `in_reply_to`\nmatched a stored inbound message_id in the same org.\n"
 					},
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this send belongs to. A reply inherits\nthe thread of the inbound it answers; a fresh send starts a\nnew thread. Fetch `/threads/{thread_id}` for the full\nordered thread (inbound + outbound interleaved). NULL on\ngate-denied sends and on sends created before threading was\nenabled.\n"
+					},
 					"queue_id": {
 						"type": ["string", "null"],
 						"description": "Message identifier assigned by Primitive's outbound\nrelay once the agent accepts the message. Null on\nqueued, gate_denied, and agent_failed rows.\n"
@@ -11807,6 +12349,11 @@ const operationManifest = [
 						"format": "uuid",
 						"description": "Reference to the inbound `emails.id` that this send\nreplied to, when known. Populated when the caller used\n/emails/{id}/reply or when /send-mail's `in_reply_to`\nmatched a stored inbound message_id in the same org.\n"
 					},
+					"thread_id": {
+						"type": ["string", "null"],
+						"format": "uuid",
+						"description": "Conversation thread this send belongs to. A reply inherits\nthe thread of the inbound it answers; a fresh send starts a\nnew thread. Fetch `/threads/{thread_id}` for the full\nordered thread (inbound + outbound interleaved). NULL on\ngate-denied sends and on sends created before threading was\nenabled.\n"
+					},
 					"queue_id": {
 						"type": ["string", "null"],
 						"description": "Message identifier assigned by Primitive's outbound\nrelay once the agent accepts the message. Null on\nqueued, gate_denied, and agent_failed rows.\n"
@@ -12259,6 +12806,101 @@ const operationManifest = [
 		"tag": "Sending",
 		"tagCommand": "sending"
 	},
+	{
+		"binaryResponse": false,
+		"bodyRequired": false,
+		"command": "get-thread",
+		"description": "Returns a conversation thread: its metadata plus the inbound\nand outbound messages that belong to it, interleaved in time\norder (oldest first). A thread spans both received emails and\nyour sends, so an agent can reconstruct an entire back-and-forth\nfrom one call instead of walking reply headers.\n\nEach message carries a `direction` (`inbound` | `outbound`) and\nan `id`; fetch the full message via `/emails/{id}` or\n`/sent-emails/{id}` accordingly. Bodies are omitted here to keep\nthe thread view lightweight.\n\nDiscover a thread id from the `thread_id` field on any email or\nsent-email (list or detail). The message list is capped; compare\n`message_count` against `messages.length` to detect truncation.\n",
+		"hasJsonBody": false,
+		"method": "GET",
+		"operationId": "getThread",
+		"path": "/threads/{id}",
+		"pathParams": [{
+			"description": "Resource UUID",
+			"enum": null,
+			"name": "id",
+			"required": true,
+			"type": "string"
+		}],
+		"queryParams": [],
+		"requestSchema": null,
+		"responseSchema": {
+			"type": "object",
+			"description": "A conversation thread: its metadata plus the inbound and\noutbound messages that belong to it, interleaved oldest-first.\nMembership is the stored `thread_id` on each message. Bodies are\nomitted here to keep the thread view lightweight; fetch\n`/emails/{id}` or `/sent-emails/{id}` for a single message's\nfull content.\n",
+			"properties": {
+				"id": {
+					"type": "string",
+					"format": "uuid"
+				},
+				"subject": {
+					"type": ["string", "null"],
+					"description": "Normalized subject of the thread (Re/Fwd prefixes stripped)."
+				},
+				"root_message_id": {
+					"type": ["string", "null"],
+					"description": "Message-ID of the conversation root, when known."
+				},
+				"message_count": {
+					"type": "integer",
+					"description": "Total messages in the thread. `messages` is capped (most\nrecent first, then re-sorted oldest-first), so\n`message_count > messages.length` signals truncation.\n"
+				},
+				"first_message_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				},
+				"last_message_at": {
+					"type": ["string", "null"],
+					"format": "date-time"
+				},
+				"created_at": {
+					"type": "string",
+					"format": "date-time"
+				},
+				"messages": {
+					"type": "array",
+					"items": {
+						"type": "object",
+						"description": "One message in a thread (inbound or outbound).",
+						"properties": {
+							"direction": {
+								"type": "string",
+								"enum": ["inbound", "outbound"],
+								"description": "`inbound` for a received email (`/emails/{id}`), `outbound`\nfor a send (`/sent-emails/{id}`). Use it with `id` to fetch\nfull content from the right endpoint.\n"
+							},
+							"id": {
+								"type": "string",
+								"format": "uuid"
+							},
+							"message_id": { "type": ["string", "null"] },
+							"from": { "type": ["string", "null"] },
+							"to": { "type": ["string", "null"] },
+							"subject": { "type": ["string", "null"] },
+							"status": {
+								"type": ["string", "null"],
+								"description": "Lifecycle status (an EmailStatus or SentEmailStatus value, per `direction`)."
+							},
+							"timestamp": {
+								"type": ["string", "null"],
+								"format": "date-time",
+								"description": "received_at for inbound, created_at for outbound."
+							}
+						},
+						"required": ["direction", "id"]
+					}
+				}
+			},
+			"required": [
+				"id",
+				"message_count",
+				"created_at",
+				"messages"
+			]
+		},
+		"sdkName": "getThread",
+		"summary": "Get a conversation thread by id",
+		"tag": "Threads",
+		"tagCommand": "threads"
+	},
 	{
 		"binaryResponse": false,
 		"bodyRequired": false,
@@ -13887,6 +14529,21 @@ function resolveChatResponseBody(reply) {
 function matchDescription(strategy) {
 	return strategy === "strict" ? "strict, matched by reply_to_sent_email_id" : "fallback, matched by sender/time window";
 }
+function normalizeEmailAddress(value) {
+	return value.trim().toLowerCase();
+}
+function derivedReplySubject(parent) {
+	const subject = parent.subject?.trim();
+	if (!subject) return "Re: (no subject)";
+	return /^re:/i.test(subject) ? subject : `Re: ${subject}`;
+}
+function assertParentMatchesRecipient(parent, recipient) {
+	if (normalizeEmailAddress(parent.from_email) === normalizeEmailAddress(recipient)) return;
+	throw cliError$6(`Inbound email ${parent.id} is from ${parent.from_email}, not ${recipient}. Use \`primitive chat ${parent.from_email} --reply <message> --reply-to-email-id ${parent.id}\` or omit --reply-to-email-id to continue the latest inbound from ${recipient}.`);
+}
+function emailDetailFromEnvelope(envelope) {
+	return envelope?.data ?? envelope ?? null;
+}
 function buildCommand(kind, description, argv, options = {}) {
 	const requiresMessage = options.requiresMessage ?? false;
 	return {
@@ -13907,15 +14564,15 @@ function buildChatFollowUpCommands(context) {
 		"primitive",
 		"chat",
 		context.recipient,
+		"--reply",
 		"<message>",
 		"--from",
 		context.from,
-		"--subject",
-		context.subject,
+		"--reply-to-email-id",
+		context.reply.id,
 		"--timeout",
 		String(context.timeoutSeconds)
 	];
-	if (context.reply.message_id) continueParts.push("--in-reply-to", context.reply.message_id);
 	if (context.json) continueParts.push("--json");
 	if (context.quiet) continueParts.push("--quiet");
 	if (context.strictOnly) continueParts.push("--strict-only");
@@ -14049,6 +14706,55 @@ function formatChatRecoveryContext(context) {
 	for (const { description, command } of buildChatRecoveryCommands(context)) lines.push(`  ${description}:`, `    ${command}`);
 	return lines.join("\n");
 }
+async function loadInboundEmailDetail(params) {
+	const result = await getEmail({
+		client: params.apiClient.client,
+		path: { id: params.id },
+		responseStyle: "fields"
+	});
+	if (result.error) {
+		const payload = extractErrorPayload(result.error);
+		writeErrorWithHints(payload);
+		surfaceUnauthorizedHint({
+			...params.authFailureContext,
+			payload
+		});
+		throw new Errors.CLIError(`Could not load inbound email ${params.id}.`, { exit: 1 });
+	}
+	const detail = emailDetailFromEnvelope(result.data);
+	if (!detail) throw new Errors.CLIError(`Could not load inbound email ${params.id}: the API returned no email body.`, { exit: 1 });
+	return detail;
+}
+async function findLatestInboundFromRecipient(params) {
+	const result = await searchEmails({
+		client: params.apiClient.client,
+		query: {
+			from: params.recipient,
+			to: params.from,
+			include_facets: "false",
+			limit: params.pageSize,
+			snippet: "false",
+			sort: "received_at_desc"
+		},
+		responseStyle: "fields"
+	});
+	if (result.error) {
+		const payload = extractErrorPayload(result.error);
+		writeErrorWithHints(payload);
+		surfaceUnauthorizedHint({
+			...params.authFailureContext,
+			payload
+		});
+		throw new Errors.CLIError("Could not find a prior chat reply.", { exit: 1 });
+	}
+	const row = (result.data?.data ?? []).find((email) => email.status === "accepted" || email.status === "completed");
+	if (!row) return null;
+	return loadInboundEmailDetail({
+		apiClient: params.apiClient,
+		authFailureContext: params.authFailureContext,
+		id: row.id
+	});
+}
 var ChatCommand = class ChatCommand extends Command {
 	static description = `Send a message to an address and wait for the reply.
 
@@ -14062,6 +14768,13 @@ var ChatCommand = class ChatCommand extends Command {
   follow-up commands as templates. The default transcript is for humans;
   agents and scripts should pass --json for parse-safe output.
 
+  To continue an existing chat, pass --reply '<message>'. By default,
+  the CLI replies to the latest inbound email from the recipient to
+  your sender address. For exact continuation, pass
+  --reply-to-email-id <inbound-email-id>. Reply mode uses Primitive's
+  reply endpoint, so the reply subject and threading headers are
+  derived from the inbound email instead of copied into CLI flags.
+
   --json emits a structured envelope with both sides of the exchange,
   a direct response_body field, match details, and follow-up command
   metadata such as kind, argv, placeholders, and requires_message.
@@ -14079,6 +14792,8 @@ var ChatCommand = class ChatCommand extends Command {
 	static examples = [
 		"<%= config.bin %> chat help@agent.acme.dev 'how do I rotate my API key?'",
 		"cat error.log | <%= config.bin %> chat help@agent.acme.dev --subject 'webhook 401s'",
+		"<%= config.bin %> chat help@agent.acme.dev --reply 'one more thing'",
+		"<%= config.bin %> chat help@agent.acme.dev --reply 'one more thing' --reply-to-email-id <inbound-email-id>",
 		"<%= config.bin %> chat help@agent.acme.dev 'follow up question' --json",
 		"<%= config.bin %> chat help@agent.acme.dev 'one more thing' --timeout 300"
 	];
@@ -14106,7 +14821,9 @@ var ChatCommand = class ChatCommand extends Command {
 		}),
 		from: Flags.string({ description: "Sender address. Defaults to agent@<your-first-verified-outbound-domain>." }),
 		subject: Flags.string({ description: "Subject line. Defaults to the first line of the message when omitted." }),
-		"in-reply-to": Flags.string({ description: "Message-Id of the parent email to thread this against. Use when continuing a prior conversation from outside the CLI; for an inbound you received via Primitive, prefer `primitive reply --id <inbound-id>`." }),
+		reply: Flags.string({ description: "Reply body. Continues the latest inbound email from the recipient to your sender address; pass --reply-to-email-id for an exact thread." }),
+		"reply-to-email-id": Flags.string({ description: "Inbound email id to continue exactly. Uses Primitive's reply endpoint, so recipient, subject, and threading headers are derived from the inbound email." }),
+		"in-reply-to": Flags.string({ description: "Raw Message-Id of the parent email to thread a new send against. Prefer --reply-to-email-id with --reply when continuing an inbound email stored by Primitive." }),
 		json: Flags.boolean({ description: "Emit a structured JSON envelope { sent, reply, response_body, response_body_format, match, follow_up_commands } on stdout instead of the human-readable transcript." }),
 		quiet: Flags.boolean({ description: "Suppress stderr progress updates while sending and waiting. Errors and recovery commands are still written to stderr." }),
 		timeout: Flags.integer({
@@ -14136,8 +14853,12 @@ var ChatCommand = class ChatCommand extends Command {
 	};
 	async run() {
 		const { args, flags } = await this.parse(ChatCommand);
-		const message = args.message !== void 0 && args.message !== "" ? args.message : await readStdinToString();
-		if (!message.trim()) throw cliError$6("Message body is empty.");
+		const replyMode = flags.reply !== void 0 || flags["reply-to-email-id"] !== void 0;
+		if (flags.reply !== void 0 && args.message !== void 0 && args.message !== "") throw cliError$6("Pass the reply body either as --reply or as the positional message, not both.");
+		if (replyMode && flags.subject !== void 0) throw cliError$6("--subject is not used with --reply. Primitive derives the reply subject from the inbound email.");
+		if (replyMode && flags["in-reply-to"] !== void 0) throw cliError$6("Use --reply-to-email-id with --reply instead of raw --in-reply-to.");
+		const message = flags.reply !== void 0 ? flags.reply : args.message !== void 0 && args.message !== "" ? args.message : await readStdinToString();
+		if (!message.trim()) throw cliError$6(replyMode ? "Reply body is empty." : "Message body is empty.");
 		await runWithTiming(flags.time, async () => {
 			const { apiClient, auth, baseUrlOverridden } = await createAuthenticatedCliApiClient({
 				apiKey: flags["api-key"],
@@ -14150,12 +14871,71 @@ var ChatCommand = class ChatCommand extends Command {
 				baseUrlOverridden,
 				configDir: this.config.configDir
 			};
-			const from = flags.from ?? await pickDefaultFromAddress(apiClient, authFailureContext);
-			const subject = flags.subject ?? deriveSubject(message);
-			const sentAtIso = (/* @__PURE__ */ new Date()).toISOString();
 			const progress = flags.quiet ? null : new ChatProgressIndicator(process.stderr);
-			progress?.start(`Sending message to ${args.recipient}`);
-			const sendResult = await sendEmail({
+			let from;
+			let parentReply;
+			let subject;
+			if (replyMode) {
+				const replyContext = await (async () => {
+					let replyContextFailureMessage = "Could not load reply context.";
+					try {
+						if (flags["reply-to-email-id"] !== void 0) {
+							progress?.start(`Loading reply context for ${flags["reply-to-email-id"]}`);
+							const exactParentReply = await loadInboundEmailDetail({
+								apiClient,
+								authFailureContext,
+								id: flags["reply-to-email-id"]
+							});
+							replyContextFailureMessage = `Inbound email ${flags["reply-to-email-id"]} does not match recipient ${args.recipient}.`;
+							assertParentMatchesRecipient(exactParentReply, args.recipient);
+							return {
+								from: flags.from ?? exactParentReply.to_email,
+								parentReply: exactParentReply
+							};
+						}
+						const replyFrom = flags.from ?? await pickDefaultFromAddress(apiClient, authFailureContext);
+						progress?.start(`Finding latest inbound email from ${args.recipient}`);
+						const latestParentReply = await findLatestInboundFromRecipient({
+							apiClient,
+							authFailureContext,
+							from: replyFrom,
+							pageSize: flags["page-size"],
+							recipient: args.recipient
+						});
+						if (!latestParentReply) {
+							replyContextFailureMessage = "No prior inbound email found.";
+							throw cliError$6(`No prior inbound email from ${args.recipient} to ${replyFrom}. Start a new chat with \`primitive chat ${args.recipient} <message>\`, pass --from, or pass --reply-to-email-id <inbound-email-id>.`);
+						}
+						replyContextFailureMessage = `Inbound email ${latestParentReply.id} does not match recipient ${args.recipient}.`;
+						assertParentMatchesRecipient(latestParentReply, args.recipient);
+						return {
+							from: replyFrom,
+							parentReply: latestParentReply
+						};
+					} catch (error) {
+						progress?.fail(replyContextFailureMessage);
+						throw error;
+					}
+				})();
+				from = replyContext.from;
+				parentReply = replyContext.parentReply;
+				subject = derivedReplySubject(replyContext.parentReply);
+			} else {
+				from = flags.from ?? await pickDefaultFromAddress(apiClient, authFailureContext);
+				subject = flags.subject ?? deriveSubject(message);
+			}
+			const sentAtIso = (/* @__PURE__ */ new Date()).toISOString();
+			if (replyMode) progress?.update(`Sending reply to ${args.recipient}`);
+			else progress?.start(`Sending message to ${args.recipient}`);
+			const sendResult = parentReply !== void 0 ? await replyToEmail({
+				body: {
+					body_text: message,
+					from
+				},
+				client: apiClient.client,
+				path: { id: parentReply.id },
+				responseStyle: "fields"
+			}) : await sendEmail({
 				body: {
 					from,
 					to: args.recipient,
@@ -14167,7 +14947,7 @@ var ChatCommand = class ChatCommand extends Command {
 				responseStyle: "fields"
 			});
 			if (sendResult.error) {
-				progress?.fail("Message send failed.");
+				progress?.fail(replyMode ? "Reply send failed." : "Message send failed.");
 				const errorPayload = extractErrorPayload(sendResult.error);
 				writeErrorWithHints(errorPayload);
 				surfaceUnauthorizedHint({
@@ -14182,13 +14962,15 @@ var ChatCommand = class ChatCommand extends Command {
 				progress?.fail("Send succeeded but the API returned no data.");
 				throw cliError$6("Send succeeded but the API returned no data.");
 			}
-			progress?.update(`Message sent; waiting for reply from ${args.recipient}`, {
+			const replyAddress = sent.from || from;
+			progress?.update(`${replyMode ? "Reply" : "Message"} sent; waiting for reply from ${args.recipient}`, {
 				heartbeatMs: 15e3,
 				timeoutSeconds: flags.timeout
 			});
 			const baseContext = {
-				from,
+				from: replyAddress,
 				json: flags.json,
+				parentReply,
 				quiet: flags.quiet,
 				recipient: args.recipient,
 				sent,
@@ -14203,7 +14985,7 @@ var ChatCommand = class ChatCommand extends Command {
 				replyResult = await waitForReply({
 					apiClient,
 					authFailureContext,
-					from,
+					from: replyAddress,
 					interval: flags.interval,
 					notice: (message) => {
 						if (progress) {

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

@@ -0,0 +1,31 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+//#region src/oclif/root-signup-hint.ts
+const CREDENTIALS_FILE = "credentials.json";
+function activeConfigDir(env, home) {
+	if (env.PRIMITIVE_CONFIG_DIR) return env.PRIMITIVE_CONFIG_DIR;
+	return join(env.XDG_CONFIG_HOME || join(home, ".config"), "primitive");
+}
+function shouldShowLoggedOutSignupHint(options = {}) {
+	if ((options.argv ?? process.argv.slice(2)).length > 0) return false;
+	const env = options.env ?? process.env;
+	if (env.PRIMITIVE_HIDE_SIGNUP_HINT === "1") return false;
+	if (env.PRIMITIVE_API_KEY?.trim()) return false;
+	return !existsSync(join(activeConfigDir(env, options.home ?? homedir()), CREDENTIALS_FILE));
+}
+function loggedOutSignupHint() {
+	return [
+		"New to Primitive?",
+		"  You or your user don't have an account yet?",
+		"  Run `primitive signup <email> --signup-code <invite-code> --accept-terms`",
+		"  to create an account, get your own domain, and get started now.",
+		""
+	].join("\n");
+}
+function writeLoggedOutSignupHintIfNeeded(options = {}) {
+	if (!shouldShowLoggedOutSignupHint(options)) return;
+	(options.write ?? ((message) => process.stdout.write(message)))(loggedOutSignupHint());
+}
+//#endregion
+export { loggedOutSignupHint, shouldShowLoggedOutSignupHint, writeLoggedOutSignupHintIfNeeded };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitivedotdev/cli",
-  "version": "0.31.6",
+  "version": "0.31.8",
   "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,
@@ -25,8 +25,15 @@
     "dirname": "primitive",
     "plugins": [
       "@oclif/plugin-help",
-      "@oclif/plugin-autocomplete"
+      "@oclif/plugin-autocomplete",
+      "@oclif/plugin-warn-if-update-available"
     ],
+    "warn-if-update-available": {
+      "timeoutInDays": 1,
+      "frequency": 1,
+      "frequencyUnit": "days",
+      "message": "Primitive CLI update available from <%= chalk.greenBright(config.version) %> to <%= chalk.greenBright(latest) %>. Run `npm install -g @primitivedotdev/cli@latest` to update."
+    },
     "topics": {
       "cli": {
         "description": "CLI authentication"
@@ -59,6 +66,9 @@
       "sent": {
         "description": "Short aliases for outbound sent-email history: `primitive sent list` and `primitive sent get`."
       },
+      "threads": {
+        "description": "Inspect conversation threads spanning received and sent emails: `primitive threads get --id <thread-id>`."
+      },
       "endpoints": {
         "description": "Manage webhook endpoints that receive email events"
       },
@@ -112,7 +122,8 @@
   "dependencies": {
     "@oclif/core": "^4.10.5",
     "@oclif/plugin-autocomplete": "^3.2.45",
-    "@oclif/plugin-help": "^6.2.44"
+    "@oclif/plugin-help": "^6.2.44",
+    "@oclif/plugin-warn-if-update-available": "^3.1.65"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.10",