@hailer/mcp 1.3.9 → 1.3.11

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.11] - 22-06-2026
+
+### Fix
+
+**Workspace-aware local publish-auth injection**
+
+`npx hailer-mcp` mints a user API key into the machine-global `~/.env` so app
+publishing works flag-free. It previously skipped whenever *any* key was already
+present, so the first project to boot claimed `~/.env` permanently — every other
+project then published silently into the first project's workspace.
+
+The injector now records the workspace in the `~/.env` marker and re-mints when
+the booting project's workspace differs (last server to boot owns `~/.env`).
+A key the user set themselves — exported, or hand-added without our marker — is
+left untouched, and pre-1.3.11 marker blocks auto-upgrade on next boot.
+
 ## [1.1.7] - 18-02-2026
 
 ### Fix

package/dist/bot/bot.d.ts

@@ -57,6 +57,14 @@ export declare class Bot {
     private hailerApi;
     private opLogger;
     private cachedTools;
+    /**
+     * Per-turn tool result dedup cache for helperMode.
+     * Key includes senderId to prevent cross-user permission leaks.
+     * Cleared on each new user message AND when any write tool executes.
+     */
+    private toolDedupCache;
+    private static readonly DEDUP_TOOLS;
+    private static readonly WRITE_TOOLS_FOR_CACHE;
     private signalHandler;
     private processUpdatedHandler;
     private workspaceUpdatedHandler;
@@ -118,6 +126,8 @@ export declare class Bot {
     private handleSignal;
     private processDiscussion;
     private processMessage;
+    /** Short continuation messages used in helperMode onboarding (numbers, "ok", "next", etc.) */
+    private static readonly HELPER_TRIVIAL;
     private routeMessage;
     private getRecentContext;
     private runLlmLoop;

package/dist/bot/bot.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../../src/bot/bot.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"bot.d.ts","sourceRoot":"","sources":["../../src/bot/bot.ts"],"names":[],"mappings":"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"}

package/dist/bot/bot.js

@@ -75,7 +75,7 @@ const config_1 = require("../config");
  */
 const SEED_TURNS_MAX = 24;
 function parseSeedTurns(raw, log) {
-    const empty = { turns: [], viewedSlides: [] };
+    const empty = { turns: [], viewedSlides: [], templateIds: [], templateNames: [] };
     if (!raw) {
         return empty;
     }
@@ -89,23 +89,48 @@ function parseSeedTurns(raw, log) {
         });
         return empty;
     }
-    // Two supported shapes:
+    // Three supported shapes:
     //   - bare array of {role, content} turns (legacy)
     //   - object { turns: [...], viewedSlides: [...] } (current)
+    //   - object { summary: "...", viewedSlides: [...], templateIds: [...], templateNames: [...] } (summarized handoff)
     let turnSource;
     let viewedSlides = [];
+    let templateIds = [];
+    let templateNames = [];
     if (Array.isArray(parsed)) {
         turnSource = parsed;
     }
     else if (parsed && typeof parsed === 'object') {
-        turnSource = parsed.turns;
         const slidesRaw = parsed.viewedSlides;
         if (Array.isArray(slidesRaw)) {
             viewedSlides = slidesRaw.filter((id) => typeof id === 'string' && id.length > 0);
         }
+        const tplRaw = parsed.templateIds;
+        if (Array.isArray(tplRaw)) {
+            templateIds = tplRaw.filter((id) => typeof id === 'string' && id.length > 0);
+        }
+        const namesRaw = parsed.templateNames;
+        if (Array.isArray(namesRaw)) {
+            templateNames = namesRaw.filter((n) => typeof n === 'string' && n.length > 0);
+        }
+        // Summary format: plain-text handoff from summarizeChat()
+        const summary = parsed.summary;
+        if (typeof summary === 'string' && summary.length > 0) {
+            // Append explicit template names so the bot sees them clearly
+            const namesHint = templateNames.length > 0
+                ? `\n\n[INSTALL THESE TEMPLATES BY NAME: ${templateNames.join(', ')}]`
+                : '';
+            return {
+                turns: [{ role: 'user', content: `[Demo conversation summary]\n${summary}${namesHint}` }],
+                viewedSlides,
+                templateIds,
+                templateNames,
+            };
+        }
+        turnSource = parsed.turns;
     }
     if (!Array.isArray(turnSource)) {
-        return { turns: [], viewedSlides };
+        return { turns: [], viewedSlides, templateIds, templateNames };
     }
     const turns = [];
     for (const item of turnSource) {
@@ -122,7 +147,7 @@ function parseSeedTurns(raw, log) {
             break;
         }
     }
-    return { turns, viewedSlides };
+    return { turns, viewedSlides, templateIds, templateNames };
 }
 /**
  * Thrown by Bot.start() when the bot's own Agent Directory activity has been
@@ -177,6 +202,35 @@ const HEAP_BACKPRESSURE_THRESHOLD = 0.7;
 function fileSizeLimit(mime) {
     return EXCEL_MIME_TYPES.has(mime) || WORD_MIME_TYPES.has(mime) ? MAX_OFFICE_FILE_SIZE : MAX_FILE_SIZE;
 }
+/**
+ * Detect a supported image's true media type from its leading magic bytes.
+ * Hailer derives a file's mime from its extension, so a renamed file (e.g. an
+ * AVIF saved as .jpeg) reports the wrong mime. Anthropic vision sniffs the real
+ * bytes and rejects a mismatch with a 400, so we sniff here and send the true
+ * type — returning null for anything that is not a vision-supported image
+ * (AVIF, HEIC, corrupt data) so the caller skips it instead of mislabeling it.
+ */
+function sniffImageMime(base64) {
+    const buf = Buffer.from(base64.slice(0, 32), 'base64');
+    if (buf.length < 12) {
+        return null;
+    }
+    if (buf[0] === 0xFF && buf[1] === 0xD8 && buf[2] === 0xFF) {
+        return 'image/jpeg';
+    }
+    if (buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4E && buf[3] === 0x47) {
+        return 'image/png';
+    }
+    if (buf[0] === 0x47 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x38) {
+        return 'image/gif';
+    }
+    const isRiff = buf[0] === 0x52 && buf[1] === 0x49 && buf[2] === 0x46 && buf[3] === 0x46;
+    const isWebp = buf[8] === 0x57 && buf[9] === 0x45 && buf[10] === 0x42 && buf[11] === 0x50;
+    if (isRiff && isWebp) {
+        return 'image/webp';
+    }
+    return null;
+}
 const ATTACHMENT_KINDS = [
     { label: 'Image', trailing: 'included below for vision', matches: (mimeType) => IMAGE_MIME_TYPES.has(mimeType) },
     { label: 'Document', trailing: 'included below', matches: (mimeType) => DOCUMENT_MIME_TYPES.has(mimeType) || TEXT_MIME_TYPES.has(mimeType) },
@@ -285,6 +339,24 @@ class Bot {
     hailerApi = null;
     opLogger = new operation_logger_1.OperationLogger();
     cachedTools = null;
+    /**
+     * Per-turn tool result dedup cache for helperMode.
+     * Key includes senderId to prevent cross-user permission leaks.
+     * Cleared on each new user message AND when any write tool executes.
+     */
+    toolDedupCache = new Map();
+    static DEDUP_TOOLS = new Set([
+        'list_workflows_minimal', 'list_workflows', 'get_workflow_schema',
+        'list_workflow_phases', 'list_calendars', 'search_workspace_users',
+        'core_init', 'check_user_permissions', 'list_workflow_permissions',
+    ]);
+    static WRITE_TOOLS_FOR_CACHE = new Set([
+        'create_activity', 'update_activity', 'install_workflow',
+        'create_event', 'update_event', 'delete_event',
+        'update_workflow_field', 'update_workflow_phase',
+        'create_calendar', 'update_calendar',
+        'grant_workflow_permission', 'revoke_workflow_permission',
+    ]);
     // Signal handlers (for cleanup)
     signalHandler = null;
     processUpdatedHandler = null;
@@ -602,7 +674,7 @@ class Bot {
             accessLevel: this.config.accessLevel,
             allowBotMessages: this.config.allowBotMessages,
         });
-        const { turns: seedTurns, viewedSlides } = parseSeedTurns(this.config.seedContext, this.logger);
+        const { turns: seedTurns, viewedSlides, templateIds } = parseSeedTurns(this.config.seedContext, this.logger);
         const hasSeed = seedTurns.length > 0;
         // Map slide ids → short human labels for the prompt. Anything not in
         // the map is dropped (defence against stale ids leaking through).
@@ -629,6 +701,36 @@ class Bot {
         const slideHint = slideLabels.length > 0
             ? `\n\nAdditional signal: during the demo the visitor explicitly opened these overview slides — ${slideLabels.join(', ')}. Treat that as an interest signal. Weight your concrete suggestions toward those concepts when the demo conversation is ambiguous, but don't read more into it than "they paid attention here."`
             : '';
+        // Install marketplace templates BEFORE generating the intro so we
+        // can tell the bot what was installed and it doesn't ask the user.
+        const installedTemplateNames = [];
+        if (templateIds.length > 0 && this.client) {
+            for (const templateId of templateIds) {
+                try {
+                    await this.client.socket.request('v2.network.product.install', [templateId, this.config.workspaceId]);
+                    installedTemplateNames.push(templateId);
+                    this.logger.info('Installed marketplace template from seedContext', {
+                        templateId, workspaceId: this.config.workspaceId,
+                    });
+                }
+                catch (err) {
+                    this.logger.warn('Failed to install marketplace template, trying as app', { templateId, err });
+                    try {
+                        await this.client.socket.request('v3.app.product.install', [templateId, this.config.workspaceId]);
+                        installedTemplateNames.push(templateId);
+                        this.logger.info('Installed app product from seedContext', {
+                            templateId, workspaceId: this.config.workspaceId,
+                        });
+                    }
+                    catch (appErr) {
+                        this.logger.warn('Template install failed', { templateId, err: appErr });
+                    }
+                }
+            }
+        }
+        const templatesInstalledHint = installedTemplateNames.length > 0
+            ? `\n\nIMPORTANT: The marketplace template(s) the visitor chose during the demo have ALREADY been installed into this workspace automatically. Do NOT ask which template they want or offer to install anything — it's done. Just tell them it's installed and ready, and offer to walk them through what's inside (phases, fields, etc.).`
+            : '';
         // Only promise an automatic build when Studio session creation is
         // configured for this deployment; otherwise nothing builds the
         // workspace and the bot must not promise a build that never runs. The
@@ -650,19 +752,20 @@ What this first message needs to do:
 4. Mention in passing that they can shape how you behave (tone, persona, language, even your picture) just by asking you here, and that account-level settings live in the AI Hub app.
 
 Tone: conversational, friendly, reassuring. No section headers, no bullet lists. Keep it under ~150 words.`
-                : `You are being posted in your own activity discussion for the first time. The user just graduated from a public demo chat with you — the messages above are the conversation you both had there. NOTE: there is no automatic workspace builder running in this deployment, so YOU are how they get set up.
-
-What this first message needs to do:
+                : `You are being posted in your own activity discussion for the first time. The user just graduated from a public demo chat with you — the messages above are the conversation you both had there.
 
-1. Greet them warmly and acknowledge you remember the demo. Be specific — name the thing they were exploring (e.g. "the plumbing-company job tracker you were sketching out" rather than "your business").
-
-2. Scan the demo for concrete setup intent — a process with stages, or a list of records they want to manage. Offer to set it up for them now: be concrete, naming the phases you'd create (e.g. Quoted → Scheduled → In Progress → Invoiced → Paid) for a lifecycle, or describing it as a simple list for reference data. End with a clear yes/no like "Want me to set this up?" — don't start building unilaterally.
+CRITICAL: This is a plain text greeting. No tool calls, no bot-action tags, no JSON, no XML, no code blocks. Just normal sentences.
 
-3. If the demo is too vague to start, ask ONE or TWO concrete clarifying questions instead.
+Write exactly this structure:
+1. "Welcome to Hailer!" — warm greeting, one sentence.
+2. If a template was mentioned in the demo context: "I see you chose [template name] — shall I install it?" Ask for confirmation, nothing more.
+3. If no template was mentioned: "What would you like to set up first?" — one sentence.
 
-4. Mention in passing that they can shape how you behave (tone, persona, language, even your picture) just by asking you here, and that account-level settings live in the AI Hub app.
+${installedTemplateNames.length > 0
+                    ? `The template(s) have been auto-installed. Say: "Welcome to Hailer! I've already installed [name] for you — want me to show you what's inside?"`
+                    : ``}
 
-Tone: conversational, friendly, action-oriented. No section headers; short bullets are fine only when naming proposed phases or fields. Keep it under ~180 words.`)
+Under 40 words. No headers, no lists.`)
             : `You are being posted in your own activity discussion for the first time. Introduce yourself briefly in your own voice.
 
 CRITICAL: do NOT invent a backstory or claim to be a real person, celebrity, or fictional character based on your name alone. Your name was just chosen by the user — they may have meant a specific person/character, or they may have just liked the sound of it. If you don't have explicit persona instructions, acknowledge your name but be honest that you're a fresh assistant without a defined persona yet, and ask what kind of assistant they want you to be (or invite them to configure you).
@@ -736,6 +839,7 @@ Keep it short and conversational. No bullet lists, no headers.`;
             activityId: this.config.activityId,
             discussionId,
             length: text.length,
+            templatesInstalled: installedTemplateNames.length,
         });
     }
     /**
@@ -937,6 +1041,19 @@ Keep it short and conversational. No bullet lists, no headers.`;
                 }
                 // Build conversation entry
                 const conversation = this.conversationManager.getConversation(discussionId);
+                // First message in a graduated bot's discussion: inject the
+                // demo context so the LLM knows what was discussed before signup.
+                if (conversation.length === 0 && this.config.seedContext) {
+                    const seed = parseSeedTurns(this.config.seedContext, this.logger);
+                    if (seed.turns.length > 0) {
+                        for (const turn of seed.turns) {
+                            conversation.push(turn);
+                        }
+                        // Close with a synthetic assistant ack so the next real
+                        // user message doesn't violate the user-user turn rule.
+                        conversation.push({ role: 'assistant', content: '[Context from demo chat loaded]' });
+                    }
+                }
                 const parts = messages.map(msg => this.formatIncomingMessage(msg));
                 let merged = parts.join('\n\n');
                 if (messages.length > 1) {
@@ -1010,6 +1127,7 @@ Keep it short and conversational. No bullet lists, no headers.`;
                 return true;
             }
         }
+        this.toolDedupCache.clear();
         this.conversationManager.manageContextSize(message.discussionId);
         const conversation = this.conversationManager.getConversation(message.discussionId);
         const snapshotLength = conversation.length;
@@ -1024,12 +1142,37 @@ Keep it short and conversational. No bullet lists, no headers.`;
             this.logger.error('Message processing failed', error);
             this.typingIndicator?.stop(message.discussionId);
             conversation.length = snapshotLength;
+            // Never fail silently — always tell the user something went wrong.
+            const errMsg = error instanceof Error ? error.message : String(error);
+            const isBadImage = error instanceof sdk_1.default.BadRequestError &&
+                /image/i.test(errMsg) && /not supported|unsupported/i.test(errMsg);
+            const notice = isBadImage
+                ? 'I could not read that image — please send it as a PNG, JPEG, GIF, or WebP (formats like AVIF or HEIC are not supported).'
+                : 'Sorry — something went wrong on my end and I could not finish that. Please try again.';
+            await this.sendMessage(message.discussionId, notice);
             return false;
         }
     }
     // ===== MODEL ROUTING =====
+    /** Short continuation messages used in helperMode onboarding (numbers, "ok", "next", etc.) */
+    static HELPER_TRIVIAL = /^(?:[1-9]|ok|yes|no|да|нет|ок|дальше|далее|next|continue|продолжай|го|давай|sure|yep|yeah|ладно|хорошо|понял|ага)\.?!?$/i;
     async routeMessage(message, conversation, signal) {
         const defaultRoute = { model: MODEL_HAIKU, maxTokens: 2000 };
+        // helperMode: onboarding steps are templated — Haiku with higher budget.
+        // File attachments still go to Sonnet (checked below).
+        // Trivial continuations ("3", "дальше") skip the router call entirely.
+        if (this.config.helperMode) {
+            const helperRoute = { model: MODEL_HAIKU, maxTokens: 4096 };
+            if (Bot.HELPER_TRIVIAL.test(message.content.trim())) {
+                this.opLogger.route(message.discussionId, 'HELPER_TRIVIAL', helperRoute.model, message.content);
+                return helperRoute;
+            }
+            // Non-trivial helper messages still skip router but use Haiku
+            if (!message.fileAttachments?.length) {
+                this.opLogger.route(message.discussionId, 'HELPER', helperRoute.model, message.content);
+                return helperRoute;
+            }
+        }
         // Any file attachment forces COMPLEX: reading/analysing an attachment plus the
         // tool calls that typically follow easily blows Haiku's 2000-token budget,
         // and a truncated response with an unfinished tool_use poisons the conversation.
@@ -1132,7 +1275,10 @@ Keep it short and conversational. No bullet lists, no headers.`;
                         llmStart = Date.now();
                         continue;
                     }
-                    if (route.model !== MODEL_HAIKU && !isPromptTooLong) {
+                    // A non-prompt-length 400 (e.g. an unsupported image) is deterministic —
+                    // Haiku would fail identically, so don't waste a retry; surface it instead.
+                    const isBadRequest = error instanceof sdk_1.default.BadRequestError;
+                    if (route.model !== MODEL_HAIKU && !isPromptTooLong && !isBadRequest) {
                         this.logger.warn('Sonnet failed, falling back to Haiku');
                         route = { model: MODEL_HAIKU, maxTokens: 2000 };
                         llmStart = Date.now();
@@ -1293,6 +1439,16 @@ Keep it short and conversational. No bullet lists, no headers.`;
                 results.push({ type: 'tool_result', tool_use_id: block.id, content: 'You are already responding in this discussion. Your text response will be posted automatically — do not use add_discussion_message for the current discussion. Use it only for OTHER discussions.', is_error: true });
                 continue;
             }
+            // Dedup cache: serve cached result for read-only tools (same sender + same args)
+            if (Bot.DEDUP_TOOLS.has(block.name)) {
+                const dedupKey = `${block.name}:${message.senderId}:${JSON.stringify(args)}`;
+                const cached = this.toolDedupCache.get(dedupKey);
+                if (cached) {
+                    this.opLogger.toolCall(message.discussionId, block.name, 'dedup hit', 0, 'OK', undefined);
+                    results.push({ type: 'tool_result', tool_use_id: block.id, content: cached });
+                    continue;
+                }
+            }
             try {
                 let toolArgs = args;
                 // Auto-inject for join_discussion
@@ -1342,6 +1498,15 @@ Keep it short and conversational. No bullet lists, no headers.`;
                     contentStr = `${contentStr.slice(0, MAX_TOOL_RESULT_CHARS)}\n\n[Tool result truncated. Original: ${originalLen} chars (~${Math.round(originalLen / 4)} tokens). Narrow your query: use 'fields' parameter, add filters, lower 'limit', or use run_insight with aggregate SQL.]`;
                     this.logger.warn('Tool result truncated', { tool: block.name, originalLen, truncatedTo: MAX_TOOL_RESULT_CHARS });
                 }
+                // Invalidate dedup cache when a write tool executes
+                if (Bot.WRITE_TOOLS_FOR_CACHE.has(block.name)) {
+                    this.toolDedupCache.clear();
+                }
+                // Store read-only results in dedup cache (post-filter, so permissions are baked in)
+                if (Bot.DEDUP_TOOLS.has(block.name)) {
+                    const dedupKey = `${block.name}:${message.senderId}:${JSON.stringify(args)}`;
+                    this.toolDedupCache.set(dedupKey, contentStr);
+                }
                 results.push({ type: 'tool_result', tool_use_id: block.id, content: contentStr });
             }
             catch (error) {
@@ -1409,9 +1574,16 @@ Keep it short and conversational. No bullet lists, no headers.`;
             try {
                 const result = await this.hailerApi.downloadFile(f.fileId);
                 if (IMAGE_MIME_TYPES.has(f.mime) && result.encoding === 'base64') {
+                    // Trust the actual bytes, not the declared mime — a renamed file
+                    // (e.g. AVIF saved as .jpeg) would otherwise be sent mislabeled and 400.
+                    const sniffedMime = sniffImageMime(result.content);
+                    if (!sniffedMime) {
+                        skipped.push({ filename: f.filename || f.fileId, reason: 'not a supported image — use PNG, JPEG, GIF, or WebP (AVIF/HEIC are not supported)' });
+                        return null;
+                    }
                     return {
                         type: 'image',
-                        source: { type: 'base64', media_type: f.mime, data: result.content },
+                        source: { type: 'base64', media_type: sniffedMime, data: result.content },
                     };
                 }
                 if (DOCUMENT_MIME_TYPES.has(f.mime) && result.encoding === 'base64') {