@hyperstar/mcp 0.1.12 → 0.1.14

package/README.md

@@ -5,6 +5,9 @@ workflows. It exposes scoped creator search, campaign roster, bulk email, and
 inbox tools for MCP clients using either a service-account key or local browser
 CLI login.
 
+For first-tester setup, MCP client snippets, and safe starter prompts, use the
+[headless agent quickstart](https://github.com/Hyperstar-org/backend/blob/main/docs/headless-agent-quickstart.md).
+
 ## Install
 
 Run the MCP server directly from npm:
@@ -120,6 +123,7 @@ where the next step is deterministic, `next_tool` and `next_arguments`.
 - `start_bulk_email`
 - `get_bulk_email_job`
 - `list_inbox_threads`
+- `get_inbox_thread_messages`
 - `get_inbox_aggregates`
 - `update_inbox_thread_state`
 - `send_inbox_reply`
@@ -146,8 +150,13 @@ It also exposes matching prompts:
 npm install
 npm test
 npm run build
+npm run smoke:npm
 ```
 
+`npm run smoke:npm` verifies the published npm package can be resolved and that
+both package binaries print help without requiring local build artifacts,
+authentication, or real workflow API calls.
+
 ## Examples
 
 Search creators:
@@ -263,7 +272,21 @@ and the user has authorized the send:
 }
 ```
 
-Reply to an inbox thread. This performs a real send:
+Read a full inbox thread before replying:
+
+```json
+{
+  "tool": "get_inbox_thread_messages",
+  "arguments": {
+    "platform": "tiktok",
+    "thread_id": 456
+  }
+}
+```
+
+Reply to an inbox thread. This performs a real send. Only call this after the
+user has authorized the reply and the agent has reviewed the full message
+history:
 
 ```json
 {
@@ -273,7 +296,8 @@ Reply to an inbox thread. This performs a real send:
     "thread_id": 456,
     "subject": "Re: Partnership idea",
     "body_text": "Thanks for the reply. Here are the next details.",
-    "idempotency_key": "thread-456-reply-2026-07-09"
+    "idempotency_key": "thread-456-reply-2026-07-09",
+    "send_confirmation": "user_authorized"
   }
 }
 ```

package/dist/inbox-tool-registration.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type HyperstarToolHandlers } from "./tool-inputs.js";
+/** Register inbox-focused Hyperstar MCP tools. */
+export declare function registerInboxTools(server: McpServer, handlers: HyperstarToolHandlers): void;

package/dist/inbox-tool-registration.js

@@ -0,0 +1,31 @@
+import { TOOL_DESCRIPTIONS } from "./tool-descriptions.js";
+import { GetInboxThreadMessagesInputSchema, InboxFiltersInputSchema, ListInboxThreadsInputSchema, SendInboxReplyInputSchema, UpdateInboxThreadStateInputSchema, } from "./tool-inputs.js";
+import { toolResult } from "./tool-result.js";
+/** Register inbox-focused Hyperstar MCP tools. */
+export function registerInboxTools(server, handlers) {
+    server.registerTool("list_inbox_threads", {
+        title: "List Inbox Threads",
+        description: TOOL_DESCRIPTIONS.listInboxThreads,
+        inputSchema: ListInboxThreadsInputSchema,
+    }, async (input) => toolResult(await handlers.listInboxThreads(input)));
+    server.registerTool("get_inbox_thread_messages", {
+        title: "Get Inbox Thread Messages",
+        description: TOOL_DESCRIPTIONS.getInboxThreadMessages,
+        inputSchema: GetInboxThreadMessagesInputSchema,
+    }, async (input) => toolResult(await handlers.getInboxThreadMessages(input)));
+    server.registerTool("get_inbox_aggregates", {
+        title: "Get Inbox Aggregates",
+        description: TOOL_DESCRIPTIONS.getInboxAggregates,
+        inputSchema: InboxFiltersInputSchema,
+    }, async (input) => toolResult(await handlers.getInboxAggregates(input)));
+    server.registerTool("update_inbox_thread_state", {
+        title: "Update Inbox Thread State",
+        description: TOOL_DESCRIPTIONS.updateInboxThreadState,
+        inputSchema: UpdateInboxThreadStateInputSchema,
+    }, async (input) => toolResult(await handlers.updateInboxThreadState(input)));
+    server.registerTool("send_inbox_reply", {
+        title: "Send Inbox Reply",
+        description: TOOL_DESCRIPTIONS.sendInboxReply,
+        inputSchema: SendInboxReplyInputSchema,
+    }, async (input) => toolResult(await handlers.sendInboxReply(input)));
+}

package/dist/tool-descriptions.d.ts

@@ -12,8 +12,9 @@ export declare const TOOL_DESCRIPTIONS: {
     readonly checkBulkEmailReadiness: "The final dry-run gate before bulk email. Requires recipient_target with exact IDs or a narrowed selection, checks those selected recipients, and returns sendability guidance.";
     readonly startBulkEmail: "REAL SEND: start a campaign bulk-email job after readiness has passed and the user authorized sending. Requires recipient_target, an explicit idempotency key, and send_confirmation: \"user_authorized\".";
     readonly getBulkEmailJob: "Read campaign bulk-email job status after start_bulk_email returns a job_id.";
-    readonly listInboxThreads: "List Hyperstar inbox threads with filters for triage before reading or replying.";
+    readonly listInboxThreads: "List Hyperstar inbox thread summaries with filters for triage. Call get_inbox_thread_messages before drafting replies.";
+    readonly getInboxThreadMessages: "Read full message history for one Hyperstar inbox thread before deciding whether to reply.";
     readonly getInboxAggregates: "Read aggregate counts for Hyperstar inbox filters to summarize inbox state.";
     readonly updateInboxThreadState: "Archive, snooze, star, or set read state for one inbox thread without sending a message.";
-    readonly sendInboxReply: "REAL SEND: send one user-authorized reply to a Hyperstar inbox thread with an explicit idempotency key.";
+    readonly sendInboxReply: "REAL SEND: send one user-authorized reply to a Hyperstar inbox thread with an explicit idempotency key and send_confirmation: \"user_authorized\".";
 };

package/dist/tool-descriptions.js

@@ -12,8 +12,9 @@ export const TOOL_DESCRIPTIONS = {
     checkBulkEmailReadiness: "The final dry-run gate before bulk email. Requires recipient_target with exact IDs or a narrowed selection, checks those selected recipients, and returns sendability guidance.",
     startBulkEmail: 'REAL SEND: start a campaign bulk-email job after readiness has passed and the user authorized sending. Requires recipient_target, an explicit idempotency key, and send_confirmation: "user_authorized".',
     getBulkEmailJob: "Read campaign bulk-email job status after start_bulk_email returns a job_id.",
-    listInboxThreads: "List Hyperstar inbox threads with filters for triage before reading or replying.",
+    listInboxThreads: "List Hyperstar inbox thread summaries with filters for triage. Call get_inbox_thread_messages before drafting replies.",
+    getInboxThreadMessages: "Read full message history for one Hyperstar inbox thread before deciding whether to reply.",
     getInboxAggregates: "Read aggregate counts for Hyperstar inbox filters to summarize inbox state.",
     updateInboxThreadState: "Archive, snooze, star, or set read state for one inbox thread without sending a message.",
-    sendInboxReply: "REAL SEND: send one user-authorized reply to a Hyperstar inbox thread with an explicit idempotency key.",
+    sendInboxReply: 'REAL SEND: send one user-authorized reply to a Hyperstar inbox thread with an explicit idempotency key and send_confirmation: "user_authorized".',
 };

package/dist/tool-guidance.d.ts

@@ -10,3 +10,5 @@ export declare function campaignRosterGuidance(payload: JsonObject, campaignId:
 export declare function readinessGuidance(payload: JsonObject, input: CheckBulkEmailReadinessInput): JsonObject;
 /** Add deterministic next-step guidance after listing inbox threads. */
 export declare function inboxThreadListGuidance(payload: JsonObject): JsonObject;
+/** Add deterministic next-step guidance after reading full inbox messages. */
+export declare function inboxThreadMessagesGuidance(payload: JsonObject): JsonObject;

package/dist/tool-guidance.js

@@ -68,11 +68,19 @@ export function inboxThreadListGuidance(payload) {
     return {
         ...payload,
         next_tools: [
+            "get_inbox_thread_messages",
             "get_inbox_aggregates",
             "update_inbox_thread_state",
-            "send_inbox_reply",
         ],
-        agent_guidance: "Use get_inbox_aggregates for counts, update_inbox_thread_state for archive/star/snooze/read-state changes, and send_inbox_reply only after explicit user authorization because send_inbox_reply performs a real send.",
+        agent_guidance: "Use get_inbox_thread_messages to read full message history before replying, get_inbox_aggregates for counts, update_inbox_thread_state for archive/star/snooze/read-state changes, and send_inbox_reply only after explicit user authorization because send_inbox_reply performs a real send.",
+    };
+}
+/** Add deterministic next-step guidance after reading full inbox messages. */
+export function inboxThreadMessagesGuidance(payload) {
+    return {
+        ...payload,
+        next_tools: ["send_inbox_reply", "update_inbox_thread_state"],
+        agent_guidance: 'Review the full message history before drafting. send_inbox_reply performs a real send and requires send_confirmation: "user_authorized".',
     };
 }
 function recipientTargetArgument(ids, selection) {

package/dist/tool-inputs.d.ts

@@ -465,6 +465,14 @@ export declare const UpdateInboxThreadStateInputSchema: z.ZodObject<{
     }>>;
     clear_read_state: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strict>;
+export declare const GetInboxThreadMessagesInputSchema: z.ZodObject<{
+    platform: z.ZodEnum<{
+        tiktok: "tiktok";
+        instagram: "instagram";
+        buyer: "buyer";
+    }>;
+    thread_id: z.ZodNumber;
+}, z.core.$strict>;
 export declare const SendInboxReplyInputSchema: z.ZodObject<{
     platform: z.ZodEnum<{
         tiktok: "tiktok";
@@ -477,6 +485,7 @@ export declare const SendInboxReplyInputSchema: z.ZodObject<{
     attachments: z.ZodOptional<z.ZodArray<z.ZodString>>;
     campaign_creator_id: z.ZodOptional<z.ZodNumber>;
     idempotency_key: z.ZodString;
+    send_confirmation: z.ZodLiteral<"user_authorized">;
 }, z.core.$strict>;
 type SearchCreatorsInput = z.infer<typeof SearchCreatorsInputSchema>;
 type ListWorkspacesInput = z.infer<typeof ListWorkspacesInputSchema>;
@@ -491,6 +500,7 @@ type BulkEmailJobInput = z.infer<typeof BulkEmailJobInputSchema>;
 type InboxFiltersInput = z.infer<typeof InboxFiltersInputSchema>;
 type ListInboxThreadsInput = z.infer<typeof ListInboxThreadsInputSchema>;
 type UpdateInboxThreadStateInput = z.infer<typeof UpdateInboxThreadStateInputSchema>;
+type GetInboxThreadMessagesInput = z.infer<typeof GetInboxThreadMessagesInputSchema>;
 type SendInboxReplyInput = z.infer<typeof SendInboxReplyInputSchema>;
 export type HyperstarToolHandlers = {
     readonly hyperstarWhoami: () => Promise<JsonObject>;
@@ -509,5 +519,6 @@ export type HyperstarToolHandlers = {
     readonly listInboxThreads: (input: ListInboxThreadsInput) => Promise<JsonObject>;
     readonly getInboxAggregates: (input: InboxFiltersInput) => Promise<JsonObject>;
     readonly updateInboxThreadState: (input: UpdateInboxThreadStateInput) => Promise<JsonObject>;
+    readonly getInboxThreadMessages: (input: GetInboxThreadMessagesInput) => Promise<JsonObject>;
     readonly sendInboxReply: (input: SendInboxReplyInput) => Promise<JsonObject>;
 };

package/dist/tool-inputs.js

@@ -5,6 +5,7 @@ export { CheckBulkEmailReadinessDiscoveryInputSchema, CheckBulkEmailReadinessInp
 const PositivePageLimitSchema = z.number().int().min(1);
 const SearchPlatformSchema = z.enum(["tiktok", "instagram"]);
 const InboxPlatformSchema = z.enum(["tiktok", "instagram", "buyer"]);
+const SendConfirmationSchema = z.literal("user_authorized");
 const SearchIdSchema = z.uuid();
 // Backend workspace identifiers are organization IDs such as "org_123", not UUIDs.
 const WorkspaceOrganizationIdSchema = z.string().trim().min(1);
@@ -246,6 +247,12 @@ export const UpdateInboxThreadStateInputSchema = z
     clear_read_state: z.boolean().optional(),
 })
     .strict();
+export const GetInboxThreadMessagesInputSchema = z
+    .object({
+    platform: InboxPlatformSchema,
+    thread_id: z.number().int().positive(),
+})
+    .strict();
 export const SendInboxReplyInputSchema = z
     .object({
     platform: InboxPlatformSchema,
@@ -255,5 +262,6 @@ export const SendInboxReplyInputSchema = z
     attachments: z.array(z.string().trim().min(1)).optional(),
     campaign_creator_id: z.number().int().positive().optional(),
     idempotency_key: IdempotencyKeySchema,
+    send_confirmation: SendConfirmationSchema,
 })
     .strict();

package/dist/tools.js

@@ -1,12 +1,13 @@
 import { bulkEmailQueuedResult } from "./bulk-email-guidance.js";
 import { readinessRequestBody, startBulkEmailRequestBody, } from "./bulk-email-tool-body.js";
+import { registerInboxTools } from "./inbox-tool-registration.js";
 import { projectSearchResultPage } from "./search-result-projection.js";
 import { TOOL_DESCRIPTIONS } from "./tool-descriptions.js";
-import { campaignImportGuidance, campaignRosterGuidance, inboxThreadListGuidance, readinessGuidance, searchGuidance, } from "./tool-guidance.js";
+import { campaignImportGuidance, campaignRosterGuidance, inboxThreadListGuidance, inboxThreadMessagesGuidance, readinessGuidance, searchGuidance, } from "./tool-guidance.js";
 import { toolResult } from "./tool-result.js";
 import { compactJsonObject, pathSegment, queryFrom, } from "./tool-http-helpers.js";
 import { BulkEmailJobResponseSchema, BulkEmailReadinessResponseSchema, CampaignDetailResponseSchema, CampaignCreatorsResponseSchema, CampaignImportResponseSchema, CampaignsResponseSchema, InboxAggregatesResponseSchema, InboxThreadPageResponseSchema, InboxWorkspaceStateResponseSchema, JsonObjectSchema, SearchCreatedResponseSchema, SearchResultsResponseSchema, WhoamiResponseSchema, } from "./schemas.js";
-import { BulkEmailJobInputSchema, CampaignCreatorsInputSchema, CheckBulkEmailReadinessDiscoveryInputSchema, CheckBulkEmailReadinessInputSchema, CreateCampaignInputSchema, GetSearchResultsInputSchema, InboxFiltersInputSchema, ListCampaignsInputSchema, ListInboxThreadsInputSchema, ListWorkspacesInputSchema, SaveSearchResultsToCampaignInputSchema, SearchCreatorsInputSchema, SelectWorkspaceInputSchema, SendInboxReplyInputSchema, StartBulkEmailDiscoveryInputSchema, StartBulkEmailInputSchema, UpdateInboxThreadStateInputSchema, WorkflowGuideInputSchema, WhoamiInputSchema, normalizeCheckBulkEmailReadinessInput, normalizeStartBulkEmailInput, } from "./tool-inputs.js";
+import { BulkEmailJobInputSchema, CampaignCreatorsInputSchema, CheckBulkEmailReadinessDiscoveryInputSchema, CheckBulkEmailReadinessInputSchema, CreateCampaignInputSchema, GetInboxThreadMessagesInputSchema, GetSearchResultsInputSchema, InboxFiltersInputSchema, ListInboxThreadsInputSchema, ListCampaignsInputSchema, ListWorkspacesInputSchema, SaveSearchResultsToCampaignInputSchema, SearchCreatorsInputSchema, SelectWorkspaceInputSchema, SendInboxReplyInputSchema, StartBulkEmailDiscoveryInputSchema, StartBulkEmailInputSchema, UpdateInboxThreadStateInputSchema, WorkflowGuideInputSchema, WhoamiInputSchema, normalizeCheckBulkEmailReadinessInput, normalizeStartBulkEmailInput, } from "./tool-inputs.js";
 import { getHyperstarWorkflowGuide, listAvailableWorkspaces, selectAvailableWorkspace, } from "./workspaces.js";
 /** Build workflow handlers around a Hyperstar HTTP client. */
 export function createToolHandlers(client, options = {}) {
@@ -118,6 +119,10 @@ export function createToolHandlers(client, options = {}) {
             const parsedInput = InboxFiltersInputSchema.parse(input);
             return InboxAggregatesResponseSchema.parse(await client.get("/v1/inbox/threads/aggregates", queryFrom(parsedInput)));
         },
+        getInboxThreadMessages: async (input) => {
+            const parsedInput = GetInboxThreadMessagesInputSchema.parse(input);
+            return inboxThreadMessagesGuidance(JsonObjectSchema.parse(await client.get(`/v1/inbox/threads/${pathSegment(parsedInput.platform)}/${pathSegment(parsedInput.thread_id)}/messages`)));
+        },
         updateInboxThreadState: async (input) => {
             const parsedInput = UpdateInboxThreadStateInputSchema.parse(input);
             return InboxWorkspaceStateResponseSchema.parse(await client.patch(`/v1/inbox/threads/${pathSegment(parsedInput.platform)}/${pathSegment(parsedInput.thread_id)}/state`, compactJsonObject([
@@ -137,6 +142,7 @@ export function createToolHandlers(client, options = {}) {
                 ["attachments", parsedInput.attachments],
                 ["campaign_creator_id", parsedInput.campaign_creator_id],
                 ["idempotency_key", parsedInput.idempotency_key],
+                ["send_confirmation", parsedInput.send_confirmation],
             ])));
         },
     };
@@ -209,24 +215,5 @@ export function registerHyperstarTools(server, client, options = {}) {
         description: TOOL_DESCRIPTIONS.getBulkEmailJob,
         inputSchema: BulkEmailJobInputSchema,
     }, async (input) => toolResult(await handlers.getBulkEmailJob(input)));
-    server.registerTool("list_inbox_threads", {
-        title: "List Inbox Threads",
-        description: TOOL_DESCRIPTIONS.listInboxThreads,
-        inputSchema: ListInboxThreadsInputSchema,
-    }, async (input) => toolResult(await handlers.listInboxThreads(input)));
-    server.registerTool("get_inbox_aggregates", {
-        title: "Get Inbox Aggregates",
-        description: TOOL_DESCRIPTIONS.getInboxAggregates,
-        inputSchema: InboxFiltersInputSchema,
-    }, async (input) => toolResult(await handlers.getInboxAggregates(input)));
-    server.registerTool("update_inbox_thread_state", {
-        title: "Update Inbox Thread State",
-        description: TOOL_DESCRIPTIONS.updateInboxThreadState,
-        inputSchema: UpdateInboxThreadStateInputSchema,
-    }, async (input) => toolResult(await handlers.updateInboxThreadState(input)));
-    server.registerTool("send_inbox_reply", {
-        title: "Send Inbox Reply",
-        description: TOOL_DESCRIPTIONS.sendInboxReply,
-        inputSchema: SendInboxReplyInputSchema,
-    }, async (input) => toolResult(await handlers.sendInboxReply(input)));
+    registerInboxTools(server, handlers);
 }

package/dist/workflow-content.d.ts

@@ -11,7 +11,7 @@ export declare const CLI_WORKFLOW_SEQUENCE: readonly ["list_workspaces", "select
 export declare const SERVICE_ACCOUNT_WORKFLOW_SEQUENCE: readonly ["list_workspaces", "hyperstar_whoami", "search_creators", "list_campaigns or create_campaign", "save_search_results_to_campaign", "list_campaign_creators", "check_bulk_email_readiness", "WARNING: start_bulk_email and send_inbox_reply perform real sends."];
 export declare const CLI_SAFETY_NOTES: readonly ["Run list_workspaces and select_workspace before Product API calls that require workspace scope.", "Run hyperstar_whoami after selecting a workspace to confirm the authenticated principal.", "Run list_campaigns or create_campaign before save_search_results_to_campaign when the user has not supplied a campaign_id.", "check_bulk_email_readiness is the final dry-run gate before any bulk send.", "start_bulk_email and send_inbox_reply perform real sends."];
 export declare const SERVICE_ACCOUNT_SAFETY_NOTES: readonly ["Service-account auth is already workspace-scoped; select_workspace is only for local browser CLI auth.", "Run list_workspaces and hyperstar_whoami before workflow tools to confirm the authenticated workspace.", "Run list_campaigns or create_campaign before save_search_results_to_campaign when the user has not supplied a campaign_id.", "check_bulk_email_readiness is the final dry-run gate before any bulk send.", "start_bulk_email and send_inbox_reply perform real sends."];
-export declare const WORKFLOW_DATA_FLOW_NOTES: readonly ["search_creators returns a search_id plus compact creator summaries; save_search_results_to_campaign consumes search_id server-side, so agents do not need to load every creator row into context.", "check_bulk_email_readiness and start_bulk_email require recipient_target, either exact campaign_creator_ids or a narrowed campaign_creator_selection.", "Use list_campaign_creators after saving search results to find campaign_creator_ids for explicit recipient_target calls.", "Use list_inbox_threads for triage, update_inbox_thread_state for non-send state changes, and send_inbox_reply only after explicit user authorization."];
+export declare const WORKFLOW_DATA_FLOW_NOTES: readonly ["search_creators returns a search_id plus compact creator summaries; save_search_results_to_campaign consumes search_id server-side, so agents do not need to load every creator row into context.", "check_bulk_email_readiness and start_bulk_email require recipient_target, either exact campaign_creator_ids or a narrowed campaign_creator_selection.", "Use list_campaign_creators after saving search results to find campaign_creator_ids for explicit recipient_target calls.", "Use list_inbox_threads for triage, get_inbox_thread_messages to read full message history before drafting replies, update_inbox_thread_state for non-send state changes, and send_inbox_reply only after explicit user authorization with send_confirmation: \"user_authorized\"."];
 export declare const SEARCH_FILTER_GUIDANCE: readonly ["filters is a structured JSON object validated by the MCP before it is forwarded to Product API search.", "Use range objects such as `follower_range: {\"min\": 1000, \"max\": 100000}`, `avg_engagement_rate`, `avg_views`, `gmv`, and `gpm`.", "Use boolean/string filters such as `has_email`, `email_contactability`, `is_verified`, `has_tiktok_shop`, `creator_gender`, `creator_language`, `category_1`, and Instagram `category_name`.", "Put broad niches, verticals, and countries in `query`/`region` unless a named structured filter applies; do not invent `country`, `categories`, `follower_count`, or `engagement_rate` filter keys.", "Use sort_by for relevance, follower_count, engagement_rate, avg_views, views_growth_rate, gmv, or gpm; gmv and gpm are TikTok-only.", "Keep filters narrow and serializable; use get_search_results pagination instead of loading every creator row into context."];
 export declare const workflowGuideResourceDefinitions: readonly [{
     readonly kind: "headless-workflow";

package/dist/workflow-content.js

@@ -37,7 +37,7 @@ export const WORKFLOW_DATA_FLOW_NOTES = [
     "search_creators returns a search_id plus compact creator summaries; save_search_results_to_campaign consumes search_id server-side, so agents do not need to load every creator row into context.",
     "check_bulk_email_readiness and start_bulk_email require recipient_target, either exact campaign_creator_ids or a narrowed campaign_creator_selection.",
     "Use list_campaign_creators after saving search results to find campaign_creator_ids for explicit recipient_target calls.",
-    "Use list_inbox_threads for triage, update_inbox_thread_state for non-send state changes, and send_inbox_reply only after explicit user authorization.",
+    'Use list_inbox_threads for triage, get_inbox_thread_messages to read full message history before drafting replies, update_inbox_thread_state for non-send state changes, and send_inbox_reply only after explicit user authorization with send_confirmation: "user_authorized".',
 ];
 export const SEARCH_FILTER_GUIDANCE = [
     "filters is a structured JSON object validated by the MCP before it is forwarded to Product API search.",
@@ -150,9 +150,10 @@ export function buildWorkflowMarkdown(kind) {
                 "# Inbox Workflow",
                 "",
                 "1. Call `list_inbox_threads` with filters such as platform, unread state, archive state, search text, or campaign/job identifiers.",
-                "2. Call `get_inbox_aggregates` when the user asks for counts by common inbox filters.",
-                "3. Use `update_inbox_thread_state` for archive, star, snooze, or read-state changes.",
-                "4. Use `send_inbox_reply` only when the user has authorized a real reply. Include a stable `idempotency_key`.",
+                "2. Call `get_inbox_thread_messages` before drafting replies; thread lists contain summaries and previews, not full message history.",
+                "3. Call `get_inbox_aggregates` when the user asks for counts by common inbox filters.",
+                "4. Use `update_inbox_thread_state` for archive, star, snooze, or read-state changes.",
+                '5. Use `send_inbox_reply` only when the user has authorized a real reply. Include a stable `idempotency_key` and `send_confirmation: "user_authorized"`.',
             ].join("\n");
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperstar/mcp",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "type": "module",
   "license": "UNLICENSED",
   "description": "Local stdio MCP server and CLI for Hyperstar headless workflows.",
@@ -33,6 +33,7 @@
   },
   "files": [
     "dist",
+    "scripts/npm-clean-room-smoke.mjs",
     "README.md",
     "package.json"
   ],
@@ -44,6 +45,7 @@
     "format:check": "prettier --check .",
     "prepack": "npm run build",
     "smoke:dev": "npm run build && node scripts/dev-smoke.mjs",
+    "smoke:npm": "node scripts/npm-clean-room-smoke.mjs",
     "test": "vitest run",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },

package/scripts/npm-clean-room-smoke.mjs

@@ -0,0 +1,113 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const packageJson = JSON.parse(
+  readFileSync(resolve(packageRoot, "package.json"), "utf8"),
+);
+const packageSpec =
+  process.env.HYPERSTAR_MCP_NPM_PACKAGE ??
+  `${packageJson.name}@${packageJson.version}`;
+const scratchDir = mkdtempSync(resolve(tmpdir(), "hyperstar-mcp-npm-smoke-"));
+
+function isLocalPackageSpec(value) {
+  return (
+    value.startsWith("file:") ||
+    value.startsWith(".") ||
+    value.endsWith(".tgz") ||
+    isAbsolute(value)
+  );
+}
+
+function logLocalPackageSpec(value) {
+  console.log(
+    JSON.stringify(
+      {
+        step: "local-package",
+        ok: true,
+        command: [],
+        stdout: [value],
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+function runStep(step, command, args) {
+  const result = spawnSync(command, args, {
+    cwd: scratchDir,
+    encoding: "utf8",
+    env: process.env,
+    shell: false,
+  });
+  const stdout = result.stdout.trim();
+  const stderr = result.stderr.trim();
+  if (result.status !== 0) {
+    console.error(
+      JSON.stringify(
+        {
+          step,
+          ok: false,
+          command: [command, ...args],
+          status: result.status,
+          stdout,
+          stderr,
+        },
+        null,
+        2,
+      ),
+    );
+    process.exit(result.status ?? 1);
+  }
+  console.log(
+    JSON.stringify(
+      {
+        step,
+        ok: true,
+        command: [command, ...args],
+        stdout: stdout.split("\n").slice(0, 8),
+      },
+      null,
+      2,
+    ),
+  );
+}
+
+try {
+  if (isLocalPackageSpec(packageSpec)) {
+    logLocalPackageSpec(packageSpec);
+  } else {
+    runStep("registry-version", "npm", [
+      "view",
+      packageSpec,
+      "version",
+      "--silent",
+    ]);
+  }
+  runStep("hyperstar-cli-help", "npm", [
+    "exec",
+    "--yes",
+    "--package",
+    packageSpec,
+    "--",
+    "hyperstar",
+    "--help",
+  ]);
+  runStep("hyperstar-mcp-help", "npm", [
+    "exec",
+    "--yes",
+    "--package",
+    packageSpec,
+    "--",
+    "hyperstar-mcp",
+    "--help",
+  ]);
+} finally {
+  rmSync(scratchDir, { recursive: true, force: true });
+}