@extrovert.dev/mcp 0.1.0-pre.5 → 0.1.0-pre.6

package/dist/tools.js

@@ -12,6 +12,7 @@
  * an org-wide master key. `redeem_enrollment` lets an agent exchange a
  * single-use enrollment token for that scoped key at runtime.
  */
+import { createHash } from "node:crypto";
 import { z } from "zod/v4";
 import { ExtrovertApiError } from "./client.js";
 import { isTerminalReviewEvent } from "./types.js";
@@ -454,9 +455,12 @@ const signUp = defineTool({
     name: "sign_up",
     title: "Sign up for a free account",
     description: "Grab a free Extrovert account in one call (no enrollment token needed). Provisions a tenant and a first inbox, then " +
-        "emails a one-time verification code to your human_email. Returns a LIMITED (read-only) agent key that this " +
+        "emails a one-time verification code to your human_email. Returns a LIMITED verification-only agent key that " +
+        "cannot read or send mail and that this " +
         "MCP session keeps only through verify_signup; it expires with the code and is revoked after verification. " +
-        "Re-calling with the same human_email rotates the bootstrap key and resends the code.",
+        "Re-calling with the same human_email rotates the bootstrap key and resends the code. Free signup may be " +
+        "temporarily paused; in that state the tool " +
+        "returns signup_disabled and creates nothing. Enrollment tokens remain available.",
     inputSchema: {
         human_email: emailAddress.describe("Your email — receives the one-time verification code."),
         username: z
@@ -486,7 +490,9 @@ const verifySignup = defineTool({
     title: "Verify signup code",
     description: "Confirm the one-time code emailed by sign_up. On success the bootstrap key is revoked and you receive a NEW " +
         "full-scope agent key (create/read/send/webhooks). This MCP session switches to it automatically. The packaged " +
-        "local stdio server also stores it in its permission-restricted credential file for future sessions.",
+        "local stdio server also stores it in its permission-restricted credential file for future sessions. Pending " +
+        "signup verification returns signup_disabled while free signup is temporarily paused; keep the limited key and " +
+        "retry after reopening.",
     inputSchema: {
         otp: z.string().min(4).max(12).describe("The verification code from your signup email."),
     },
@@ -681,6 +687,7 @@ const exportEmailConfig = defineTool({
     name: "export_email_config",
     title: "Export email client config",
     description: "Export an inbox's IMAP/SMTP server settings + login so you can configure a real mail client (e.g. Himalaya). " +
+        "Requires the dedicated mailbox:credentials scope and a paid plan; free accounts cannot export raw credentials. " +
         "Direct SMTP is an explicit unreviewed delivery path: it bypasses Extrovert approval/review, suppression and " +
         "contact-list enforcement, List-Unsubscribe injection, and Extrovert billing/accounting. API/MCP sends keep those " +
         "controls. Returns a ready-to-use config; use format=json for raw connection fields.",
@@ -781,6 +788,7 @@ const sendEmail = defineTool({
             .describe("Your confidence (0..1) in the category match. Feeds the min_confidence auto-send gate ONLY; " +
             "the server never scores. Below the threshold (or omitted when one is set) the would-be auto-send " +
             "routes to needs_review (gate_outcome held:low_confidence)."),
+        composition_token: z.string().min(1).optional().describe("Token returned by the fresh get_rules call used to compose this message. The MCP refreshes it when omitted for compatibility."),
         client_id: z
             .string()
             .min(1)
@@ -790,6 +798,9 @@ const sendEmail = defineTool({
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     handler: async (args, { client }) => {
+        const compositionToken = args.composition_token ?? (await client.getRules({ category_id: args.category_id })).composition_token;
+        if (!compositionToken)
+            throw new ExtrovertApiError("Call get_rules without a scope filter before composing.", 422, "composition_token_required");
         // Review Loop overload: any of mode/intent/category_id opts into the richer
         // discriminated response. It does NOT decide whether a human sees the message —
         // the policy does that either way; this only shapes what comes back.
@@ -813,6 +824,7 @@ const sendEmail = defineTool({
                 intent: args.intent,
                 category_id: args.category_id,
                 category_confidence: args.category_confidence,
+                composition_token: compositionToken,
                 client_id: args.client_id,
             });
             return ok(renderSubmitResult(result), result);
@@ -828,6 +840,7 @@ const sendEmail = defineTool({
             reply_to: args.reply_to,
             headers: args.headers,
             attachments: args.attachments,
+            composition_token: compositionToken,
             client_id: args.client_id,
         });
         return ok(renderSendOutcome("Sent", result), result);
@@ -878,6 +891,7 @@ const replyEmail = defineTool({
             .max(1)
             .optional()
             .describe("Your confidence (0..1) in the category match. Feeds the min_confidence auto-send gate only."),
+        composition_token: z.string().min(1).optional().describe("Token returned by the fresh get_rules call used to compose this reply. The MCP refreshes it when omitted for compatibility."),
         client_id: z
             .string()
             .min(1)
@@ -890,6 +904,9 @@ const replyEmail = defineTool({
         if (!args.thread_id && !args.message_id) {
             throw new ExtrovertApiError("Provide thread_id or message_id to reply.", 400, "invalid_argument");
         }
+        const compositionToken = args.composition_token ?? (await client.getRules({ category_id: args.category_id })).composition_token;
+        if (!compositionToken)
+            throw new ExtrovertApiError("Call get_rules without a scope filter before composing.", 422, "composition_token_required");
         // Review Loop overload: any of mode/intent/category_id opts into review.
         if (args.mode !== undefined || args.intent !== undefined || args.category_id !== undefined) {
             const result = await client.submitReplyForReview({
@@ -908,6 +925,7 @@ const replyEmail = defineTool({
                 intent: args.intent,
                 category_id: args.category_id,
                 category_confidence: args.category_confidence,
+                composition_token: compositionToken,
                 client_id: args.client_id,
             });
             return ok(renderSubmitResult(result), result);
@@ -924,6 +942,7 @@ const replyEmail = defineTool({
             headers: args.headers,
             reply_all: args.reply_all,
             attachments: args.attachments,
+            composition_token: compositionToken,
             client_id: args.client_id,
         });
         return ok(renderSendOutcome("Replied", res), res);
@@ -968,6 +987,7 @@ const forwardEmail = defineTool({
             .max(1)
             .optional()
             .describe("Your confidence (0..1) in the category match. Feeds the min_confidence auto-send gate only."),
+        composition_token: z.string().min(1).optional().describe("Token returned by the fresh get_rules call used to compose this forward. The MCP refreshes it when omitted for compatibility."),
         client_id: z
             .string()
             .min(1)
@@ -977,6 +997,9 @@ const forwardEmail = defineTool({
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     handler: async (args, { client }) => {
+        const compositionToken = args.composition_token ?? (await client.getRules({ category_id: args.category_id })).composition_token;
+        if (!compositionToken)
+            throw new ExtrovertApiError("Call get_rules without a scope filter before composing.", 422, "composition_token_required");
         // Same opt-in predicate as send/reply: mode/intent/category_id select the
         // richer discriminated response; the policy governs the routing regardless.
         if (args.mode !== undefined || args.intent !== undefined || args.category_id !== undefined) {
@@ -992,6 +1015,7 @@ const forwardEmail = defineTool({
                 intent: args.intent,
                 category_id: args.category_id,
                 category_confidence: args.category_confidence,
+                composition_token: compositionToken,
                 client_id: args.client_id,
             });
             return ok(renderSubmitResult(result), result);
@@ -1004,6 +1028,7 @@ const forwardEmail = defineTool({
             bcc: args.bcc,
             text: args.text,
             html: args.html,
+            composition_token: compositionToken,
             client_id: args.client_id,
         });
         return ok(renderSendOutcome("Forwarded", res), res);
@@ -1237,6 +1262,7 @@ const submitRevision = defineTool({
             "redraft could never restore a file the human reviewed the message with."),
         built_at: z.string().optional().describe("When you built this draft (informational)."),
         rules_version_seen: z.number().int().optional().describe("Rule high-water this draft was composed against (born-stale basis)."),
+        composition_token: z.string().min(1).optional().describe("Token returned by the fresh get_rules call used to compose this revision. The MCP refreshes it when omitted for compatibility."),
         client_id: z
             .string()
             .min(1)
@@ -1246,6 +1272,10 @@ const submitRevision = defineTool({
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     handler: async (args, { client }) => {
+        const currentReview = await client.getReview(args.id);
+        const compositionToken = args.composition_token ?? (await client.getRules({ category_id: currentReview.category_id })).composition_token;
+        if (!compositionToken)
+            throw new ExtrovertApiError("Call get_rules without a scope filter before redrafting.", 422, "composition_token_required");
         const review = await client.submitRevision({
             id: args.id,
             parent_revision: args.parent_revision,
@@ -1257,6 +1287,7 @@ const submitRevision = defineTool({
             attachments: args.attachments,
             built_at: args.built_at,
             rules_version_seen: args.rules_version_seen,
+            composition_token: compositionToken,
             client_id: args.client_id,
         });
         return ok(`Revised.\n${renderReview(review)}`, review);
@@ -1556,6 +1587,11 @@ const getRules = defineTool({
         return ok(`${res.items.length} rule(s), highest precedence first.\n\n${text}`, {
             items: res.items,
             total: res.total,
+            house_style_version: res.house_style_version,
+            category_rules_version: res.category_rules_version,
+            rule_high_water: res.rule_high_water,
+            composition_token: res.composition_token,
+            composition_token_expires_at: res.composition_token_expires_at,
         });
     },
 });
@@ -1570,6 +1606,7 @@ const saveRule = defineTool({
         "lineage, the prior superseded). Use this AFTER you judge a diff/comment is a generalizable rule (the judgment is " +
         "yours; we never run an LLM). Returns the new active rule (with its rule_layer/org_id/project_id).",
     inputSchema: {
+        client_id: z.string().min(1).max(128).optional().describe("Stable retry id for this exact rule save; reuse it after a timeout. The MCP derives one when omitted."),
         rule_text: z.string().min(1).describe("The rule body, e.g. 'no em-dashes' or 'be more pushy, we need MRR'."),
         category_id: z.string().optional().describe("Category id (cat_…). Empty = house-style/general (D2)."),
         scope: z.enum(RULE_SCOPES).optional().describe("Defaults from category_id (general iff empty)."),
@@ -1591,9 +1628,11 @@ const saveRule = defineTool({
             .optional()
             .describe("Override the propagate batch (0 = base 3, bounded by rework_batch_max). Never fans one nudge to the whole queue."),
     },
-    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
+    annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true },
     handler: async (args, { client }) => {
+        const derivedClientID = `rule:${createHash("sha256").update(JSON.stringify(args)).digest("hex")}`;
         const rule = await client.saveRule({
+            client_id: args.client_id ?? derivedClientID,
             rule_text: args.rule_text,
             category_id: args.category_id,
             scope: args.scope,