@extrovert.dev/mcp 0.1.0-pre.4 → 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";
@@ -436,6 +437,7 @@ const redeemEnrollment = defineTool({
             agent_handle: args.agent_handle,
             client_id: args.client_id,
         });
+        const persistence = client.credentialPersistenceStatus();
         const text = [
             `Enrollment redeemed. Agent ${result.agent_id} is ready.`,
             `agent_key (shown once): ${result.agent_key}`,
@@ -444,7 +446,7 @@ const redeemEnrollment = defineTool({
             // whoami call — consistent with whoami's text.
             `org: ${result.org_id || "(none)"} · project: ${result.project_id || "(none)"} (fixed — bound to this key)`,
             `scopes: ${result.scopes.join(", ") || "(none)"}`,
-            "This MCP session will use the returned key. Store the complete returned agent_key as EXTROVERT_API_KEY for future sessions; it is not retrievable again.",
+            credentialPersistenceMessage(persistence),
         ].join("\n");
         return ok(text, result);
     },
@@ -453,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 " +
-        "MCP session keeps for verify_signup; store it as EXTROVERT_API_KEY for future sessions. Re-calling with the same " +
-        "human_email rotates the key and resends the code.",
+        "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. 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
@@ -473,7 +478,9 @@ const signUp = defineTool({
             `inbox: ${res.address}`,
             `agent_key (limited, shown once): ${res.agent_key}`,
             `scopes: ${res.scopes.join(", ")}`,
-            `This MCP session will use the limited key. Call verify_signup with the code to unlock full scopes; store the key as EXTROVERT_API_KEY for future sessions if needed.`,
+            `expires: ${res.otp_expires_at}`,
+            `This MCP session will use the limited key until verify_signup atomically exchanges it for the durable key. Do not store this bootstrap key for long-term use.`,
+            `After verification, verify_signup repeats the inbox and returns exact read_messages / get_message / wait_for_email calls so mailbox use can continue without raw HTTP.`,
         ].join("\n");
         return ok(text, res);
     },
@@ -481,22 +488,43 @@ const signUp = defineTool({
 const verifySignup = defineTool({
     name: "verify_signup",
     title: "Verify signup code",
-    description: "Confirm the one-time code emailed by sign_up. On success you receive a NEW full-scope agent key (create/read/send) — " +
-        "this MCP session switches to it automatically. Store it as EXTROVERT_API_KEY for future sessions.",
+    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. 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."),
     },
     annotations: { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     handler: async (args, { client }) => {
         const res = await client.verify({ otp: args.otp });
+        const quick = res.mailbox_quickstart;
+        const persistence = client.credentialPersistenceStatus();
         const text = [
             `Verified. ${res.message}`,
             `agent_key (full, shown once): ${res.agent_key}`,
             `scopes: ${res.scopes.join(", ")}`,
+            credentialPersistenceMessage(persistence),
+            `mailbox ready: ${res.address}`,
+            `First call: ${quick.list_mail.tool} ${JSON.stringify(quick.list_mail.arguments)}`,
+            `Read one result: ${quick.read_message.tool} ${JSON.stringify(quick.read_message.arguments)}`,
+            `Wait for new mail: ${quick.wait_for_mail.tool} ${JSON.stringify(quick.wait_for_mail.arguments)}`,
+            `These tools return readable text plus structured message fields; do not download raw responses or invoke jq for ordinary mailbox work.`,
+            `For outbound mail, use send_email or reply_email through the review workflow; read get_inbox first to see the effective review policy.`,
         ].join("\n");
         return ok(text, res);
     },
 });
+function credentialPersistenceMessage(status) {
+    if (status.persisted) {
+        return `Credential saved for future local sessions${status.location ? ` at ${status.location}` : ""}.`;
+    }
+    if (status.attempted) {
+        return `Automatic credential storage failed${status.error ? `: ${status.error}` : ""}. Store the complete returned agent_key now; it is not retrievable again.`;
+    }
+    return "This host did not provide durable credential storage. Store the complete returned agent_key now; it is not retrievable again.";
+}
 const whoami = defineTool({
     name: "whoami",
     title: "Who am I",
@@ -659,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.",
@@ -759,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)
@@ -768,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.
@@ -791,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);
@@ -806,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);
@@ -856,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)
@@ -868,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({
@@ -886,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);
@@ -902,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);
@@ -946,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)
@@ -955,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) {
@@ -970,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);
@@ -982,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);
@@ -1215,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)
@@ -1224,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,
@@ -1235,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);
@@ -1534,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,
         });
     },
 });
@@ -1548,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)."),
@@ -1569,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,