@extrovert.dev/sdk 0.1.0-pre.4 → 0.1.0-pre.6

package/dist/index.d.cts

@@ -6,7 +6,7 @@
  * on 429/5xx, honors `Retry-After`, and surfaces every failure as a typed {@link ApiError}.
  */
 /** The library version, surfaced in the User-Agent. Kept in sync with package.json by build. */
-declare const SDK_VERSION = "0.1.0-pre.4";
+declare const SDK_VERSION = "0.1.0-pre.6";
 interface RetryOptions {
     /** Max retry attempts for idempotent requests on 429/5xx/network errors. Default 2. */
     maxRetries: number;
@@ -58,7 +58,7 @@ type IsoTimestamp = string;
  * buy a new domain (`POST /v1/domains` with `mode: "purchased"`). `review:act` gates
  * the BYO reviewer decision plane.
  */
-type Scope = "mailbox:create" | "mailbox:read" | "mailbox:send" | "mailbox:quota" | "mailbox:delete" | "webhook:write" | "domain:manage" | "domain:purchase" | "review:act";
+type Scope = "mailbox:create" | "mailbox:read" | "mailbox:send" | "mailbox:quota" | "mailbox:credentials" | "mailbox:delete" | "webhook:write" | "domain:manage" | "domain:purchase" | "review:act" | "signup:verify";
 /** How a Extrovert domain was onboarded (§7). */
 type OnboardingMode = "shared" | "purchased" | "ns_delegated" | "manual";
 /** Lifecycle status of an agent principal. */
@@ -520,6 +520,8 @@ interface SendRequest {
      * routes to needs_review with gate_outcome `held:low_confidence`.
      */
     category_confidence?: number;
+    /** Opaque token from the fresh getRules call used for this composition. */
+    composition_token?: string;
 }
 /**
  * Request body for the canonical thread-aware reply,
@@ -555,6 +557,7 @@ interface ReplyRequest {
     category_id?: string;
     /** Agent-supplied confidence (0..1); see {@link SendRequest.category_confidence}. */
     category_confidence?: number;
+    composition_token?: string;
 }
 /**
  * Request body for `POST /v1/inboxes/{addr}/messages/{id}/forward`. Re-sends the
@@ -589,6 +592,7 @@ interface ForwardRequest {
     category_id?: string;
     /** Agent-supplied confidence (0..1); see {@link SendRequest.category_confidence}. */
     category_confidence?: number;
+    composition_token?: string;
     /** See {@link SendRequest.idempotency_key} — sent as a header, never in the body. */
     idempotency_key?: string;
 }
@@ -811,6 +815,8 @@ interface SubmitRevisionRequest {
     html?: string;
     built_at?: IsoTimestamp;
     rules_version_seen?: number;
+    /** Opaque token from the fresh getRules call used for this redraft. */
+    composition_token?: string;
     /**
      * REPLACES the draft's attachments. Omit the field to leave them untouched;
      * send an empty array to clear them.
@@ -1185,6 +1191,14 @@ interface GetRulesParams {
     /** Narrow to one layer (general | category). Default returns both. */
     scope?: "general" | "category";
 }
+/** Stable effective rule stack plus an opaque proof for the next composition. */
+interface RuleSnapshot extends Page<Rule> {
+    house_style_version: number;
+    category_rules_version: number;
+    rule_high_water: number;
+    composition_token?: string;
+    composition_token_expires_at?: IsoTimestamp;
+}
 /**
  * Save / edit a writing rule (append-only by supersession; spec §5.4; D11).
  *
@@ -1196,6 +1210,8 @@ interface GetRulesParams {
  * `scope` is the category axis, `rule_layer` is the ownership axis.)
  */
 interface SaveRuleRequest {
+    /** Stable retry key, sent as Idempotency-Key and omitted from the JSON body. */
+    idempotency_key?: string;
     /** Defaults from category_id (general iff empty). */
     scope?: "general" | "category";
     /** Category id (cat_…); empty = house-style/general (D2). */
@@ -1619,13 +1635,13 @@ interface SignUpRequest {
 }
 /**
  * Response from `POST /v1/agent/sign-up`. The `agent_key` is a LIMITED-scope key
- * (read-only) until the emailed code is confirmed via `POST /v1/agent/verify`.
- * The OTP itself is never returned — it is emailed to `human_email`.
+ * (read-only) that expires with the emailed code. Successful verification revokes
+ * it and returns a replacement full-scope key. The OTP itself is never returned.
  */
 interface SignUpResponse {
     customer_id: string;
     agent_id: string;
-    /** Limited-scope agent key, shown once. Re-calling signup rotates it. */
+    /** Limited-scope bootstrap key, shown once and bounded by `otp_expires_at`. */
     agent_key: string;
     key_prefix: string;
     scopes: Scope[];
@@ -1642,17 +1658,40 @@ interface VerifyRequest {
     /** The one-time code delivered to the signup human email. */
     otp: string;
 }
+/** One copy-ready MCP operation in the post-verification mailbox handoff. */
+interface MailboxQuickstartCall {
+    tool: "read_messages" | "get_message" | "wait_for_email";
+    arguments: Record<string, unknown>;
+}
 /**
- * Response from `POST /v1/agent/verify`. On success a NEW full-scope `agent_key`
- * is returned (shown once); switch to it for subsequent calls.
+ * Safe, MCP-first next calls for the inbox returned by signup verification.
+ * SDK callers can use `address` with the typed inbox/message resources instead;
+ * these calls keep agent runtimes from inventing raw HTTP routes or parsers.
+ */
+interface MailboxQuickstart {
+    inbox: string;
+    list_mail: MailboxQuickstartCall;
+    read_message: MailboxQuickstartCall;
+    wait_for_mail: MailboxQuickstartCall;
+}
+/**
+ * Response from `POST /v1/agent/verify`. On success the bootstrap key is revoked
+ * and a NEW full-scope `agent_key` is returned; switch to it for subsequent calls.
+ * `address` repeats the ready inbox so the handoff remains self-contained after
+ * a process restart or context compaction.
  */
 interface VerifyResponse {
     agent_id: string;
     agent_key: string;
     key_prefix: string;
     scopes: Scope[];
+    /** The signup inbox, ready for immediate list/read/wait/send operations. */
+    address: string;
     verified: boolean;
     message: string;
+    mailbox_quickstart: MailboxQuickstart;
+    /** One-time email-bound owner claim for the human console, when freshly seeded. */
+    org_claim_token?: string;
 }
 /**
  * Response from `GET /v1/auth/me` — the verified principal behind the key.
@@ -1840,7 +1879,7 @@ interface Transport {
     proposeGraduation(categoryId: string, req: ProposeGraduationRequest, signal?: AbortSignal): Promise<GraduationStatus>;
     getScanBacklogStatus(categoryId: string, signal?: AbortSignal): Promise<ScanBacklogStatus>;
     getCategoryPacingState(categoryId: string, signal?: AbortSignal): Promise<CategoryPacingState>;
-    getRules(params: GetRulesParams, signal?: AbortSignal): Promise<Page<Rule>>;
+    getRules(params: GetRulesParams, signal?: AbortSignal): Promise<RuleSnapshot>;
     saveRule(req: SaveRuleRequest, signal?: AbortSignal): Promise<Rule>;
     promoteRule(ruleId: string, toScope: "general" | "category", signal?: AbortSignal): Promise<Rule>;
     retireRule(ruleId: string, signal?: AbortSignal): Promise<Rule>;
@@ -2059,7 +2098,7 @@ declare class MockBackend {
     /** rank a rule for the §7 ladder (mock mirror of the server's deterministic order). */
     private ruleRank;
     /** Get the ORDERED active rule set (mock) — §7 ladder + category-before-general. */
-    getRules(params?: GetRulesParams): Page<Rule>;
+    getRules(params?: GetRulesParams): RuleSnapshot;
     /** Save / edit a rule (mock) — append-only by supersession (D11). */
     saveRule(req: SaveRuleRequest): Rule;
     /** Promote a rule between layers (mock, via supersession), or undefined when unknown. */
@@ -2976,7 +3015,7 @@ declare class Rules {
     private readonly ctx;
     constructor(ctx: ResourceContext);
     /** Get the ORDERED active rule set (precedence ladder applied; NO LLM). */
-    get(params?: GetRulesParams, signal?: AbortSignal): Promise<Page<Rule>>;
+    get(params?: GetRulesParams, signal?: AbortSignal): Promise<RuleSnapshot>;
     /**
      * Save / edit a rule (append-only by supersession; D11). An agent-plane save is
      * ALWAYS project-layer: the saved rule's `rule_layer` is `project`, bound to the
@@ -3103,11 +3142,17 @@ declare class ExtrovertClient {
      * + a first inbox and returns a LIMITED-scope (read-only) agent key; a one-time
      * code is emailed to `human_email`. Call {@link verify} with the code to unlock
      * full scopes. Idempotent on `human_email`: re-calling rotates the key + resends.
+     * When free signup is paused, this throws an `ApiError` with status 403 and
+     * code `signup_disabled` without creating account state.
      */
     signUp(req: SignUpRequest, signal?: AbortSignal): Promise<SignUpResponse>;
     /**
      * Confirm the emailed signup code and receive a NEW full-scope agent key (shown
      * once). Must be called with the limited key from {@link signUp} as the bearer.
+     * The result repeats the ready inbox address and includes MCP-first list/read/wait
+     * calls; SDK callers can pass `address` directly to `inboxes` and `messages`.
+     * Pending verification is also fail-closed with 403 `signup_disabled` while
+     * free signup is paused.
      */
     verify(req: VerifyRequest, signal?: AbortSignal): Promise<VerifyResponse>;
     /** Introspect the principal behind the current key (`GET /v1/auth/me`). */
@@ -3674,7 +3719,7 @@ declare function signWebhook(secret: string, body: string, timestampSeconds: num
  *
  * ## Provisional, pre-1.0 (0.x)
  *
- * {@link CONTRACT_VERSION} is **`0.1.0-pre.4`** — a deliberately **provisional**, pre-1.0
+ * {@link CONTRACT_VERSION} is **`0.1.0-pre.6`** — a deliberately **provisional**, pre-1.0
  * contract. It is open and documented, but it MAY still evolve before 1.0: there
  * are no external users yet, and the **D20 shared-pool auto-send governor** is a
  * hard prerequisite before onboarding external users. Pin the version; expect
@@ -3731,12 +3776,12 @@ interface DiffJson {
 /**
  * The published version of the Extrovert Review-Loop open contract (D14).
  *
- * **`0.1.0-pre.4` — PROVISIONAL, pre-1.0.** Versioned *with the SDK* (this package's
+ * **`0.1.0-pre.6` — PROVISIONAL, pre-1.0.** Versioned *with the SDK* (this package's
  * `package.json` version) and aligned to the openapi `info.version`. Open and
  * documented, but MAY still evolve before 1.0 (no external users yet; the D20
  * shared-pool governor is required before external users). Pin it.
  */
-declare const CONTRACT_VERSION: "0.1.0-pre.4";
+declare const CONTRACT_VERSION: "0.1.0-pre.6";
 /** The stability posture of a published contract version. */
 type ContractStability = "provisional" | "stable";
 /**
@@ -3779,4 +3824,4 @@ interface ContractManifest {
  */
 declare const CONTRACT_MANIFEST: ContractManifest;
 
-export { API_VERSION_HEADER, type AccountRiskDial, type AckReviewEventEntry, type AckReviewEventRequest, type AckReviewEventResult, type AddContactListRequest, type Agent, type AgentStatus, ApiError, type ApiErrorBody, type Attachment, type AttachmentDownload, type AttachmentInput, AuthenticationError, type BatchUpdateMessagesRequest, type BatchUpdateResult, BornStaleError, BreadthRequiredError, CONTRACT_MANIFEST, CONTRACT_VERSION, CURRENT_API_VERSION, Categories, type Category, type CategoryPacingState, type CategoryRiskDial, ConflictError, ConnectionError, type ContactListDirection, type ContactListEntry, type ContactListKind, ContactLists, type ContractManifest, type ContractStability, type CreateInboxRequest, type Cursor, DEFAULT_BASE_URL, type DeleteResult, type DiffHunk, type DiffJson, type Domain, type DomainOffboard, type DomainRecord, type DomainScope, Domains, type EffectiveRiskDial, type EmailAddress, type EnrollRequest, type EnrollResponse, type ExtractedCredentials, ExtrovertClient as Extrovert, ExtrovertClient, type ExtrovertClientOptions, ForbiddenScopeError, type ForwardRequest, type GetInboxParams, type GetRuleAuditParams, type GetRulesParams, type GraduationStatus, IdempotencyConflictError, type Inbox, type InboxCredentials, InboxHandle, type InboxInclude, type InboxMetadata, type InboxMetadataPatch, type InboxMetadataValue, type InboxStatus, Inboxes, IntentRequiredError, type IsoTimestamp, type Job, type KeyTier, type List, type ListCategoriesParams, type ListInboxesParams, type ListMessagesParams, ListPage, type ListParams, type ListReviewEventsParams, type ListReviewsParams, type ListSuppressionsParams, type ListThreadsParams, MOCK_BASE_URL, type MailFolder, type MarkReadRequest, type Message, type MessageDirection, Messages, MockBackend, NotFoundError, type OnboardDomainRequest, type OnboardingMode, PROBLEM_CODES, type PacingItem, type Page, type PageFetcher, PaymentRequiredError, PermissionError, type PostReviewChatRequest, type Problem, type ProblemCode, type ProblemField, type ProjectInboxListParams, ProjectInboxes, Projects, type ProposeCategoryRequest, type ProposeGraduationRequest, type QueuedForReviewResult, REVIEW_PROBLEM_RETRYABLE, RateLimitError, RecipientSuppressedError, type RegisterWebhookRequest, type ReplyRequest, type RestampReviewRequest, type Review, ReviewConflictError, type ReviewDecisionContext, type ReviewEvent, type ReviewEventCursor, type ReviewEventReason, ReviewEvents, type ReviewEventsResult, type ReviewFeedback, type ReviewFeedbackComment, type ReviewInclude, type ReviewIntent, type ReviewMode, type ReviewPolicy, type ReviewState, type ReviewTurn, type ReviewerAction, type ReviewerDecisionRequest, type ReviewerDecisionResult, Reviews, type RiskDial, type Rule, type RuleAuditEntry, type RuleLayer, Rules, SDK_VERSION, type SaveRuleRequest, type ScanBacklogStatus, type Scope, type SearchMessagesParams, SendNeedsReconciliationError, type SendOutcome, type SendRequest, type SendResult, type SentResult, type SignUpRequest, type SignUpResponse, StaleError, type StreamEvent, type StreamOptions, type SubmitForReviewResult, type SubmitRevisionRequest, type SuppressionEntry, type SuppressionPrecheck, type SuppressionScope, type SuppressionSource, Suppressions, TerminalError, type Thread, type ThreadDetail, Threads, TimeoutError, UnavailableError, type UpdateCategoryRequest, type UpdateInboxRequest, type UpdateWebhookRequest, ValidationError, type VerifyRequest, type VerifyResponse, type VerifyWebhookOptions, type WaitForEmailRequest, type WaitForEmailResult, type WaitForReviewEventParams, type Webhook, type WebhookEvent, type WebhookPayload, Webhooks, type WhoAmI, WrongStateError, extractCredentials, extractLink, extractOtp, isProblemCode, isQueuedForReview, isSentImmediately, listPage, parseKeyTier, parseProblem, parseWebhook, reviewIdOf, sentMessageIdOf, serializeInclude, signWebhook, threadIdOf, tierAllowsOrgWildcard, tierNeedsExplicitBreadth, verifyWebhookSignature };
+export { API_VERSION_HEADER, type AccountRiskDial, type AckReviewEventEntry, type AckReviewEventRequest, type AckReviewEventResult, type AddContactListRequest, type Agent, type AgentStatus, ApiError, type ApiErrorBody, type Attachment, type AttachmentDownload, type AttachmentInput, AuthenticationError, type BatchUpdateMessagesRequest, type BatchUpdateResult, BornStaleError, BreadthRequiredError, CONTRACT_MANIFEST, CONTRACT_VERSION, CURRENT_API_VERSION, Categories, type Category, type CategoryPacingState, type CategoryRiskDial, ConflictError, ConnectionError, type ContactListDirection, type ContactListEntry, type ContactListKind, ContactLists, type ContractManifest, type ContractStability, type CreateInboxRequest, type Cursor, DEFAULT_BASE_URL, type DeleteResult, type DiffHunk, type DiffJson, type Domain, type DomainOffboard, type DomainRecord, type DomainScope, Domains, type EffectiveRiskDial, type EmailAddress, type EnrollRequest, type EnrollResponse, type ExtractedCredentials, ExtrovertClient as Extrovert, ExtrovertClient, type ExtrovertClientOptions, ForbiddenScopeError, type ForwardRequest, type GetInboxParams, type GetRuleAuditParams, type GetRulesParams, type GraduationStatus, IdempotencyConflictError, type Inbox, type InboxCredentials, InboxHandle, type InboxInclude, type InboxMetadata, type InboxMetadataPatch, type InboxMetadataValue, type InboxStatus, Inboxes, IntentRequiredError, type IsoTimestamp, type Job, type KeyTier, type List, type ListCategoriesParams, type ListInboxesParams, type ListMessagesParams, ListPage, type ListParams, type ListReviewEventsParams, type ListReviewsParams, type ListSuppressionsParams, type ListThreadsParams, MOCK_BASE_URL, type MailFolder, type MailboxQuickstart, type MailboxQuickstartCall, type MarkReadRequest, type Message, type MessageDirection, Messages, MockBackend, NotFoundError, type OnboardDomainRequest, type OnboardingMode, PROBLEM_CODES, type PacingItem, type Page, type PageFetcher, PaymentRequiredError, PermissionError, type PostReviewChatRequest, type Problem, type ProblemCode, type ProblemField, type ProjectInboxListParams, ProjectInboxes, Projects, type ProposeCategoryRequest, type ProposeGraduationRequest, type QueuedForReviewResult, REVIEW_PROBLEM_RETRYABLE, RateLimitError, RecipientSuppressedError, type RegisterWebhookRequest, type ReplyRequest, type RestampReviewRequest, type Review, ReviewConflictError, type ReviewDecisionContext, type ReviewEvent, type ReviewEventCursor, type ReviewEventReason, ReviewEvents, type ReviewEventsResult, type ReviewFeedback, type ReviewFeedbackComment, type ReviewInclude, type ReviewIntent, type ReviewMode, type ReviewPolicy, type ReviewState, type ReviewTurn, type ReviewerAction, type ReviewerDecisionRequest, type ReviewerDecisionResult, Reviews, type RiskDial, type Rule, type RuleAuditEntry, type RuleLayer, type RuleSnapshot, Rules, SDK_VERSION, type SaveRuleRequest, type ScanBacklogStatus, type Scope, type SearchMessagesParams, SendNeedsReconciliationError, type SendOutcome, type SendRequest, type SendResult, type SentResult, type SignUpRequest, type SignUpResponse, StaleError, type StreamEvent, type StreamOptions, type SubmitForReviewResult, type SubmitRevisionRequest, type SuppressionEntry, type SuppressionPrecheck, type SuppressionScope, type SuppressionSource, Suppressions, TerminalError, type Thread, type ThreadDetail, Threads, TimeoutError, UnavailableError, type UpdateCategoryRequest, type UpdateInboxRequest, type UpdateWebhookRequest, ValidationError, type VerifyRequest, type VerifyResponse, type VerifyWebhookOptions, type WaitForEmailRequest, type WaitForEmailResult, type WaitForReviewEventParams, type Webhook, type WebhookEvent, type WebhookPayload, Webhooks, type WhoAmI, WrongStateError, extractCredentials, extractLink, extractOtp, isProblemCode, isQueuedForReview, isSentImmediately, listPage, parseKeyTier, parseProblem, parseWebhook, reviewIdOf, sentMessageIdOf, serializeInclude, signWebhook, threadIdOf, tierAllowsOrgWildcard, tierNeedsExplicitBreadth, verifyWebhookSignature };

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  * on 429/5xx, honors `Retry-After`, and surfaces every failure as a typed {@link ApiError}.
  */
 /** The library version, surfaced in the User-Agent. Kept in sync with package.json by build. */
-declare const SDK_VERSION = "0.1.0-pre.4";
+declare const SDK_VERSION = "0.1.0-pre.6";
 interface RetryOptions {
     /** Max retry attempts for idempotent requests on 429/5xx/network errors. Default 2. */
     maxRetries: number;
@@ -58,7 +58,7 @@ type IsoTimestamp = string;
  * buy a new domain (`POST /v1/domains` with `mode: "purchased"`). `review:act` gates
  * the BYO reviewer decision plane.
  */
-type Scope = "mailbox:create" | "mailbox:read" | "mailbox:send" | "mailbox:quota" | "mailbox:delete" | "webhook:write" | "domain:manage" | "domain:purchase" | "review:act";
+type Scope = "mailbox:create" | "mailbox:read" | "mailbox:send" | "mailbox:quota" | "mailbox:credentials" | "mailbox:delete" | "webhook:write" | "domain:manage" | "domain:purchase" | "review:act" | "signup:verify";
 /** How a Extrovert domain was onboarded (§7). */
 type OnboardingMode = "shared" | "purchased" | "ns_delegated" | "manual";
 /** Lifecycle status of an agent principal. */
@@ -520,6 +520,8 @@ interface SendRequest {
      * routes to needs_review with gate_outcome `held:low_confidence`.
      */
     category_confidence?: number;
+    /** Opaque token from the fresh getRules call used for this composition. */
+    composition_token?: string;
 }
 /**
  * Request body for the canonical thread-aware reply,
@@ -555,6 +557,7 @@ interface ReplyRequest {
     category_id?: string;
     /** Agent-supplied confidence (0..1); see {@link SendRequest.category_confidence}. */
     category_confidence?: number;
+    composition_token?: string;
 }
 /**
  * Request body for `POST /v1/inboxes/{addr}/messages/{id}/forward`. Re-sends the
@@ -589,6 +592,7 @@ interface ForwardRequest {
     category_id?: string;
     /** Agent-supplied confidence (0..1); see {@link SendRequest.category_confidence}. */
     category_confidence?: number;
+    composition_token?: string;
     /** See {@link SendRequest.idempotency_key} — sent as a header, never in the body. */
     idempotency_key?: string;
 }
@@ -811,6 +815,8 @@ interface SubmitRevisionRequest {
     html?: string;
     built_at?: IsoTimestamp;
     rules_version_seen?: number;
+    /** Opaque token from the fresh getRules call used for this redraft. */
+    composition_token?: string;
     /**
      * REPLACES the draft's attachments. Omit the field to leave them untouched;
      * send an empty array to clear them.
@@ -1185,6 +1191,14 @@ interface GetRulesParams {
     /** Narrow to one layer (general | category). Default returns both. */
     scope?: "general" | "category";
 }
+/** Stable effective rule stack plus an opaque proof for the next composition. */
+interface RuleSnapshot extends Page<Rule> {
+    house_style_version: number;
+    category_rules_version: number;
+    rule_high_water: number;
+    composition_token?: string;
+    composition_token_expires_at?: IsoTimestamp;
+}
 /**
  * Save / edit a writing rule (append-only by supersession; spec §5.4; D11).
  *
@@ -1196,6 +1210,8 @@ interface GetRulesParams {
  * `scope` is the category axis, `rule_layer` is the ownership axis.)
  */
 interface SaveRuleRequest {
+    /** Stable retry key, sent as Idempotency-Key and omitted from the JSON body. */
+    idempotency_key?: string;
     /** Defaults from category_id (general iff empty). */
     scope?: "general" | "category";
     /** Category id (cat_…); empty = house-style/general (D2). */
@@ -1619,13 +1635,13 @@ interface SignUpRequest {
 }
 /**
  * Response from `POST /v1/agent/sign-up`. The `agent_key` is a LIMITED-scope key
- * (read-only) until the emailed code is confirmed via `POST /v1/agent/verify`.
- * The OTP itself is never returned — it is emailed to `human_email`.
+ * (read-only) that expires with the emailed code. Successful verification revokes
+ * it and returns a replacement full-scope key. The OTP itself is never returned.
  */
 interface SignUpResponse {
     customer_id: string;
     agent_id: string;
-    /** Limited-scope agent key, shown once. Re-calling signup rotates it. */
+    /** Limited-scope bootstrap key, shown once and bounded by `otp_expires_at`. */
     agent_key: string;
     key_prefix: string;
     scopes: Scope[];
@@ -1642,17 +1658,40 @@ interface VerifyRequest {
     /** The one-time code delivered to the signup human email. */
     otp: string;
 }
+/** One copy-ready MCP operation in the post-verification mailbox handoff. */
+interface MailboxQuickstartCall {
+    tool: "read_messages" | "get_message" | "wait_for_email";
+    arguments: Record<string, unknown>;
+}
 /**
- * Response from `POST /v1/agent/verify`. On success a NEW full-scope `agent_key`
- * is returned (shown once); switch to it for subsequent calls.
+ * Safe, MCP-first next calls for the inbox returned by signup verification.
+ * SDK callers can use `address` with the typed inbox/message resources instead;
+ * these calls keep agent runtimes from inventing raw HTTP routes or parsers.
+ */
+interface MailboxQuickstart {
+    inbox: string;
+    list_mail: MailboxQuickstartCall;
+    read_message: MailboxQuickstartCall;
+    wait_for_mail: MailboxQuickstartCall;
+}
+/**
+ * Response from `POST /v1/agent/verify`. On success the bootstrap key is revoked
+ * and a NEW full-scope `agent_key` is returned; switch to it for subsequent calls.
+ * `address` repeats the ready inbox so the handoff remains self-contained after
+ * a process restart or context compaction.
  */
 interface VerifyResponse {
     agent_id: string;
     agent_key: string;
     key_prefix: string;
     scopes: Scope[];
+    /** The signup inbox, ready for immediate list/read/wait/send operations. */
+    address: string;
     verified: boolean;
     message: string;
+    mailbox_quickstart: MailboxQuickstart;
+    /** One-time email-bound owner claim for the human console, when freshly seeded. */
+    org_claim_token?: string;
 }
 /**
  * Response from `GET /v1/auth/me` — the verified principal behind the key.
@@ -1840,7 +1879,7 @@ interface Transport {
     proposeGraduation(categoryId: string, req: ProposeGraduationRequest, signal?: AbortSignal): Promise<GraduationStatus>;
     getScanBacklogStatus(categoryId: string, signal?: AbortSignal): Promise<ScanBacklogStatus>;
     getCategoryPacingState(categoryId: string, signal?: AbortSignal): Promise<CategoryPacingState>;
-    getRules(params: GetRulesParams, signal?: AbortSignal): Promise<Page<Rule>>;
+    getRules(params: GetRulesParams, signal?: AbortSignal): Promise<RuleSnapshot>;
     saveRule(req: SaveRuleRequest, signal?: AbortSignal): Promise<Rule>;
     promoteRule(ruleId: string, toScope: "general" | "category", signal?: AbortSignal): Promise<Rule>;
     retireRule(ruleId: string, signal?: AbortSignal): Promise<Rule>;
@@ -2059,7 +2098,7 @@ declare class MockBackend {
     /** rank a rule for the §7 ladder (mock mirror of the server's deterministic order). */
     private ruleRank;
     /** Get the ORDERED active rule set (mock) — §7 ladder + category-before-general. */
-    getRules(params?: GetRulesParams): Page<Rule>;
+    getRules(params?: GetRulesParams): RuleSnapshot;
     /** Save / edit a rule (mock) — append-only by supersession (D11). */
     saveRule(req: SaveRuleRequest): Rule;
     /** Promote a rule between layers (mock, via supersession), or undefined when unknown. */
@@ -2976,7 +3015,7 @@ declare class Rules {
     private readonly ctx;
     constructor(ctx: ResourceContext);
     /** Get the ORDERED active rule set (precedence ladder applied; NO LLM). */
-    get(params?: GetRulesParams, signal?: AbortSignal): Promise<Page<Rule>>;
+    get(params?: GetRulesParams, signal?: AbortSignal): Promise<RuleSnapshot>;
     /**
      * Save / edit a rule (append-only by supersession; D11). An agent-plane save is
      * ALWAYS project-layer: the saved rule's `rule_layer` is `project`, bound to the
@@ -3103,11 +3142,17 @@ declare class ExtrovertClient {
      * + a first inbox and returns a LIMITED-scope (read-only) agent key; a one-time
      * code is emailed to `human_email`. Call {@link verify} with the code to unlock
      * full scopes. Idempotent on `human_email`: re-calling rotates the key + resends.
+     * When free signup is paused, this throws an `ApiError` with status 403 and
+     * code `signup_disabled` without creating account state.
      */
     signUp(req: SignUpRequest, signal?: AbortSignal): Promise<SignUpResponse>;
     /**
      * Confirm the emailed signup code and receive a NEW full-scope agent key (shown
      * once). Must be called with the limited key from {@link signUp} as the bearer.
+     * The result repeats the ready inbox address and includes MCP-first list/read/wait
+     * calls; SDK callers can pass `address` directly to `inboxes` and `messages`.
+     * Pending verification is also fail-closed with 403 `signup_disabled` while
+     * free signup is paused.
      */
     verify(req: VerifyRequest, signal?: AbortSignal): Promise<VerifyResponse>;
     /** Introspect the principal behind the current key (`GET /v1/auth/me`). */
@@ -3674,7 +3719,7 @@ declare function signWebhook(secret: string, body: string, timestampSeconds: num
  *
  * ## Provisional, pre-1.0 (0.x)
  *
- * {@link CONTRACT_VERSION} is **`0.1.0-pre.4`** — a deliberately **provisional**, pre-1.0
+ * {@link CONTRACT_VERSION} is **`0.1.0-pre.6`** — a deliberately **provisional**, pre-1.0
  * contract. It is open and documented, but it MAY still evolve before 1.0: there
  * are no external users yet, and the **D20 shared-pool auto-send governor** is a
  * hard prerequisite before onboarding external users. Pin the version; expect
@@ -3731,12 +3776,12 @@ interface DiffJson {
 /**
  * The published version of the Extrovert Review-Loop open contract (D14).
  *
- * **`0.1.0-pre.4` — PROVISIONAL, pre-1.0.** Versioned *with the SDK* (this package's
+ * **`0.1.0-pre.6` — PROVISIONAL, pre-1.0.** Versioned *with the SDK* (this package's
  * `package.json` version) and aligned to the openapi `info.version`. Open and
  * documented, but MAY still evolve before 1.0 (no external users yet; the D20
  * shared-pool governor is required before external users). Pin it.
  */
-declare const CONTRACT_VERSION: "0.1.0-pre.4";
+declare const CONTRACT_VERSION: "0.1.0-pre.6";
 /** The stability posture of a published contract version. */
 type ContractStability = "provisional" | "stable";
 /**
@@ -3779,4 +3824,4 @@ interface ContractManifest {
  */
 declare const CONTRACT_MANIFEST: ContractManifest;
 
-export { API_VERSION_HEADER, type AccountRiskDial, type AckReviewEventEntry, type AckReviewEventRequest, type AckReviewEventResult, type AddContactListRequest, type Agent, type AgentStatus, ApiError, type ApiErrorBody, type Attachment, type AttachmentDownload, type AttachmentInput, AuthenticationError, type BatchUpdateMessagesRequest, type BatchUpdateResult, BornStaleError, BreadthRequiredError, CONTRACT_MANIFEST, CONTRACT_VERSION, CURRENT_API_VERSION, Categories, type Category, type CategoryPacingState, type CategoryRiskDial, ConflictError, ConnectionError, type ContactListDirection, type ContactListEntry, type ContactListKind, ContactLists, type ContractManifest, type ContractStability, type CreateInboxRequest, type Cursor, DEFAULT_BASE_URL, type DeleteResult, type DiffHunk, type DiffJson, type Domain, type DomainOffboard, type DomainRecord, type DomainScope, Domains, type EffectiveRiskDial, type EmailAddress, type EnrollRequest, type EnrollResponse, type ExtractedCredentials, ExtrovertClient as Extrovert, ExtrovertClient, type ExtrovertClientOptions, ForbiddenScopeError, type ForwardRequest, type GetInboxParams, type GetRuleAuditParams, type GetRulesParams, type GraduationStatus, IdempotencyConflictError, type Inbox, type InboxCredentials, InboxHandle, type InboxInclude, type InboxMetadata, type InboxMetadataPatch, type InboxMetadataValue, type InboxStatus, Inboxes, IntentRequiredError, type IsoTimestamp, type Job, type KeyTier, type List, type ListCategoriesParams, type ListInboxesParams, type ListMessagesParams, ListPage, type ListParams, type ListReviewEventsParams, type ListReviewsParams, type ListSuppressionsParams, type ListThreadsParams, MOCK_BASE_URL, type MailFolder, type MarkReadRequest, type Message, type MessageDirection, Messages, MockBackend, NotFoundError, type OnboardDomainRequest, type OnboardingMode, PROBLEM_CODES, type PacingItem, type Page, type PageFetcher, PaymentRequiredError, PermissionError, type PostReviewChatRequest, type Problem, type ProblemCode, type ProblemField, type ProjectInboxListParams, ProjectInboxes, Projects, type ProposeCategoryRequest, type ProposeGraduationRequest, type QueuedForReviewResult, REVIEW_PROBLEM_RETRYABLE, RateLimitError, RecipientSuppressedError, type RegisterWebhookRequest, type ReplyRequest, type RestampReviewRequest, type Review, ReviewConflictError, type ReviewDecisionContext, type ReviewEvent, type ReviewEventCursor, type ReviewEventReason, ReviewEvents, type ReviewEventsResult, type ReviewFeedback, type ReviewFeedbackComment, type ReviewInclude, type ReviewIntent, type ReviewMode, type ReviewPolicy, type ReviewState, type ReviewTurn, type ReviewerAction, type ReviewerDecisionRequest, type ReviewerDecisionResult, Reviews, type RiskDial, type Rule, type RuleAuditEntry, type RuleLayer, Rules, SDK_VERSION, type SaveRuleRequest, type ScanBacklogStatus, type Scope, type SearchMessagesParams, SendNeedsReconciliationError, type SendOutcome, type SendRequest, type SendResult, type SentResult, type SignUpRequest, type SignUpResponse, StaleError, type StreamEvent, type StreamOptions, type SubmitForReviewResult, type SubmitRevisionRequest, type SuppressionEntry, type SuppressionPrecheck, type SuppressionScope, type SuppressionSource, Suppressions, TerminalError, type Thread, type ThreadDetail, Threads, TimeoutError, UnavailableError, type UpdateCategoryRequest, type UpdateInboxRequest, type UpdateWebhookRequest, ValidationError, type VerifyRequest, type VerifyResponse, type VerifyWebhookOptions, type WaitForEmailRequest, type WaitForEmailResult, type WaitForReviewEventParams, type Webhook, type WebhookEvent, type WebhookPayload, Webhooks, type WhoAmI, WrongStateError, extractCredentials, extractLink, extractOtp, isProblemCode, isQueuedForReview, isSentImmediately, listPage, parseKeyTier, parseProblem, parseWebhook, reviewIdOf, sentMessageIdOf, serializeInclude, signWebhook, threadIdOf, tierAllowsOrgWildcard, tierNeedsExplicitBreadth, verifyWebhookSignature };
+export { API_VERSION_HEADER, type AccountRiskDial, type AckReviewEventEntry, type AckReviewEventRequest, type AckReviewEventResult, type AddContactListRequest, type Agent, type AgentStatus, ApiError, type ApiErrorBody, type Attachment, type AttachmentDownload, type AttachmentInput, AuthenticationError, type BatchUpdateMessagesRequest, type BatchUpdateResult, BornStaleError, BreadthRequiredError, CONTRACT_MANIFEST, CONTRACT_VERSION, CURRENT_API_VERSION, Categories, type Category, type CategoryPacingState, type CategoryRiskDial, ConflictError, ConnectionError, type ContactListDirection, type ContactListEntry, type ContactListKind, ContactLists, type ContractManifest, type ContractStability, type CreateInboxRequest, type Cursor, DEFAULT_BASE_URL, type DeleteResult, type DiffHunk, type DiffJson, type Domain, type DomainOffboard, type DomainRecord, type DomainScope, Domains, type EffectiveRiskDial, type EmailAddress, type EnrollRequest, type EnrollResponse, type ExtractedCredentials, ExtrovertClient as Extrovert, ExtrovertClient, type ExtrovertClientOptions, ForbiddenScopeError, type ForwardRequest, type GetInboxParams, type GetRuleAuditParams, type GetRulesParams, type GraduationStatus, IdempotencyConflictError, type Inbox, type InboxCredentials, InboxHandle, type InboxInclude, type InboxMetadata, type InboxMetadataPatch, type InboxMetadataValue, type InboxStatus, Inboxes, IntentRequiredError, type IsoTimestamp, type Job, type KeyTier, type List, type ListCategoriesParams, type ListInboxesParams, type ListMessagesParams, ListPage, type ListParams, type ListReviewEventsParams, type ListReviewsParams, type ListSuppressionsParams, type ListThreadsParams, MOCK_BASE_URL, type MailFolder, type MailboxQuickstart, type MailboxQuickstartCall, type MarkReadRequest, type Message, type MessageDirection, Messages, MockBackend, NotFoundError, type OnboardDomainRequest, type OnboardingMode, PROBLEM_CODES, type PacingItem, type Page, type PageFetcher, PaymentRequiredError, PermissionError, type PostReviewChatRequest, type Problem, type ProblemCode, type ProblemField, type ProjectInboxListParams, ProjectInboxes, Projects, type ProposeCategoryRequest, type ProposeGraduationRequest, type QueuedForReviewResult, REVIEW_PROBLEM_RETRYABLE, RateLimitError, RecipientSuppressedError, type RegisterWebhookRequest, type ReplyRequest, type RestampReviewRequest, type Review, ReviewConflictError, type ReviewDecisionContext, type ReviewEvent, type ReviewEventCursor, type ReviewEventReason, ReviewEvents, type ReviewEventsResult, type ReviewFeedback, type ReviewFeedbackComment, type ReviewInclude, type ReviewIntent, type ReviewMode, type ReviewPolicy, type ReviewState, type ReviewTurn, type ReviewerAction, type ReviewerDecisionRequest, type ReviewerDecisionResult, Reviews, type RiskDial, type Rule, type RuleAuditEntry, type RuleLayer, type RuleSnapshot, Rules, SDK_VERSION, type SaveRuleRequest, type ScanBacklogStatus, type Scope, type SearchMessagesParams, SendNeedsReconciliationError, type SendOutcome, type SendRequest, type SendResult, type SentResult, type SignUpRequest, type SignUpResponse, StaleError, type StreamEvent, type StreamOptions, type SubmitForReviewResult, type SubmitRevisionRequest, type SuppressionEntry, type SuppressionPrecheck, type SuppressionScope, type SuppressionSource, Suppressions, TerminalError, type Thread, type ThreadDetail, Threads, TimeoutError, UnavailableError, type UpdateCategoryRequest, type UpdateInboxRequest, type UpdateWebhookRequest, ValidationError, type VerifyRequest, type VerifyResponse, type VerifyWebhookOptions, type WaitForEmailRequest, type WaitForEmailResult, type WaitForReviewEventParams, type Webhook, type WebhookEvent, type WebhookPayload, Webhooks, type WhoAmI, WrongStateError, extractCredentials, extractLink, extractOtp, isProblemCode, isQueuedForReview, isSentImmediately, listPage, parseKeyTier, parseProblem, parseWebhook, reviewIdOf, sentMessageIdOf, serializeInclude, signWebhook, threadIdOf, tierAllowsOrgWildcard, tierNeedsExplicitBreadth, verifyWebhookSignature };

package/dist/index.js

@@ -266,7 +266,7 @@ var CURRENT_API_VERSION = "2026-06-23";
 var API_VERSION_HEADER = "Extrovert-Version";
 
 // src/http.ts
-var SDK_VERSION = "0.1.0-pre.4";
+var SDK_VERSION = "0.1.0-pre.6";
 function buildUrl(baseUrl, path, query) {
   const base = baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
   const rel = path.startsWith("/") ? path : `/${path}`;
@@ -623,6 +623,23 @@ function decodeMockCursor(cursor) {
     return 0;
   }
 }
+function mailboxQuickstart(address) {
+  return {
+    inbox: address,
+    list_mail: {
+      tool: "read_messages",
+      arguments: { inbox: address, limit: 20, unread_only: false }
+    },
+    read_message: {
+      tool: "get_message",
+      arguments: { id: "<message_id from read_messages>", format: "text", variant: "extracted" }
+    },
+    wait_for_mail: {
+      tool: "wait_for_email",
+      arguments: { inbox: address, since_now: true }
+    }
+  };
+}
 var SHARED_SUBDOMAIN = "smtp.extrovert.dev";
 var MOCK_ORG_ID = "org_mock";
 var MOCK_PROJECT_ID = "prj_mock";
@@ -933,14 +950,14 @@ var MockBackend = class {
     const customerId = existing?.customerId ?? `cus_pn_signup_${rid("c").slice(2)}`;
     const agentId = existing?.agentId ?? rid("agt");
     const address = existing?.address ?? `${req.username ?? randomHandle()}@smtp.extrovert.dev`;
-    const otp = String(Math.floor(1e5 + Math.random() * 9e5));
+    const otp = "492013";
     this.state.signupByEmail.set(email, { customerId, agentId, address, otp, verified: false });
     return {
       customer_id: customerId,
       agent_id: agentId,
       agent_key: `pk_agent_${agentId.slice(4)}_${rid("sk").slice(3)}`,
       key_prefix: `pk_agent_${agentId.slice(4, 8)}`,
-      scopes: ["mailbox:read"],
+      scopes: ["signup:verify"],
       address,
       verified: false,
       otp_sent_to: email,
@@ -958,8 +975,10 @@ var MockBackend = class {
           agent_key: `pk_agent_${s.agentId.slice(4)}_${rid("sk").slice(3)}`,
           key_prefix: `pk_agent_${s.agentId.slice(4, 8)}`,
           scopes: ["mailbox:create", "mailbox:read", "mailbox:send"],
+          address: s.address,
           verified: true,
-          message: "Verified. Use the new agent_key (full scopes)."
+          message: "Verified. The inbox is ready; use read_messages, then get_message with a returned message id.",
+          mailbox_quickstart: mailboxQuickstart(s.address)
         };
       }
     }
@@ -1969,7 +1988,15 @@ var MockBackend = class {
       category = active.filter((r) => r.scope === "category" && r.category_id === params.category_id).sort(byRank);
     }
     const items = [...category, ...general];
-    return { items, total: items.length };
+    return {
+      items,
+      total: items.length,
+      house_style_version: 1,
+      category_rules_version: params.category_id ? 1 : 0,
+      rule_high_water: params.category_id ? 1 : 0,
+      composition_token: params.scope ? void 0 : `cmp_fixture_${params.category_id ?? "general"}`,
+      composition_token_expires_at: params.scope ? void 0 : new Date(Date.now() + 6e5).toISOString()
+    };
   }
   /** Save / edit a rule (mock) — append-only by supersession (D11). */
   saveRule(req) {
@@ -3577,7 +3604,13 @@ var HttpTransport = class {
     });
   }
   saveRule(req, signal) {
-    return this.call({ method: "PUT", path: "/v1/rules", body: req, signal });
+    return this.call({
+      method: "PUT",
+      path: "/v1/rules",
+      body: withoutIdempotencyKey(req),
+      idempotencyKey: req.idempotency_key,
+      signal
+    });
   }
   promoteRule(ruleId, toScope, signal) {
     return this.call({
@@ -4974,6 +5007,8 @@ var ExtrovertClient = class _ExtrovertClient {
    * + a first inbox and returns a LIMITED-scope (read-only) agent key; a one-time
    * code is emailed to `human_email`. Call {@link verify} with the code to unlock
    * full scopes. Idempotent on `human_email`: re-calling rotates the key + resends.
+   * When free signup is paused, this throws an `ApiError` with status 403 and
+   * code `signup_disabled` without creating account state.
    */
   signUp(req, signal) {
     return this.transport.signUp(req, signal);
@@ -4981,6 +5016,10 @@ var ExtrovertClient = class _ExtrovertClient {
   /**
    * Confirm the emailed signup code and receive a NEW full-scope agent key (shown
    * once). Must be called with the limited key from {@link signUp} as the bearer.
+   * The result repeats the ready inbox address and includes MCP-first list/read/wait
+   * calls; SDK callers can pass `address` directly to `inboxes` and `messages`.
+   * Pending verification is also fail-closed with 403 `signup_disabled` while
+   * free signup is paused.
    */
   verify(req, signal) {
     return this.transport.verify(req, signal);
@@ -5148,7 +5187,7 @@ async function signWebhook(secret, body, timestampSeconds) {
 }
 
 // src/contract.ts
-var CONTRACT_VERSION = "0.1.0-pre.4";
+var CONTRACT_VERSION = "0.1.0-pre.6";
 var CONTRACT_MANIFEST = {
   name: "extrovert.review-loop",
   version: CONTRACT_VERSION,