@hailer/mcp 1.2.1 → 1.3.9

package/dist/bot/bot.js

@@ -9,13 +9,49 @@
  * - buildSystemPrompt: LLM system prompt construction
  * - ConversationManager, MessageClassifier, MessageFormatterService, etc.
  */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
 var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Bot = void 0;
+exports.Bot = exports.ActivityGoneError = void 0;
+const v8 = __importStar(require("v8"));
 const sdk_1 = __importDefault(require("@anthropic-ai/sdk"));
 const tool_registry_1 = require("../mcp/tool-registry");
+const tool_profiles_1 = require("../mcp/tool-profiles");
+const hailer_rpc_1 = require("../mcp/hailer-rpc");
 const hailer_clients_1 = require("../mcp/hailer-clients");
 const hailer_api_client_1 = require("../mcp/utils/hailer-api-client");
 const types_1 = require("../mcp/utils/types");
@@ -24,43 +60,201 @@ const tool_executor_1 = require("./tool-executor");
 const workspace_overview_1 = require("./workspace-overview");
 const operation_logger_1 = require("./operation-logger");
 const services_1 = require("./services");
+const bot_config_1 = require("../bot-config");
 const logger_1 = require("../lib/logger");
+const config_1 = require("../config");
 // ===== CONSTANTS =====
+/**
+ * Parse the optional `seedContext` field on the bot config — a JSON array
+ * of prior chat turns from the public demo — into Anthropic message
+ * params suitable for prepending to the self-intro request. Caps the
+ * count so a misbehaving caller can't blow the context budget.
+ *
+ * Returns `[]` for missing, malformed, or empty input; the bot falls
+ * back to the generic intro path in that case.
+ */
+const SEED_TURNS_MAX = 24;
+function parseSeedTurns(raw, log) {
+    const empty = { turns: [], viewedSlides: [] };
+    if (!raw) {
+        return empty;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        log.warn('seedContext: JSON parse failed — skipping', {
+            err: err instanceof Error ? err.message : String(err),
+        });
+        return empty;
+    }
+    // Two supported shapes:
+    //   - bare array of {role, content} turns (legacy)
+    //   - object { turns: [...], viewedSlides: [...] } (current)
+    let turnSource;
+    let viewedSlides = [];
+    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);
+        }
+    }
+    if (!Array.isArray(turnSource)) {
+        return { turns: [], viewedSlides };
+    }
+    const turns = [];
+    for (const item of turnSource) {
+        if (!item || typeof item !== 'object') {
+            continue;
+        }
+        const role = item.role;
+        const content = item.content;
+        if ((role !== 'user' && role !== 'assistant') || typeof content !== 'string' || !content) {
+            continue;
+        }
+        turns.push({ role, content });
+        if (turns.length >= SEED_TURNS_MAX) {
+            break;
+        }
+    }
+    return { turns, viewedSlides };
+}
+/**
+ * Thrown by Bot.start() when the bot's own Agent Directory activity has been
+ * deleted in Hailer. BotManager catches this and discards the bot without
+ * adding it to the running set; the entry has already been removed from
+ * .bot-config/{workspaceId}.json by the time this is thrown.
+ */
+class ActivityGoneError extends Error {
+    activityId;
+    workspaceId;
+    constructor(activityId, workspaceId) {
+        super(`Activity ${activityId} no longer exists in workspace ${workspaceId}`);
+        this.activityId = activityId;
+        this.workspaceId = workspaceId;
+        this.name = 'ActivityGoneError';
+    }
+}
+exports.ActivityGoneError = ActivityGoneError;
 const WRITE_TOOLS = new Set(['create_activity', 'update_activity']);
 const DISCUSSION_TOOLS = new Set([
     'fetch_discussion_messages', 'fetch_previous_discussion_messages',
     'add_discussion_message', 'invite_discussion_members', 'get_activity_from_discussion',
 ]);
-const BOT_TOOLS = new Set([
-    'list_workflows', 'list_workflows_minimal', 'list_workflow_phases', 'get_workflow_schema',
-    'list_activities', 'show_activity_by_id', 'count_activities',
-    'search_workspace_users', 'get_workspace_balance',
-    'create_activity', 'update_activity',
-    'install_workflow',
-    'list_my_discussions', 'fetch_discussion_messages', 'fetch_previous_discussion_messages',
-    'add_discussion_message', 'join_discussion', 'leave_discussion',
-    'invite_discussion_members', 'get_activity_from_discussion',
-    'upload_files', 'download_file',
-    'list_insights', 'get_insight_data', 'preview_insight', 'create_insight', 'update_insight',
-    'list_workflow_permissions', 'check_user_permissions',
-    'grant_workflow_permission', 'revoke_workflow_permission',
-    'resolve_date',
-]);
-const MODEL_HAIKU = 'claude-haiku-4-5-20251001';
-const MODEL_SONNET = 'claude-sonnet-4-5-20250929';
+/** Model-facing text for a pre-execution permission denial. */
+function permissionDeniedMessage(denied) {
+    if (denied.reason === 'bot-scope') {
+        return `Permission denied: This bot does not have access to workflow ${denied.workflowId}.`;
+    }
+    if (denied.reason === 'unverified-insight') {
+        return `Permission denied: Could not verify which workflows insight ${denied.workflowId} reads from — `
+            + 'it may have been deleted. Call list_insights to see valid insight IDs, then retry.';
+    }
+    return `Permission denied: You do not have access to workflow ${denied.workflowId}.`;
+}
+const MODEL_HAIKU = 'claude-haiku-4-5';
+const MODEL_SONNET = 'claude-sonnet-4-6';
+const MAX_TOOL_RESULT_CHARS = 40000;
+const MAX_PROMPT_TRIM_ATTEMPTS = 5;
 const IMAGE_MIME_TYPES = new Set(['image/jpeg', 'image/png', 'image/gif', 'image/webp']);
 const DOCUMENT_MIME_TYPES = new Set(['application/pdf']);
 const TEXT_MIME_TYPES = new Set(['text/plain', 'text/csv', 'text/html', 'text/markdown', 'application/json', 'application/xml']);
+const EXCEL_MIME_TYPES = new Set([
+    'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet', // .xlsx only
+]);
+const WORD_MIME_TYPES = new Set([
+    'application/vnd.openxmlformats-officedocument.wordprocessingml.document', // .docx
+]);
 const MAX_FILE_SIZE = 5 * 1024 * 1024;
+const MAX_OFFICE_FILE_SIZE = 10 * 1024 * 1024;
+const OFFICE_TEXT_CAP = 512 * 1024;
+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;
+}
+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) },
+    { label: 'Spreadsheet', trailing: 'included below as CSV per sheet', matches: (mimeType) => EXCEL_MIME_TYPES.has(mimeType) },
+    { label: 'Word document', trailing: 'included below as plain text', matches: (mimeType) => WORD_MIME_TYPES.has(mimeType) },
+];
+function describeAttachment(mime, filename, fileId) {
+    const matched = ATTACHMENT_KINDS.find((kind) => kind.matches(mime));
+    if (!matched) {
+        return null;
+    }
+    return `[${matched.label} attached: ${filename} (fileId: ${fileId}) — ${matched.trailing}]`;
+}
+function isSupportedMime(mime) {
+    return IMAGE_MIME_TYPES.has(mime) || DOCUMENT_MIME_TYPES.has(mime) || TEXT_MIME_TYPES.has(mime)
+        || EXCEL_MIME_TYPES.has(mime) || WORD_MIME_TYPES.has(mime);
+}
+function isOfficeMime(mime) {
+    return EXCEL_MIME_TYPES.has(mime) || WORD_MIME_TYPES.has(mime);
+}
+function capText(text) {
+    return text.length > OFFICE_TEXT_CAP ? text.slice(0, OFFICE_TEXT_CAP) + '\n\n[...content truncated...]' : text;
+}
+function isHeapUnderPressure() {
+    const { heapUsed } = process.memoryUsage();
+    const heapLimit = v8.getHeapStatistics().heap_size_limit;
+    return heapUsed / heapLimit > HEAP_BACKPRESSURE_THRESHOLD;
+}
+function cellToCsv(value) {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (typeof value === 'object') {
+        const v = value;
+        if (typeof v.result !== 'undefined') {
+            return cellToCsv(v.result);
+        }
+        if (typeof v.text === 'string') {
+            return cellToCsv(v.text);
+        }
+        if (Array.isArray(v.richText)) {
+            return v.richText.map((rt) => rt.text || '').join('');
+        }
+        if (typeof v.error === 'string') {
+            return v.error;
+        }
+        return '';
+    }
+    const s = String(value);
+    return /[",\n]/.test(s) ? `"${s.replace(/"/g, '""')}"` : s;
+}
+// Global mutex — serialize Office downloads + parses across the pod to bound peak memory
+let officeParseQueue = Promise.resolve();
+function withOfficeParseLock(fn) {
+    const next = officeParseQueue.then(fn, fn);
+    officeParseQueue = next.catch(() => undefined);
+    return next;
+}
+const SONNET_ROUTE = { model: MODEL_SONNET, maxTokens: 16384 };
 const TOOL_STATUS_LABELS = {
-    list_activities: 'Searching activities', count_activities: 'Counting activities',
+    list_activities: 'Searching activities',
     show_activity_by_id: 'Reading activity', create_activity: 'Creating activity',
-    update_activity: 'Updating activity', list_workflows: 'Loading workflows',
-    list_workflows_minimal: 'Loading workflows', get_workflow_schema: 'Reading workflow schema',
-    list_workflow_phases: 'Loading phases', preview_insight: 'Running query',
-    get_insight_data: 'Running report', search_workspace_users: 'Searching users',
+    update_activity: 'Updating activity',
+    describe_workflows: 'Reading workflows',
+    update_workflow_structure: 'Updating workflow structure',
+    run_insight: 'Running report', save_insight: 'Saving report',
+    search_workspace_users: 'Searching users',
     fetch_discussion_messages: 'Reading messages', add_discussion_message: 'Sending message',
     join_discussion: 'Joining discussion',
+    query_events: 'Loading events', manage_calendar: 'Managing calendars',
+    create_event: 'Creating event',
+    update_event: 'Updating event', delete_event: 'Deleting event',
+    respond_to_invite: 'Responding to invite',
+    set_workflow_permission: 'Updating workflow access',
+    manage_my_profile: 'Updating my profile',
 };
 // ===== BOT CLASS =====
 class Bot {
@@ -97,37 +291,47 @@ class Bot {
     workspaceUpdatedHandler = null;
     cacheInvalidateHandler = null;
     _connected = false;
-    // Config
     config;
+    anthropicApiKey;
     botManager;
-    constructor(config) {
+    constructor(config, runtime) {
         this.config = {
-            email: config.email, password: config.password, apiHost: config.apiHost,
-            anthropicApiKey: config.anthropicApiKey,
-            model: config.model || MODEL_HAIKU,
-            toolRegistry: config.toolRegistry,
-            workspaceId: config.workspaceId, systemPrompt: config.systemPrompt,
-            accessLevel: config.accessLevel || 'all',
-            allowedWorkflows: config.allowedWorkflows || [],
-            allowBotMessages: config.allowBotMessages || false,
+            ...config,
+            accessLevel: config.accessLevel ?? 'all',
+            allowedWorkflows: config.allowedWorkflows ?? [],
+            allowBotMessages: config.allowBotMessages ?? false,
+            helperMode: config.helperMode ?? false,
         };
-        this.botManager = config.botManager || null;
+        this.anthropicApiKey = runtime.anthropicApiKey;
+        this.botManager = runtime.botManager ?? null;
         this._systemPrompt = config.systemPrompt;
-        this._responseMode = config.responseMode || 'always';
+        this._responseMode = config.responseMode ?? 'always';
         this.logger = (0, logger_1.createLogger)({ component: 'Bot' });
         this.clientManager = new hailer_clients_1.HailerClientManager(config.apiHost, config.email, config.password);
-        this.toolExecutor = new tool_executor_1.ToolExecutor(config.toolRegistry);
+        this.toolExecutor = new tool_executor_1.ToolExecutor(runtime.toolRegistry);
         this.signalRouter = new services_1.SignalRouter(this.logger);
         this.permissions = new services_1.BotPermissions(this.config.allowedWorkflows, this.logger);
         this.workspaceRefresh = new services_1.WorkspaceRefresh(this.logger);
     }
     // Public accessors (used by BotManager for hot-reload)
-    get email() { return this.config.email; }
-    get password() { return this.config.password; }
-    get accessLevel() { return this.config.accessLevel; }
-    get connected() { return this._connected; }
-    get workspaceId() { return this._workspaceId; }
-    get botUserId() { return this.userId; }
+    get email() {
+        return this.config.email;
+    }
+    get password() {
+        return this.config.password;
+    }
+    get accessLevel() {
+        return this.config.accessLevel;
+    }
+    get connected() {
+        return this._connected;
+    }
+    get workspaceId() {
+        return this._workspaceId;
+    }
+    get botUserId() {
+        return this.userId;
+    }
     updateSystemPrompt(prompt) {
         this._systemPrompt = prompt;
         this.logger.info('System prompt updated live', { hasPrompt: !!prompt });
@@ -136,21 +340,88 @@ class Bot {
         this._responseMode = mode || 'always';
         this.logger.info('Response mode updated live', { responseMode: this._responseMode });
     }
+    updateHelperMode(helperMode) {
+        this.config.helperMode = !!helperMode;
+        this.logger.info('Helper mode updated live', { helperMode: this.config.helperMode });
+    }
     // ===== LIFECYCLE =====
     async start() {
-        if (this._connected)
+        if (this._connected) {
             return;
+        }
         this.logger.debug('Starting bot', { email: this.config.email });
         // 1. Connect
         this.client = await this.clientManager.connect();
         this.config.password = ''; // Clear from memory — connection is established
         // 2. Fetch workspace data + user in one call
-        this.init = await this.client.socket.request('v2.core.init', [
-            ['user', 'processes', 'users', 'network', 'networks', 'teams', 'groups'],
-        ]);
+        const initFields = ['user', 'processes', 'users', 'network', 'networks', 'teams', 'groups'];
+        this.init = await this.client.socket.request(hailer_rpc_1.HailerRpc.Core.init, [initFields]);
+        try {
+            const pendingInvites = await this.client.socket.request(hailer_rpc_1.HailerRpc.User.inviteList, []);
+            if (pendingInvites?.length) {
+                for (const invite of pendingInvites) {
+                    await this.client.socket.request(hailer_rpc_1.HailerRpc.User.inviteAccept, [invite.invite_key]);
+                    await this.client.socket.request(hailer_rpc_1.HailerRpc.Core.switchEcosystem, [invite.cid]);
+                    this.logger.info('Accepted workspace invite', { workspaceId: invite.cid, workspaceName: invite.network?.name });
+                }
+                this.init = await this.client.socket.request(hailer_rpc_1.HailerRpc.Core.init, [initFields]);
+            }
+        }
+        catch (err) {
+            this.logger.warn('Failed to check/accept pending invites', { error: err instanceof Error ? err.message : err });
+        }
+        // Hailer drops password-auth users into their personal "My Hailer" ecosystem
+        // on each fresh login, even after they've accepted a workspace invite. Force
+        // the configured workspace as the active ecosystem so the bot operates where
+        // it was provisioned, not in its personal workspace.
+        if (this.config.workspaceId && this.init.network?._id !== this.config.workspaceId) {
+            const fromWorkspaceId = this.init.network?._id;
+            try {
+                await this.client.socket.request(hailer_rpc_1.HailerRpc.Core.switchEcosystem, [this.config.workspaceId]);
+                this.init = await this.client.socket.request(hailer_rpc_1.HailerRpc.Core.init, [initFields]);
+                this.logger.info('Switched to configured workspace', {
+                    from: fromWorkspaceId, to: this.config.workspaceId,
+                });
+            }
+            catch (err) {
+                this.logger.warn('Failed to switch to configured workspace', {
+                    workspaceId: this.config.workspaceId,
+                    error: err instanceof Error ? err.message : err,
+                });
+            }
+        }
+        // Self-prune: probe the bot's own Agent Directory activity. If the
+        // activity is gone (definitively deleted OR otherwise unreachable in
+        // a way that matches the gone signals), drop the local config entry
+        // so we stop trying to run this bot. The bot's Hailer user account
+        // is NEVER deleted from here — a previous version did, and the
+        // classifier shared a numeric code with "Permission denied" which
+        // caused mass user-account deletion on transient permission errors.
+        // Orphaned bot users are reaped separately by Hailer's inactive-user
+        // prune (out-of-band).
+        if (this.config.activityId && this.config.workspaceId) {
+            try {
+                await this.client.socket.request(hailer_rpc_1.HailerRpc.Activities.load, [this.config.activityId]);
+            }
+            catch (err) {
+                const shape = (0, bot_config_1.extractHailerError)(err);
+                if ((0, bot_config_1.isActivityGone)(shape)) {
+                    this.logger.info('Self-probe: activity gone — pruning local config entry (keeping Hailer user)', {
+                        activityId: this.config.activityId, workspaceId: this.config.workspaceId,
+                        msg: shape.msg, code: shape.code,
+                    });
+                    this.pruneSelfFromConfig();
+                    throw new ActivityGoneError(this.config.activityId, this.config.workspaceId);
+                }
+                this.logger.debug('Self-probe non-deletion error — continuing startup', {
+                    activityId: this.config.activityId, msg: shape.msg, code: shape.code,
+                });
+            }
+        }
         this.userId = this.init.user?._id || '';
-        if (!this.userId)
+        if (!this.userId) {
             throw new Error('Could not determine bot user ID');
+        }
         (0, types_1.normalizeInitProcesses)(this.init);
         this._workspaceId = this.init.network?._id || this.config.workspaceId;
         // 3. Build caches
@@ -172,7 +443,7 @@ class Bot {
             workflowNames: this.init.processes.map(p => p.name),
         });
         // 4. Anthropic client
-        this.anthropic = new sdk_1.default({ apiKey: this.config.anthropicApiKey });
+        this.anthropic = new sdk_1.default({ apiKey: this.anthropicApiKey });
         // 5. Services
         const botConnection = {
             client: this.client,
@@ -194,11 +465,13 @@ class Bot {
             email: this.config.email, password: '', // Intentionally empty — cleared after connect
             workspaceRoles: { [currentWorkspaceId]: 'admin' },
             currentWorkspaceId, allowedGroups: [tool_registry_1.ToolGroup.READ, tool_registry_1.ToolGroup.WRITE, tool_registry_1.ToolGroup.BOT_INTERNAL],
+            botActivityId: this.config.activityId,
         };
         // 7. Wire workspace refresh
         this.workspaceRefresh.setHandler(async (scopes) => {
-            if (!this.client || !this.init)
+            if (!this.client || !this.init) {
                 return;
+            }
             const result = await services_1.WorkspaceRefresh.refresh(this.client, scopes, this.init, this.config.workspaceId, this.permissions, this.userContext, this.logger);
             this.init = result.init;
             this.workspaceCache = result.workspaceCache;
@@ -206,10 +479,17 @@ class Bot {
             this._workspaceId = result.workspaceId;
         });
         // 8. Subscribe to signals
-        this.signalHandler = (data) => this.handleSignal({
-            type: 'messenger.new', data, timestamp: Date.now(),
-            workspaceId: data.sid,
-        });
+        this.signalHandler = (data) => {
+            this.logger.info('Bot received messenger.new signal', {
+                discussion: data.discussion,
+                uid: data.uid,
+                msg_id: data.msg_id,
+            });
+            this.handleSignal({
+                type: 'messenger.new', data, timestamp: Date.now(),
+                workspaceId: data.sid,
+            });
+        };
         this.clientManager.onSignal('messenger.new', this.signalHandler);
         this.processUpdatedHandler = () => this.workspaceRefresh.schedule('processes');
         this.workspaceUpdatedHandler = () => this.workspaceRefresh.schedule('network');
@@ -219,6 +499,285 @@ class Bot {
         this.clientManager.onSignal('cache.invalidate', this.cacheInvalidateHandler);
         this._connected = true;
         this.logger.debug('Bot started', { userId: this.userId, workspaceId: this._workspaceId });
+        // Fire-and-forget: re-assert that the bot is following its own
+        // activity discussion on every startup. The self-intro path used to be
+        // the only caller of joinActivityDiscussion, but it short-circuits on
+        // `introPosted: true`, leaving bots that were unfollowed in the past
+        // (e.g. by the pre-fix raw activities.follow toggle, or by any other
+        // path that flipped their follow state) silently subscribed to nothing.
+        // Running joinActivityDiscussion here closes that loop — it's
+        // idempotent (no-op if already following).
+        this.ensureFollowingOwnDiscussion().catch((err) => {
+            const { msg, code } = (0, bot_config_1.extractHailerError)(err);
+            this.logger.warn('ensureFollowingOwnDiscussion threw (non-fatal)', { msg, code });
+        });
+        // Fire-and-forget self-introduction. One-shot per bot (persisted via
+        // BotEntry.introPosted), so restarts don't re-spam the discussion. Errors
+        // are logged inside the method — this catch is only a safety net.
+        this.introduceSelfIfNeeded().catch((err) => {
+            const { msg, code } = (0, bot_config_1.extractHailerError)(err);
+            this.logger.warn('Self-intro threw (non-fatal)', { msg, code });
+        });
+    }
+    /**
+   * Re-join the bot's own activity discussion if (and only if) the bot has
+   * drifted out of it. Runs every startup so bots that lost their follow
+   * state (e.g. via the pre-51254a2 raw activities.follow toggle) recover.
+   *
+   * Reads the activity's `followers` list and skips the join when the bot's
+   * userId is already there. activities.follow is a toggle that emits a
+   * leave/join event on every call — even toggle-toggle pairs — so calling
+   * unconditionally pollutes the discussion with "left / joined" pairs on
+   * every restart (visible in the timeline after deploy → retire → deploy).
+   */
+    async ensureFollowingOwnDiscussion() {
+        if (!this.config.activityId || !this.hailerApi || !this.userId) {
+            return;
+        }
+        try {
+            const activity = await this.hailerApi.fetchActivityById(this.config.activityId);
+            const followers = Array.isArray(activity?.followers) ? activity.followers : [];
+            if (followers.includes(this.userId)) {
+                this.logger.debug('Already following own discussion — skipping toggle', {
+                    activityId: this.config.activityId,
+                });
+                return;
+            }
+            await this.hailerApi.joinActivityDiscussion(this.config.activityId);
+        }
+        catch (err) {
+            const { msg, code } = (0, bot_config_1.extractHailerError)(err);
+            this.logger.debug('ensureFollowingOwnDiscussion failed (non-fatal)', { msg, code });
+        }
+    }
+    /**
+   * Post a one-time greeting in the bot's own activity discussion explaining
+   * what users can ask the bot to change about itself (system prompt, etc.).
+   * Marks the entry's `introPosted` flag in `.bot-config` so subsequent
+   * restarts don't repeat the message.
+   *
+   * Follow state is handled separately by ensureFollowingOwnDiscussion()
+   * which runs on every startup. We don't flip `introPosted` until the send
+   * succeeds, so a permission failure on first start retries on the next
+   * start instead of silently giving up.
+   */
+    async introduceSelfIfNeeded() {
+        if (!this.config.activityId || !this.config.workspaceId || !this.client) {
+            return;
+        }
+        const cfg = (0, bot_config_1.loadWorkspaceConfigFile)(this.config.workspaceId);
+        const entry = cfg.bots.find((b) => b.activityId === this.config.activityId);
+        if (!entry) {
+            return;
+        }
+        if (entry.introPosted) {
+            return;
+        }
+        let discussionId;
+        try {
+            const activity = await this.client.socket.request(hailer_rpc_1.HailerRpc.Activities.load, [this.config.activityId]);
+            discussionId = activity?.discussion;
+        }
+        catch (err) {
+            const { msg, code } = (0, bot_config_1.extractHailerError)(err);
+            this.logger.warn('Self-intro: activities.load failed', { msg, code });
+            return;
+        }
+        if (!discussionId) {
+            return;
+        }
+        if (!this.anthropic) {
+            return;
+        }
+        // Generate the intro via LLM so each bot speaks in its own voice. The
+        // bot's system prompt already explains its self-management capabilities,
+        // so a "pirate" bot greets in pirate voice while still mentioning users
+        // can change it.
+        const systemPrompt = (0, services_1.buildSystemPrompt)({
+            init: this.init, userId: this.userId,
+            workspaceOverview: this.workspaceOverview, customPrompt: this._systemPrompt,
+            helperMode: this.config.helperMode,
+            hasSeedContext: !!this.config.seedContext,
+            responseMode: this._responseMode,
+            accessLevel: this.config.accessLevel,
+            allowBotMessages: this.config.allowBotMessages,
+        });
+        const { turns: seedTurns, viewedSlides } = 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).
+        const SLIDE_LABEL = {
+            title: 'the Hailer overview cover',
+            what: 'what Hailer is in one line',
+            problem: 'the trackers-vs-chat problem framing',
+            'core-label': 'the core-concepts section',
+            workspaces: 'Workspaces',
+            workflows: 'Workflows',
+            activities: 'Activities',
+            discussions: 'Discussions',
+            'build-label': 'the build-and-extend section',
+            'apps-studio': 'Apps & Hailer Studio',
+            sdk: 'the Hailer SDK',
+            'sdk-code': 'the workflow-as-code example',
+            mcp: 'Hailer MCP',
+            insights: 'Insights & Automations',
+            closer: 'the closing one-platform statement',
+        };
+        const slideLabels = viewedSlides
+            .map((id) => SLIDE_LABEL[id])
+            .filter((s) => typeof s === 'string');
+        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."`
+            : '';
+        // 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
+        // graduation flow gates createStudioSession on the same env var, so
+        // "build promised" matches "build attempted".
+        const studioBuilding = !!config_1.environment.STUDIO_SESSIONS_CREATE_URL;
+        const introInstruction = hasSeed
+            ? (studioBuilding
+                ? `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.
+
+What this first message needs to do:
+
+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. Tell them what's happening RIGHT NOW: based on that conversation, their workspace is being set up for them automatically — the workflow(s) to run that process, a few sample records so they can see it in action, and a custom app on top. It takes a couple of minutes. Do NOT offer to build it yourself and do NOT ask "want me to set this up?" — it is already being built. You are not the one building it; just let them know it's underway.
+
+3. Tell them what comes next: as soon as the workflows are ready you'll walk them through their new workspace with a quick guided tour, so there's nothing they need to do yet — they can sit tight or keep chatting with you here.
+
+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:
+
+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.
+
+3. If the demo is too vague to start, ask ONE or TWO concrete clarifying questions instead.
+
+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, action-oriented. No section headers; short bullets are fine only when naming proposed phases or fields. Keep it under ~180 words.`)
+            : `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).
+
+In all cases, let the user know they can change how you behave — your tone, persona, language, dos and donts, even your profile picture — just by asking you here in chat. They can also ask to see your current configuration. For account-level settings (credentials, who can talk to you, etc.) point them at the AI Hub app.
+
+Tell them how to actually get your attention: describe your current response mode in one sentence (you can see it in <your-settings>). For example, if you only respond to mentions or replies, say so — otherwise they'll wonder why you're silent in shared discussions. Mention that they can switch you to a different mode in AI Hub if it doesn't suit them.
+
+Keep it short and conversational. No bullet lists, no headers.`;
+        const introInstructionFinal = introInstruction + slideHint;
+        const messages = [
+            ...seedTurns,
+            { role: 'user', content: introInstructionFinal },
+        ];
+        let response;
+        try {
+            response = await this.anthropic.messages.create({
+                model: MODEL_HAIKU,
+                max_tokens: 400,
+                temperature: 0.7,
+                system: systemPrompt,
+                messages,
+            });
+        }
+        catch (err) {
+            this.logger.warn('Self-intro: LLM call failed', {
+                activityId: this.config.activityId,
+                error: err instanceof Error ? err.message : String(err),
+            });
+            return;
+        }
+        const text = response.content
+            .filter((b) => b.type === 'text')
+            .map((b) => b.text)
+            .join('')
+            .trim();
+        if (!text) {
+            this.logger.warn('Self-intro: empty LLM response', { activityId: this.config.activityId });
+            return;
+        }
+        // Bill the intro generation to the workspace — same as any other LLM call.
+        if (this.tokenBilling && this._workspaceId) {
+            const usage = response.usage;
+            const cacheCreation = usage.cache_creation_input_tokens || 0;
+            const cacheRead = usage.cache_read_input_tokens || 0;
+            const cost = this.tokenBilling.calculateCost(usage.input_tokens, usage.output_tokens, cacheCreation, cacheRead, MODEL_HAIKU);
+            this.tokenBilling.burnTokens({
+                workspaceId: this._workspaceId,
+                inputTokens: usage.input_tokens, outputTokens: usage.output_tokens,
+                cacheCreationTokens: cacheCreation, cacheReadTokens: cacheRead, costUsd: cost,
+                sessionId: discussionId, model: MODEL_HAIKU,
+            });
+        }
+        try {
+            await this.client.socket.request(hailer_rpc_1.HailerRpc.Messenger.send, [{ msg: text }, discussionId]);
+        }
+        catch (err) {
+            const { msg: errMsg, code } = (0, bot_config_1.extractHailerError)(err);
+            this.logger.warn('Self-intro: messenger.send failed', {
+                activityId: this.config.activityId,
+                discussionId,
+                msg: errMsg,
+                code,
+            });
+            return;
+        }
+        entry.introPosted = true;
+        (0, bot_config_1.saveWorkspaceConfigFile)(cfg);
+        (0, bot_config_1.invalidateConfigCache)();
+        this.logger.info('Posted self-intro in own discussion', {
+            activityId: this.config.activityId,
+            discussionId,
+            length: text.length,
+        });
+    }
+    /**
+   * Teardown: stop the bot's websocket and live state. We intentionally do
+   * NOT delete the Hailer user account from here — that was previously a
+   * source of mass user-account deletion when the gone-classifier fired on
+   * transient permission errors. Orphaned bot users are reaped out-of-band
+   * by Hailer's inactive-user prune.
+   */
+    async destroy() {
+        await this.stop();
+    }
+    /**
+   * Remove this bot's entry from .bot-config/{workspaceId}.json. Called when
+   * the bot's own activity has been deleted in Hailer (detected via the
+   * self-probe in start()). Idempotent — safe if the entry is already gone.
+   */
+    pruneSelfFromConfig() {
+        if (!this.config.activityId || !this.config.workspaceId) {
+            return;
+        }
+        try {
+            const cfg = (0, bot_config_1.loadWorkspaceConfigFile)(this.config.workspaceId);
+            const before = cfg.bots.length;
+            cfg.bots = cfg.bots.filter((b) => b.activityId !== this.config.activityId);
+            if (cfg.bots.length === before) {
+                return;
+            }
+            (0, bot_config_1.saveWorkspaceConfigFile)(cfg);
+            (0, bot_config_1.invalidateConfigCache)();
+            this.logger.info('Pruned self from bot config', {
+                activityId: this.config.activityId,
+                workspaceId: this.config.workspaceId,
+                remaining: cfg.bots.length,
+            });
+        }
+        catch (err) {
+            this.logger.warn('Failed to prune self from bot config', {
+                activityId: this.config.activityId,
+                error: err instanceof Error ? err.message : err,
+            });
+        }
     }
     async stop() {
         this.logger.debug('Stopping bot');
@@ -247,8 +806,9 @@ class Bot {
     }
     // ===== SIGNAL HANDLING =====
     async handleSignal(signal) {
-        if (!this._connected || !this.messageClassifier)
+        if (!this._connected || !this.messageClassifier) {
             return;
+        }
         try {
             const rawMsgId = signal.data.msg_id;
             const discussionId = signal.data.discussion;
@@ -257,23 +817,27 @@ class Bot {
                 this.logger.warn('messenger.new signal has no dedup key');
                 return;
             }
-            if (this.signalRouter.isDuplicate(dedupKey))
+            if (this.signalRouter.isDuplicate(dedupKey)) {
                 return;
+            }
             const message = await this.messageClassifier.extractIncomingMessage(signal);
             if (!message) {
-                if (rawMsgId)
+                if (rawMsgId) {
                     this.signalRouter.removeDedupKey(rawMsgId);
+                }
                 return;
             }
             // Self-message guard — always skip own messages
-            if (message.senderId === this.userId)
+            if (message.senderId === this.userId) {
                 return;
+            }
             // Bot-to-bot guard
             if (this.botManager && this._workspaceId) {
                 const botUserIds = this.botManager.getBotUserIdsForWorkspace(this._workspaceId);
                 if (botUserIds.has(message.senderId)) {
-                    if (!this.config.allowBotMessages)
-                        return; // Hard block if not opted in
+                    if (!this.config.allowBotMessages) {
+                        return;
+                    } // Hard block if not opted in
                     // Only respond to bot messages if explicitly mentioned or replied to
                     if (!message.isMention && !message.isReplyToBot) {
                         this.logger.debug('Ignoring bot message - no mention or reply', {
@@ -304,27 +868,31 @@ class Bot {
                 }
             }
             // Rate limiting
-            if (this.signalRouter.isRateLimited(message.discussionId))
+            if (this.signalRouter.isRateLimited(message.discussionId)) {
                 return;
+            }
             // Layer 1: Workspace membership
             if (!this.permissions.isMember(message.senderId)) {
                 this.logger.debug('Ignoring message - not a workspace member', { senderId: message.senderId });
-                if (rawMsgId)
+                if (rawMsgId) {
                     this.signalRouter.removeDedupKey(rawMsgId);
+                }
                 return;
             }
             // Layer 2: Access level
             if (!this.permissions.meetsAccessLevel(message.senderId, this.config.accessLevel)) {
                 this.logger.debug('Ignoring message - access level not met', { senderId: message.senderId });
-                if (rawMsgId)
+                if (rawMsgId) {
                     this.signalRouter.removeDedupKey(rawMsgId);
+                }
                 return;
             }
             // Engagement logic
             const state = this.signalRouter.getOrCreateState(message.discussionId);
             state.contextBuffer.push(message);
-            if (!this.signalRouter.checkTrigger(message, this._responseMode))
+            if (!this.signalRouter.checkTrigger(message, this._responseMode)) {
                 return;
+            }
             const isExplicit = this.signalRouter.isExplicitTrigger(message);
             if (state.state === 'idle') {
                 if (isExplicit || this._responseMode === 'always') {
@@ -336,8 +904,9 @@ class Bot {
                     return;
                 }
             }
-            if (this._responseMode !== 'always' && !isExplicit)
+            if (this._responseMode !== 'always' && !isExplicit) {
                 return;
+            }
             // Process if not already running
             if (!this.signalRouter.processingDiscussions.has(message.discussionId)) {
                 this.processDiscussion(message.discussionId).catch(err => {
@@ -352,17 +921,20 @@ class Bot {
     }
     // ===== DISCUSSION PROCESSING =====
     async processDiscussion(discussionId) {
-        if (this.signalRouter.processingDiscussions.has(discussionId))
+        if (this.signalRouter.processingDiscussions.has(discussionId)) {
             return;
+        }
         this.signalRouter.processingDiscussions.add(discussionId);
         const state = this.signalRouter.getOrCreateState(discussionId);
         try {
             while (true) {
                 const messages = state.contextBuffer.splice(0);
-                if (messages.length === 0)
+                if (messages.length === 0) {
                     break;
-                if (messages.length > 1)
+                }
+                if (messages.length > 1) {
                     this.opLogger.coalesce(discussionId, messages.length);
+                }
                 // Build conversation entry
                 const conversation = this.conversationManager.getConversation(discussionId);
                 const parts = messages.map(msg => this.formatIncomingMessage(msg));
@@ -380,8 +952,9 @@ class Bot {
                 const primaryMessage = messages[messages.length - 1];
                 state.lastProgressTime = 0;
                 state.abortController = new AbortController();
-                for (const msg of messages)
+                for (const msg of messages) {
                     this.opLogger.messageIn(msg.discussionId, msg.senderName, msg.content);
+                }
                 let responded;
                 try {
                     responded = await this.processMessage(primaryMessage, state.abortController.signal);
@@ -404,12 +977,14 @@ class Bot {
                         break;
                     }
                 }
-                if (state.contextBuffer.length === 0)
+                if (state.contextBuffer.length === 0) {
                     break;
+                }
                 if (state.state === 'idle') {
                     const hasExplicit = state.contextBuffer.some(m => this.signalRouter.isExplicitTrigger(m));
-                    if (!hasExplicit)
+                    if (!hasExplicit) {
                         break;
+                    }
                     state.state = 'engaged';
                     state.consecutiveNonResponses = 0;
                     this.opLogger.engage(discussionId, 'reengaged');
@@ -443,8 +1018,9 @@ class Bot {
             return await this.runLlmLoop(message, route, signal);
         }
         catch (error) {
-            if (error instanceof sdk_1.default.APIUserAbortError)
+            if (error instanceof sdk_1.default.APIUserAbortError) {
                 throw error;
+            }
             this.logger.error('Message processing failed', error);
             this.typingIndicator?.stop(message.discussionId);
             conversation.length = snapshotLength;
@@ -454,6 +1030,14 @@ class Bot {
     // ===== MODEL ROUTING =====
     async routeMessage(message, conversation, signal) {
         const defaultRoute = { model: MODEL_HAIKU, maxTokens: 2000 };
+        // 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.
+        if (message.fileAttachments && message.fileAttachments.length > 0) {
+            const route = { ...SONNET_ROUTE };
+            this.opLogger.route(message.discussionId, 'COMPLEX (attachments)', route.model, message.content);
+            return route;
+        }
         try {
             const wsName = this.init?.network?.name || 'Workspace';
             const recentContext = this.getRecentContext(conversation);
@@ -465,7 +1049,7 @@ class Bot {
             this.trackTokenUsage(response, message, MODEL_HAIKU);
             const text = response.content.filter((b) => b.type === 'text').map(b => b.text).join('').trim().toUpperCase();
             if (text.includes('COMPLEX')) {
-                const route = { model: MODEL_SONNET, maxTokens: 16384 };
+                const route = { ...SONNET_ROUTE };
                 this.opLogger.route(message.discussionId, 'COMPLEX', route.model, message.content);
                 return route;
             }
@@ -488,8 +1072,9 @@ class Bot {
             else if (Array.isArray(msg.content)) {
                 text = msg.content.filter((b) => b.type === 'text').map((b) => b.text).join(' ');
             }
-            if (!text)
+            if (!text) {
                 continue;
+            }
             lines.unshift(`${msg.role === 'user' ? 'User' : 'Assistant'}: ${text.length > 200 ? text.slice(0, 200) + '...' : text}`);
             count++;
         }
@@ -505,38 +1090,54 @@ class Bot {
         const systemPrompt = (0, services_1.buildSystemPrompt)({
             init: this.init, userId: this.userId,
             workspaceOverview: this.workspaceOverview, customPrompt: this._systemPrompt,
-            botExchangeContext,
+            botExchangeContext, helperMode: this.config.helperMode,
+            hasSeedContext: !!this.config.seedContext,
+            responseMode: this._responseMode,
+            accessLevel: this.config.accessLevel,
+            allowBotMessages: this.config.allowBotMessages,
         });
         const tools = this.cachedTools || this.getAnthropicTools();
         for (let i = 0;; i++) {
-            const cachedConversation = this.conversationManager.prepareForCaching(conversation);
             this.typingIndicator?.updateStatus(message.discussionId, i === 0 ? 'Thinking' : 'Processing');
             let response;
             let llmStart = Date.now();
-            try {
-                response = await this.anthropic.messages.create({
-                    model: route.model, max_tokens: route.maxTokens, temperature: 0,
-                    system: [{ type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } }],
-                    messages: cachedConversation, tools,
-                }, { signal });
-            }
-            catch (error) {
-                if (error instanceof sdk_1.default.APIUserAbortError) {
-                    this.cleanupIncompleteExchange(conversation);
-                    this.opLogger.interrupt(message.discussionId, 'new message received');
-                    return false;
-                }
-                if (route.model !== MODEL_HAIKU) {
-                    this.logger.warn('Sonnet failed, falling back to Haiku');
-                    route = { model: MODEL_HAIKU, maxTokens: 2000 };
-                    llmStart = Date.now();
+            let trimAttempts = 0;
+            while (true) {
+                try {
+                    const cachedConversation = this.conversationManager.prepareForCaching(conversation);
                     response = await this.anthropic.messages.create({
-                        model: MODEL_HAIKU, max_tokens: 2000, temperature: 0,
+                        model: route.model, max_tokens: route.maxTokens, temperature: 0,
                         system: [{ type: 'text', text: systemPrompt, cache_control: { type: 'ephemeral' } }],
                         messages: cachedConversation, tools,
                     }, { signal });
+                    break;
                 }
-                else {
+                catch (error) {
+                    if (error instanceof sdk_1.default.APIUserAbortError) {
+                        this.cleanupIncompleteExchange(conversation);
+                        this.opLogger.interrupt(message.discussionId, 'new message received');
+                        return false;
+                    }
+                    const isPromptTooLong = error instanceof sdk_1.default.BadRequestError &&
+                        /prompt is too long/i.test(error.message || '');
+                    if (isPromptTooLong && trimAttempts < MAX_PROMPT_TRIM_ATTEMPTS && conversation.length >= 4) {
+                        trimAttempts++;
+                        const dropped = conversation.splice(0, 2);
+                        this.logger.warn('Prompt too long — dropped oldest conversation pair', {
+                            attempt: trimAttempts,
+                            droppedRoles: dropped.map(msg => msg.role),
+                            remainingMessages: conversation.length,
+                            model: route.model,
+                        });
+                        llmStart = Date.now();
+                        continue;
+                    }
+                    if (route.model !== MODEL_HAIKU && !isPromptTooLong) {
+                        this.logger.warn('Sonnet failed, falling back to Haiku');
+                        route = { model: MODEL_HAIKU, maxTokens: 2000 };
+                        llmStart = Date.now();
+                        continue;
+                    }
                     throw error;
                 }
             }
@@ -546,12 +1147,37 @@ class Bot {
             const cacheRead = usage.cache_read_input_tokens || 0;
             const totalInput = usage.input_tokens + cacheRead + (usage.cache_creation_input_tokens || 0);
             this.opLogger.llmCall(message.discussionId, route.model, usage.input_tokens, usage.output_tokens, totalInput > 0 ? Math.round((cacheRead / totalInput) * 100) : 0, llmDuration);
-            if (!response.content || response.content.length === 0)
+            if (!response.content || response.content.length === 0) {
                 break;
+            }
             conversation.push({ role: 'assistant', content: response.content });
-            // Truncation guard
+            // Truncation guard. When the response is cut off at max_tokens
+            // AND the truncated assistant content contains tool_use blocks,
+            // Anthropic's API requires the very next message to carry
+            // matching tool_result blocks — otherwise every subsequent
+            // request fails with `tool_use ids were found without tool_result
+            // blocks immediately after`. We can't actually execute the
+            // truncated tools (JSON inputs may be malformed, and the model
+            // expected all of them to run together), so we synthesize error
+            // tool_results that tell the model exactly why nothing ran.
             if (response.stop_reason === 'max_tokens') {
-                conversation.push({ role: 'user', content: 'Your previous response was truncated because it exceeded the output token limit. Break it into smaller batches of 25-50 items per tool call.' });
+                const truncatedToolUses = response.content.filter((b) => b.type === 'tool_use');
+                const reminder = 'Your previous response was truncated because it exceeded the output token limit. Break it into smaller batches of 25-50 items per tool call.';
+                if (truncatedToolUses.length > 0) {
+                    const errorResults = truncatedToolUses.map(b => ({
+                        type: 'tool_result',
+                        tool_use_id: b.id,
+                        content: 'Tool call was truncated before it could run because the response exceeded the output token limit. Try again with a smaller batch.',
+                        is_error: true,
+                    }));
+                    conversation.push({
+                        role: 'user',
+                        content: [...errorResults, { type: 'text', text: reminder }],
+                    });
+                }
+                else {
+                    conversation.push({ role: 'user', content: reminder });
+                }
                 continue;
             }
             // Tool calls
@@ -565,7 +1191,7 @@ class Bot {
                 if (route.model === MODEL_HAIKU) {
                     const failedCount = toolResults.filter(r => r.is_error).length;
                     if (failedCount >= 2) {
-                        route = { model: MODEL_SONNET, maxTokens: 16384 };
+                        route = { ...SONNET_ROUTE };
                         await this.sendMessage(message.discussionId, 'Switching to a more capable model to handle this.');
                     }
                 }
@@ -595,25 +1221,49 @@ class Bot {
         for (const block of toolUseBlocks) {
             const toolStart = Date.now();
             const args = block.input;
-            // Admin-only gate
-            if (this.permissions.isAdminOnlyTool(block.name) && !this.permissions.isAdminOrOwner(message.senderId)) {
+            // Bot profile gate — the model is only offered BOT_TOOLS, but enforce
+            // at execution too so a hallucinated tool name can't reach the registry.
+            // Resolve deprecation aliases first so mid-conversation calls under
+            // old v1 names keep working during the grace release.
+            const canonicalName = this.toolExecutor.resolveName(block.name);
+            if (!tool_profiles_1.BOT_TOOLS.has(canonicalName)) {
+                this.opLogger.permDenied(message.discussionId, block.name, 'n/a', 'not-in-bot-tools');
+                results.push({
+                    type: 'tool_result',
+                    tool_use_id: block.id,
+                    content: `Tool not available: ${block.name} is not part of this bot's toolset. `
+                        + 'Use only the tools you were given — do not retry.',
+                    is_error: true,
+                });
+                continue;
+            }
+            // Admin-only gate (args-aware: merged tools gate per-action)
+            if (this.permissions.isAdminOnlyTool(block.name, args) && !this.permissions.isAdminOrOwner(message.senderId)) {
                 this.opLogger.permDenied(message.discussionId, block.name, 'n/a', 'requires-admin');
-                results.push({ type: 'tool_result', tool_use_id: block.id, content: 'Permission denied: Only workspace admins can modify workflow permissions.', is_error: true });
+                results.push({
+                    type: 'tool_result',
+                    tool_use_id: block.id,
+                    content: `Permission denied: ${block.name} requires workspace admin or owner permission. Explain to the user that this action is restricted to admins/owners — do not retry, do not try a workaround, do not pretend it succeeded.`,
+                    is_error: true,
+                });
                 continue;
             }
-            // Pre-execution permission check
+            // Pre-execution permission check. An UNKNOWN insightId is
+            // resolved against the server first — an insight the bot can't
+            // map to workflows is denied, not run, because the workflow
+            // check can't see inside it (it would fail open).
             if (!this.permissions.isPostCheckTool(block.name)) {
-                const denied = this.permissions.checkArgs(args, message.senderId);
+                const denied = await this.permissions.checkArgsResolving(args, message.senderId, () => this.fetchInsightWorkflowMap());
                 if (denied) {
                     this.opLogger.permDenied(message.discussionId, block.name, denied.workflowId, denied.reason);
-                    results.push({ type: 'tool_result', tool_use_id: block.id, content: denied.reason === 'bot-scope' ? `Permission denied: This bot does not have access to workflow ${denied.workflowId}.` : `Permission denied: You do not have access to workflow ${denied.workflowId}.`, is_error: true });
+                    results.push({ type: 'tool_result', tool_use_id: block.id, content: permissionDeniedMessage(denied), is_error: true });
                     continue;
                 }
             }
             // Discussion isolation: prevent leaking DMs and discussions the user shouldn't access
             if (DISCUSSION_TOOLS.has(block.name) && args.discussionId && args.discussionId !== message.discussionId) {
                 try {
-                    const discResult = await this.client.socket.request('v3.discussion.message.latest', [args.discussionId]);
+                    const discResult = await this.client.socket.request(hailer_rpc_1.HailerRpc.Discussion.messageLatest, [args.discussionId]);
                     const disc = discResult?.discussion || {};
                     const participants = disc.participants || [];
                     const isPrivate = disc.private === true;
@@ -648,22 +1298,24 @@ class Bot {
                 // Auto-inject for join_discussion
                 if (block.name === 'join_discussion') {
                     toolArgs = { ...toolArgs };
-                    if (!toolArgs.inviteUserId && message.senderId)
+                    if (!toolArgs.inviteUserId && message.senderId) {
                         toolArgs.inviteUserId = message.senderId;
-                    if (!toolArgs.welcomeReason && message.content)
+                    }
+                    if (!toolArgs.welcomeReason && message.content) {
                         toolArgs.welcomeReason = message.content;
+                    }
                     // Only auto-inject sourceActivityId if explicitly provided — don't link DMs to random activities
                 }
                 const result = await this.toolExecutor.execute(block.name, toolArgs, this.getUserContext());
                 const text = result?.content?.[0]?.text ?? JSON.stringify(result);
                 let contentStr = typeof text === 'string' ? text : JSON.stringify(text);
                 const toolDuration = (Date.now() - toolStart) / 1000;
-                // Cache insight mappings
-                if (block.name === 'create_insight' && !contentStr.includes('❌')) {
-                    this.permissions.cacheInsightWorkflows(contentStr, args);
-                }
-                // Post-filter list results
-                contentStr = await this.permissions.postFilterListResults(block.name, contentStr, message.senderId, message.discussionId, this.opLogger);
+                // Cache insight mappings (keyed on the canonical name —
+                // create_insight is an alias of save_insight)
+                this.permissions.maybeCacheInsight(canonicalName, contentStr, args);
+                // Post-filter list results (canonical name: alias calls
+                // produce the new tools' output format)
+                contentStr = await this.permissions.postFilterListResults(canonicalName, contentStr, message.senderId, message.discussionId, this.opLogger);
                 // Post-execution permission check
                 if (this.permissions.isPostCheckTool(block.name)) {
                     const wfId = this.permissions.extractWorkflowIdFromResult(block.name, contentStr);
@@ -685,6 +1337,11 @@ class Bot {
                 if (signal?.aborted && WRITE_TOOLS.has(block.name)) {
                     this.logger.warn('Write tool completed before abort', { tool: block.name });
                 }
+                if (contentStr.length > MAX_TOOL_RESULT_CHARS) {
+                    const originalLen = contentStr.length;
+                    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 });
+                }
                 results.push({ type: 'tool_result', tool_use_id: block.id, content: contentStr });
             }
             catch (error) {
@@ -708,43 +1365,47 @@ class Bot {
             const parts = [];
             const unsupported = [];
             for (const f of message.fileAttachments) {
-                if (!f.mime || (f.size && f.size > MAX_FILE_SIZE)) {
+                if (!f.mime || (f.size && f.size > fileSizeLimit(f.mime))) {
                     unsupported.push(f.fileId);
+                    continue;
                 }
-                else if (IMAGE_MIME_TYPES.has(f.mime)) {
-                    parts.push(`[Image attached: ${f.filename} — included below for vision]`);
-                }
-                else if (DOCUMENT_MIME_TYPES.has(f.mime) || TEXT_MIME_TYPES.has(f.mime)) {
-                    parts.push(`[Document attached: ${f.filename} — included below]`);
-                }
-                else {
+                const desc = describeAttachment(f.mime, f.filename, f.fileId);
+                if (!desc) {
                     unsupported.push(f.fileId);
+                    continue;
                 }
+                parts.push(desc);
             }
-            if (unsupported.length)
+            if (unsupported.length) {
                 parts.push(`[File attached: ${unsupported.length} file(s) - IDs: ${unsupported.join(', ')}]\nUse download_file tool with fileId to read file contents.`);
-            if (parts.length)
+            }
+            if (parts.length) {
                 fileInfo = '\n' + parts.join('\n');
+            }
         }
         const dmNote = isDm ? '\n[This is a private DM conversation, not an activity discussion.]' : '';
-        return `<incoming discussion="${message.discussionId}"${typeAttr}${nameAttr}${activityAttr} from="${message.senderName}" user_id="${message.senderId}" timestamp="${new Date(message.timestamp).toISOString()}">\n${message.content}${fileInfo}${dmNote}\n</incoming>`;
+        const aiContext = message.meta?.aiContext ? `<context>${JSON.stringify(message.meta.aiContext)}</context>\n\n` : '';
+        return `<incoming discussion="${message.discussionId}"${typeAttr}${nameAttr}${activityAttr} from="${message.senderName}" user_id="${message.senderId}" timestamp="${new Date(message.timestamp).toISOString()}">\n${aiContext}${message.content}${fileInfo}${dmNote}\n</incoming>`;
     }
     async resolveFileAttachments(messages) {
-        if (!this.hailerApi)
+        if (!this.hailerApi) {
             return [];
-        const eligible = [];
+        }
+        const nonOffice = [];
+        const office = [];
+        const skipped = [];
         for (const msg of messages) {
             for (const f of msg.fileAttachments || []) {
-                if (!f.mime || (f.size && f.size > MAX_FILE_SIZE))
+                if (!f.mime || (f.size && f.size > fileSizeLimit(f.mime))) {
                     continue;
-                if (IMAGE_MIME_TYPES.has(f.mime) || DOCUMENT_MIME_TYPES.has(f.mime) || TEXT_MIME_TYPES.has(f.mime)) {
-                    eligible.push({ fileId: f.fileId, mime: f.mime });
                 }
+                if (!isSupportedMime(f.mime)) {
+                    continue;
+                }
+                (isOfficeMime(f.mime) ? office : nonOffice).push({ fileId: f.fileId, mime: f.mime, filename: f.filename });
             }
         }
-        if (!eligible.length)
-            return [];
-        const results = await Promise.all(eligible.map(async (f) => {
+        const nonOfficeResults = await Promise.all(nonOffice.map(async (f) => {
             try {
                 const result = await this.hailerApi.downloadFile(f.fileId);
                 if (IMAGE_MIME_TYPES.has(f.mime) && result.encoding === 'base64') {
@@ -768,11 +1429,98 @@ class Bot {
                 }
             }
             catch (err) {
-                this.logger.warn('Failed to download file', { fileId: f.fileId, mime: f.mime });
+                this.logger.warn('Failed to read file attachment', { fileId: f.fileId, mime: f.mime, err: err instanceof Error ? err.message : err });
+                skipped.push({ filename: f.filename || f.fileId, reason: 'download failed' });
             }
             return null;
         }));
-        return results.filter((b) => b !== null);
+        // Download Office files in parallel (I/O-bound), parse serially under the lock (memory-bound)
+        const officeDownloads = await Promise.all(office.map(async (f) => {
+            try {
+                const result = await this.hailerApi.downloadFile(f.fileId);
+                return { f, result };
+            }
+            catch (err) {
+                this.logger.warn('Failed to download Office file', { fileId: f.fileId, mime: f.mime, err: err instanceof Error ? err.message : err });
+                skipped.push({ filename: f.filename || f.fileId, reason: 'download failed' });
+                return null;
+            }
+        }));
+        const officeResults = [];
+        for (const entry of officeDownloads) {
+            if (!entry) {
+                continue;
+            }
+            const { f, result } = entry;
+            if (result.encoding !== 'base64') {
+                this.logger.warn('Office file has unexpected encoding, skipping', { fileId: f.fileId, mime: f.mime, encoding: result.encoding });
+                skipped.push({ filename: f.filename || f.fileId, reason: 'unexpected encoding from download' });
+                continue;
+            }
+            if (isHeapUnderPressure()) {
+                this.logger.warn('Heap under pressure, skipping Office parse', { fileId: f.fileId, mime: f.mime });
+                skipped.push({ filename: f.filename || f.fileId, reason: 'bot is under memory pressure — ask the user to retry in a moment' });
+                continue;
+            }
+            const block = await withOfficeParseLock(async () => {
+                try {
+                    if (EXCEL_MIME_TYPES.has(f.mime)) {
+                        const ExcelJS = (await Promise.resolve().then(() => __importStar(require('exceljs')))).default;
+                        const buffer = Buffer.from(result.content, 'base64');
+                        const wb = new ExcelJS.Workbook();
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Node 24 Buffer<ArrayBuffer> vs exceljs Buffer typing mismatch
+                        await wb.xlsx.load(buffer);
+                        const parts = [];
+                        wb.eachSheet((sheet) => {
+                            const rows = [];
+                            sheet.eachRow({ includeEmpty: false }, (row) => {
+                                const values = Array.isArray(row.values) ? row.values.slice(1) : [];
+                                rows.push(values.map(cellToCsv).join(','));
+                            });
+                            parts.push(`=== Sheet: ${sheet.name} (${rows.length} rows) ===\n${rows.join('\n')}`);
+                        });
+                        return {
+                            type: 'document',
+                            source: { type: 'text', media_type: 'text/plain', data: capText(`${f.filename || 'spreadsheet'}\n\n${parts.join('\n\n')}`) },
+                        };
+                    }
+                    if (WORD_MIME_TYPES.has(f.mime)) {
+                        const mammoth = await Promise.resolve().then(() => __importStar(require('mammoth')));
+                        const buffer = Buffer.from(result.content, 'base64');
+                        // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Node 24 Buffer<ArrayBuffer> vs mammoth Buffer typing mismatch
+                        const { value } = await mammoth.extractRawText({ buffer: buffer });
+                        return {
+                            type: 'document',
+                            source: { type: 'text', media_type: 'text/plain', data: capText(`${f.filename || 'document'}\n\n${value}`) },
+                        };
+                    }
+                }
+                catch (err) {
+                    this.logger.warn('Failed to parse Office file', { fileId: f.fileId, mime: f.mime, err: err instanceof Error ? err.message : err });
+                    skipped.push({ filename: f.filename || f.fileId, reason: 'parse error' });
+                }
+                return null;
+            });
+            if (block) {
+                officeResults.push(block);
+            }
+        }
+        const blocks = [
+            ...nonOfficeResults.filter((b) => b !== null),
+            ...officeResults,
+        ];
+        if (skipped.length > 0) {
+            const lines = skipped.map((s) => `  - ${s.filename}: ${s.reason}`).join('\n');
+            blocks.push({
+                type: 'document',
+                source: {
+                    type: 'text',
+                    media_type: 'text/plain',
+                    data: `=== SYSTEM NOTICE: some attachments could not be processed ===\nThe following files were attached but could NOT be read. Tell the user clearly which files failed and why. Do not pretend to have read them.\n${lines}`,
+                },
+            });
+        }
+        return blocks;
     }
     async formatOutgoingMessage(text) {
         let formatted = await this.messageFormatter.resolveUserTags(text);
@@ -785,27 +1533,31 @@ class Bot {
         formatted = formatted.replace(/(\[hailerTag\|[^\]]+\]\([a-f0-9]{24}\)\uFEFF?)\s*\([^)]+\)/gi, '$1');
         // Strip hailerTags inside markdown table rows (pipe in hailerTag|Name breaks table columns)
         formatted = formatted.split('\n').map(line => {
-            if (!line.trimStart().startsWith('|'))
+            if (!line.trimStart().startsWith('|')) {
                 return line;
+            }
             return line.replace(/\uFEFF?\[hailerTag\|([^\]]+)\]\([a-f0-9]{24}\)\uFEFF?/gi, '$1');
         }).join('\n');
         formatted = await this.resolveBareIds(formatted);
         return formatted;
     }
     async resolveBareIds(text) {
-        const bareIdPattern = /(?<!\()([a-f0-9]{24})(?!\)[^\[]*\[hailerTag)/gi;
+        const bareIdPattern = /(?<!\()([a-f0-9]{24})(?!\)[^[]*\[hailerTag)/gi;
         const matches = [...text.matchAll(bareIdPattern)];
         const idsToResolve = [];
         for (const match of matches) {
             const id = match[1];
-            if (new RegExp(`\\[hailerTag\\|[^\\]]+\\]\\(${id}\\)`, 'i').test(text))
+            if (new RegExp(`\\[hailerTag\\|[^\\]]+\\]\\(${id}\\)`, 'i').test(text)) {
                 continue;
+            }
             idsToResolve.push(id);
-            if (idsToResolve.length >= 5)
+            if (idsToResolve.length >= 5) {
                 break;
+            }
         }
-        if (idsToResolve.length === 0)
+        if (idsToResolve.length === 0) {
             return text;
+        }
         const resolutions = await Promise.all(idsToResolve.map(async (id) => {
             try {
                 const result = await this.toolExecutor.execute('show_activity_by_id', { activityId: id }, this.getUserContext());
@@ -814,8 +1566,9 @@ class Bot {
                     const j = resultText.match(/\{[\s\S]*\}/);
                     if (j) {
                         const p = JSON.parse(j[0]);
-                        if (p.name)
+                        if (p.name) {
                             return { id, name: p.name };
+                        }
                     }
                 }
             }
@@ -823,8 +1576,9 @@ class Bot {
             return null;
         }));
         for (const r of resolutions) {
-            if (!r)
+            if (!r) {
                 continue;
+            }
             text = text.replace(r.id, `\uFEFF[hailerTag|${r.name}](${r.id})\uFEFF`);
         }
         return text;
@@ -832,15 +1586,17 @@ class Bot {
     // ===== HELPERS =====
     async injectPendingContext(discussionId, conversation) {
         const state = this.signalRouter.getState(discussionId);
-        if (!state || state.contextBuffer.length === 0)
+        if (!state || state.contextBuffer.length === 0) {
             return;
+        }
         const pending = state.contextBuffer.splice(0);
         const lastMsg = conversation[conversation.length - 1];
         if (lastMsg?.role === 'user' && Array.isArray(lastMsg.content)) {
             const content = lastMsg.content;
             content.push({ type: 'text', text: `<context type="messages-during-processing">\n${pending.map(m => this.formatIncomingMessage(m)).join('\n\n')}\n</context>` });
-            for (const block of await this.resolveFileAttachments(pending))
+            for (const block of await this.resolveFileAttachments(pending)) {
                 content.push(block);
+            }
             this.opLogger.contextInject(discussionId, pending.length);
         }
     }
@@ -860,30 +1616,34 @@ class Bot {
         }
     }
     getToolStatus(toolUseBlocks) {
-        if (toolUseBlocks.length === 1)
+        if (toolUseBlocks.length === 1) {
             return TOOL_STATUS_LABELS[toolUseBlocks[0].name] || toolUseBlocks[0].name.replace(/_/g, ' ');
+        }
         return `${TOOL_STATUS_LABELS[toolUseBlocks[0].name] || toolUseBlocks[0].name.replace(/_/g, ' ')} (+${toolUseBlocks.length - 1} more)`;
     }
     getAnthropicTools() {
-        if (this.cachedTools)
+        if (this.cachedTools) {
             return this.cachedTools;
+        }
         const defs = this.toolExecutor.getToolDefinitions({
             allowedGroups: [tool_registry_1.ToolGroup.READ, tool_registry_1.ToolGroup.WRITE, tool_registry_1.ToolGroup.PLAYGROUND, tool_registry_1.ToolGroup.BOT_INTERNAL],
         });
-        const tools = defs.filter(d => BOT_TOOLS.has(d.name)).map(d => ({
+        const tools = defs.filter(d => tool_profiles_1.BOT_TOOLS.has(d.name)).map(d => ({
             name: d.name, description: d.description, input_schema: d.inputSchema,
         }));
-        if (tools.length > 0)
+        if (tools.length > 0) {
             tools[tools.length - 1].cache_control = { type: 'ephemeral' };
+        }
         this.cachedTools = tools;
         return tools;
     }
     async sendMessage(discussionId, text, links) {
         try {
             const msgData = { msg: text };
-            if (links?.length)
+            if (links?.length) {
                 msgData.links = links;
-            await this.client.socket.request('messenger.send', [msgData, discussionId]);
+            }
+            await this.client.socket.request(hailer_rpc_1.HailerRpc.Messenger.send, [msgData, discussionId]);
             this.opLogger.messageOut(discussionId, text.length, (text.match(/\[hailerTag\|/g) || []).length);
         }
         catch (error) {
@@ -891,13 +1651,29 @@ class Bot {
         }
     }
     getUserContext() {
-        if (!this.userContext)
+        if (!this.userContext) {
             throw new Error('Bot not started');
+        }
         return this.userContext;
     }
+    /** Full insight → source-workflow map from v3.insight.list (the endpoint list_insights renders). */
+    async fetchInsightWorkflowMap() {
+        const result = await this.getUserContext().hailer.request('v3.insight.list', [this._workspaceId]);
+        const insights = Array.isArray(result) ? result : (result?.details || result?.insights || []);
+        const map = new Map();
+        for (const insight of insights) {
+            if (!insight?._id) {
+                continue;
+            }
+            const wfIds = (insight.sources || []).map((src) => src?.workflowId).filter(Boolean);
+            map.set(insight._id, new Set(wfIds));
+        }
+        return map;
+    }
     trackTokenUsage(response, message, model) {
-        if (!response.usage)
+        if (!response.usage) {
             return;
+        }
         const { input_tokens, output_tokens } = response.usage;
         const cacheCreation = response.usage.cache_creation_input_tokens || 0;
         const cacheRead = response.usage.cache_read_input_tokens || 0;