@hailer/mcp 1.0.29 → 1.1.3

package/dist/bot/services/token-billing.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Token Billing Service
+ *
+ * Handles real-time token burning per workspace with balance checks at session start.
+ *
+ * Workspace Isolation:
+ * - Each workspace has its own token balance (managed by Hailer backend)
+ * - Balance check and burn calls include workspaceId for correct routing
+ *
+ * Behavior:
+ * - Check balance when new session starts -> reject if negative for that workspace
+ * - Burn tokens after each LLM API call -> real-time, charges correct workspace
+ * - Allow balance to go negative during active session -> don't interrupt
+ */
+import { Logger } from "../../lib/logger";
+import { HailerApiClient } from "../../mcp/utils/hailer-api-client";
+export interface TokenBurnPayload {
+    workspaceId: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    costUsd: number;
+    sessionId?: string;
+    activityId?: string;
+    model?: string;
+}
+export interface BalanceResponse {
+    workspaceId: string;
+    balance: number;
+    isNegative: boolean;
+    hasBalance: boolean;
+}
+export interface TokenBillingConfig {
+    enabled: boolean;
+}
+export declare class TokenBillingService {
+    private logger;
+    private hailerClient;
+    private balanceCache;
+    private pendingBalanceChecks;
+    private static CACHE_TTL_MS;
+    constructor(logger: Logger, hailerClient?: HailerApiClient);
+    /**
+     * Invalidate cached balance for a workspace
+     * Call this after write operations that cost tokens
+     */
+    invalidateCache(workspaceId: string): void;
+    /**
+     * Check workspace balance before starting a new session
+     * Returns balance info - caller decides whether to reject
+     *
+     * Error handling: On network failure, returns a default "OK" response
+     * to allow graceful degradation (don't block users due to billing errors)
+     */
+    checkBalance(workspaceId: string): Promise<BalanceResponse>;
+    /**
+     * Fetch balance from Hailer backend API
+     * Separated from checkBalance to support deduplication of concurrent requests
+     */
+    private fetchBalanceFromBackend;
+    /**
+     * Burn tokens after LLM API call - fire and forget
+     * Does not block the response pipeline
+     *
+     * Error handling: Logs errors but does not throw
+     */
+    burnTokens(payload: TokenBurnPayload): Promise<void>;
+    /**
+     * Internal burn implementation with proper error handling
+     */
+    private burnTokensInternal;
+    /**
+     * Calculate cost in USD based on token counts and model
+     */
+    calculateCost(inputTokens: number, outputTokens: number, cacheCreationTokens: number, cacheReadTokens: number, model?: string): number;
+}
+//# sourceMappingURL=token-billing.d.ts.map

package/dist/bot/services/token-billing.js

@@ -0,0 +1,233 @@
+"use strict";
+/**
+ * Token Billing Service
+ *
+ * Handles real-time token burning per workspace with balance checks at session start.
+ *
+ * Workspace Isolation:
+ * - Each workspace has its own token balance (managed by Hailer backend)
+ * - Balance check and burn calls include workspaceId for correct routing
+ *
+ * Behavior:
+ * - Check balance when new session starts -> reject if negative for that workspace
+ * - Burn tokens after each LLM API call -> real-time, charges correct workspace
+ * - Allow balance to go negative during active session -> don't interrupt
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TokenBillingService = void 0;
+// Claude Haiku 4.5 pricing (Oct 2025)
+const HAIKU_PRICING = {
+    inputPerMillion: 1.00, // $1.00 per 1M input tokens
+    outputPerMillion: 5.00, // $5.00 per 1M output tokens
+    cacheWritePerMillion: 1.25, // $1.25 per 1M cache write tokens (1.25x input)
+    cacheReadPerMillion: 0.10, // $0.10 per 1M cache read tokens (0.1x input)
+};
+// Claude Sonnet 4.5 pricing (Sep 2025)
+const SONNET_PRICING = {
+    inputPerMillion: 3.00, // $3.00 per 1M input tokens
+    outputPerMillion: 15.00, // $15.00 per 1M output tokens
+    cacheWritePerMillion: 3.75, // $3.75 per 1M cache write tokens (1.25x input)
+    cacheReadPerMillion: 0.30, // $0.30 per 1M cache read tokens (0.1x input)
+};
+const MODEL_PRICING = {
+    'claude-haiku-4-5-20251001': HAIKU_PRICING,
+    'claude-sonnet-4-5-20250929': SONNET_PRICING,
+};
+function getPricing(model) {
+    if (model) {
+        const match = MODEL_PRICING[model];
+        if (match)
+            return match;
+    }
+    return HAIKU_PRICING;
+}
+function getOutputWeights(pricing) {
+    return {
+        input: pricing.inputPerMillion / pricing.outputPerMillion,
+        output: 1.0,
+        cacheWrite: pricing.cacheWritePerMillion / pricing.outputPerMillion,
+        cacheRead: pricing.cacheReadPerMillion / pricing.outputPerMillion,
+    };
+}
+// ================================================================================
+// SERVICE
+// ================================================================================
+class TokenBillingService {
+    logger;
+    hailerClient = null;
+    balanceCache = new Map();
+    pendingBalanceChecks = new Map();
+    static CACHE_TTL_MS = 60_000; // 60 seconds
+    constructor(logger, hailerClient) {
+        this.logger = logger;
+        this.hailerClient = hailerClient || null;
+    }
+    /**
+     * Invalidate cached balance for a workspace
+     * Call this after write operations that cost tokens
+     */
+    invalidateCache(workspaceId) {
+        this.balanceCache.delete(workspaceId);
+        this.logger.debug("Balance cache invalidated", { workspaceId });
+    }
+    /**
+     * Check workspace balance before starting a new session
+     * Returns balance info - caller decides whether to reject
+     *
+     * Error handling: On network failure, returns a default "OK" response
+     * to allow graceful degradation (don't block users due to billing errors)
+     */
+    async checkBalance(workspaceId) {
+        if (!this.hailerClient) {
+            this.logger.warn("Balance check skipped - no Hailer client");
+            // Allow processing when we can't check balance (graceful degradation)
+            return { workspaceId, balance: 999, isNegative: false, hasBalance: true };
+        }
+        // Check cache first
+        const cached = this.balanceCache.get(workspaceId);
+        if (cached && Date.now() - cached.timestamp < TokenBillingService.CACHE_TTL_MS) {
+            const balance = cached.balance;
+            const cacheAge = Math.round((Date.now() - cached.timestamp) / 1000);
+            // Determine status
+            let status;
+            if (balance < 0) {
+                status = 'NEGATIVE - SHOULD NOT RESPOND';
+            }
+            else if (balance === 0) {
+                status = 'EMPTY - SHOULD NOT RESPOND';
+            }
+            else if (balance < 5) {
+                status = 'LOW';
+            }
+            else {
+                status = 'OK';
+            }
+            this.logger.debug(`BALANCE CHECK (CACHED) | ${workspaceId} | ${balance} tokens | ${status}`);
+            return {
+                workspaceId,
+                balance,
+                isNegative: balance < 0,
+                hasBalance: balance > 0,
+            };
+        }
+        // Deduplicate concurrent balance checks for the same workspace
+        const pending = this.pendingBalanceChecks.get(workspaceId);
+        if (pending) {
+            this.logger.debug(`BALANCE CHECK (DEDUP) | ${workspaceId} | reusing in-flight request`);
+            return pending;
+        }
+        const promise = this.fetchBalanceFromBackend(workspaceId);
+        this.pendingBalanceChecks.set(workspaceId, promise);
+        try {
+            return await promise;
+        }
+        finally {
+            this.pendingBalanceChecks.delete(workspaceId);
+        }
+    }
+    /**
+     * Fetch balance from Hailer backend API
+     * Separated from checkBalance to support deduplication of concurrent requests
+     */
+    async fetchBalanceFromBackend(workspaceId) {
+        try {
+            const result = await this.hailerClient.request('v3.mcp.getTokenBalance', [workspaceId]);
+            const balance = typeof result?.balance === "number" ? result.balance :
+                typeof result === "number" ? result : 0;
+            // Cache the result
+            this.balanceCache.set(workspaceId, { balance, timestamp: Date.now() });
+            // Determine status
+            let status;
+            if (balance < 0) {
+                status = 'NEGATIVE - SHOULD NOT RESPOND';
+            }
+            else if (balance === 0) {
+                status = 'EMPTY - SHOULD NOT RESPOND';
+            }
+            else if (balance < 5) {
+                status = 'LOW';
+            }
+            else {
+                status = 'OK';
+            }
+            this.logger.debug(`BALANCE CHECK | ${workspaceId} | ${balance} tokens | ${status}`);
+            return {
+                workspaceId,
+                balance,
+                isNegative: balance < 0,
+                hasBalance: balance > 0,
+            };
+        }
+        catch (error) {
+            this.logger.warn(`BALANCE CHECK FAILED | ${workspaceId} | ${error instanceof Error ? error.message : String(error)}`);
+            return { workspaceId, balance: 0, isNegative: false, hasBalance: false };
+        }
+    }
+    /**
+     * Burn tokens after LLM API call - fire and forget
+     * Does not block the response pipeline
+     *
+     * Error handling: Logs errors but does not throw
+     */
+    async burnTokens(payload) {
+        // Fire and forget - don't await in caller
+        this.burnTokensInternal(payload).catch((error) => {
+            this.logger.error("Token burn failed", {
+                workspaceId: payload.workspaceId,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        });
+    }
+    /**
+     * Internal burn implementation with proper error handling
+     */
+    async burnTokensInternal(payload) {
+        if (!this.hailerClient) {
+            this.logger.warn("Token burn skipped - no Hailer client");
+            return;
+        }
+        // Calculate output-normalized tokens (what backend expects)
+        const weights = getOutputWeights(getPricing(payload.model));
+        const normalizedTokens = Math.round(payload.inputTokens * weights.input +
+            payload.outputTokens * weights.output +
+            payload.cacheCreationTokens * weights.cacheWrite +
+            payload.cacheReadTokens * weights.cacheRead);
+        try {
+            const result = await this.hailerClient.request('v3.mcp.deductTokens', [{
+                    mcpToken: 'hL9xK2mNpQrS4tVwY6zA8bCD',
+                    workspaceId: payload.workspaceId,
+                    tokenAmount: normalizedTokens,
+                    model: 'claude-haiku',
+                    meta: {
+                        operation: 'chat'
+                    }
+                }]);
+            // Cache the new balance from response
+            if (result?.newBalance !== undefined) {
+                this.balanceCache.set(payload.workspaceId, {
+                    balance: result.newBalance,
+                    timestamp: Date.now()
+                });
+            }
+            this.logger.debug(`TOKEN DEDUCTION | ${payload.workspaceId} | ${normalizedTokens} tokens | $${payload.costUsd.toFixed(6)} | balance: ${result?.newBalance ?? 'N/A'}`);
+        }
+        catch (error) {
+            this.logger.warn(`TOKEN DEDUCTION FAILED | ${payload.workspaceId} | ${normalizedTokens} tokens | ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Calculate cost in USD based on token counts and model
+     */
+    calculateCost(inputTokens, outputTokens, cacheCreationTokens, cacheReadTokens, model) {
+        const pricing = getPricing(model);
+        const inputCost = (inputTokens / 1_000_000) * pricing.inputPerMillion;
+        const outputCost = (outputTokens / 1_000_000) * pricing.outputPerMillion;
+        const cacheWriteCost = (cacheCreationTokens / 1_000_000) * pricing.cacheWritePerMillion;
+        const cacheReadCost = (cacheReadTokens / 1_000_000) * pricing.cacheReadPerMillion;
+        const totalCost = inputCost + outputCost + cacheWriteCost + cacheReadCost;
+        // Round to 8 decimal places to avoid floating point issues
+        return Math.round(totalCost * 100_000_000) / 100_000_000;
+    }
+}
+exports.TokenBillingService = TokenBillingService;
+//# sourceMappingURL=token-billing.js.map

package/dist/bot/services/types.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Bot Services Types
+ *
+ * Shared types for bot service layer.
+ * These are decoupled from the agent system's types.
+ */
+/** Response from v3.discussion.message.latest */
+export interface MessageLatestResponse {
+    messages: HailerMessage[];
+}
+/** Discussion info returned by messenger.load_discussions */
+export interface DiscussionInfo {
+    _id: string;
+    participants: string[];
+    private?: boolean;
+    description?: string;
+    name?: string;
+    linked_activity?: string;
+    cid?: string;
+}
+/** Message data for messenger.send */
+export interface SendMessageData {
+    msg: string;
+    links?: Array<{
+        target: string;
+        targetType: string;
+        type: string;
+    }>;
+}
+/** Generic bot connection interface - decoupled from BotClient */
+export interface BotConnection {
+    client: {
+        socket: {
+            request: {
+                (method: 'v3.discussion.message.latest', args: [string]): Promise<MessageLatestResponse>;
+                (method: 'messenger.load_discussions', args: [string[]]): Promise<Record<string, DiscussionInfo>>;
+                (method: 'messenger.send', args: [SendMessageData, string]): Promise<void>;
+                (method: 'messenger.set_discussion_typing_state', args: [string, boolean]): Promise<void>;
+                (method: string, args: any[]): Promise<any>;
+            };
+        };
+    };
+    workspaceCache?: {
+        usersById: Record<string, {
+            id: string;
+            firstname?: string;
+            lastname?: string;
+            fullName?: string;
+        }>;
+        users: Array<{
+            id: string;
+            firstname?: string;
+            lastname?: string;
+            fullName?: string;
+        }>;
+        rawInit?: {
+            processes?: Array<{
+                _id: string;
+                name: string;
+            }>;
+        };
+    };
+}
+export type MessagePriority = "high" | "normal" | "low";
+/** File attachment in a Hailer message */
+export interface HailerFileAttachment {
+    _id: string;
+    filename?: string;
+    name?: string;
+    size?: number;
+    mime?: string;
+    type?: string;
+}
+/** Hailer discussion message from API */
+export interface HailerMessage {
+    _id: string;
+    msg?: string;
+    content?: string;
+    uid: string;
+    userName?: string;
+    type?: string;
+    replyTo?: string;
+    created?: number;
+    files?: HailerFileAttachment[];
+}
+/** Hailer user from search/workspace cache */
+export interface HailerUser {
+    _id: string;
+    firstname?: string;
+    lastname?: string;
+    fullName?: string;
+    email?: string;
+}
+/** File attachment info for incoming messages */
+export interface IncomingFileAttachment {
+    fileId: string;
+    filename: string;
+    size?: number;
+    mime?: string;
+}
+export interface IncomingMessage {
+    id: string;
+    discussionId: string;
+    workspaceId: string;
+    discussionName?: string;
+    linkedActivityId?: string;
+    linkedActivityName?: string;
+    senderId: string;
+    senderName: string;
+    content: string;
+    timestamp: number;
+    priority: MessagePriority;
+    priorityReason: string;
+    isReplyToBot: boolean;
+    isMention: boolean;
+    isDirectMessage: boolean;
+    fileAttachments?: IncomingFileAttachment[];
+}
+export interface DiscussionState {
+    contextBuffer: IncomingMessage[];
+    abortController: AbortController | null;
+    state: 'idle' | 'engaged';
+    consecutiveNonResponses: number;
+    lastProgressTime: number;
+}
+export interface SessionMetrics {
+    inputTokens: number;
+    outputTokens: number;
+    cacheCreationTokens: number;
+    cacheReadTokens: number;
+    toolCalls: number;
+    writeOperations: number;
+    messagesProcessed: number;
+    responsesPosted: number;
+    apiCalls: number;
+}
+/** Detail about a write operation */
+export interface WriteDetail {
+    tool: string;
+    what: string;
+    targetId?: string;
+}
+export interface ActivitySession {
+    activityId: string;
+    activityName: string;
+    discussionId: string;
+    workspaceId: string;
+    startTime: number;
+    lastActivityTime: number;
+    metrics: SessionMetrics;
+    actions: string[];
+    previousLogId: string | null;
+    conversation: string[];
+    writeDetails: WriteDetail[];
+    triggerRequest: string | null;
+    requestedBy: string | null;
+    requestedById: string | null;
+}
+export declare const SESSION_IDLE_TIMEOUT = 60000;
+/** MCP tool result from server */
+export interface McpToolResult {
+    content?: Array<{
+        text?: string;
+        type?: string;
+    }>;
+}
+/** Callback type for MCP tool calls */
+export type McpToolCallback = (name: string, args: any) => Promise<McpToolResult>;
+//# sourceMappingURL=types.d.ts.map

package/dist/bot/services/types.js

@@ -0,0 +1,12 @@
+"use strict";
+/**
+ * Bot Services Types
+ *
+ * Shared types for bot service layer.
+ * These are decoupled from the agent system's types.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SESSION_IDLE_TIMEOUT = void 0;
+// ===== CONSTANTS =====
+exports.SESSION_IDLE_TIMEOUT = 60_000; // 60 seconds
+//# sourceMappingURL=types.js.map

package/dist/bot/services/typing-indicator.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Typing Indicator Service
+ * Manages typing indicator state with auto-refresh for Hailer discussions
+ */
+import { Logger } from "../../lib/logger";
+import { BotConnection } from "./types";
+export declare class TypingIndicatorService {
+    private botConnection;
+    private logger;
+    private static TYPING_REFRESH_MS;
+    private typingIntervals;
+    constructor(botConnection: BotConnection, logger: Logger);
+    /**
+     * Start typing indicator with auto-refresh interval for a discussion
+     */
+    start(discussionId: string): void;
+    /**
+     * Stop typing indicator for a specific discussion, or all discussions (shutdown)
+     */
+    stop(discussionId?: string): void;
+    private sendSignal;
+}
+//# sourceMappingURL=typing-indicator.d.ts.map

package/dist/bot/services/typing-indicator.js

@@ -0,0 +1,60 @@
+"use strict";
+/**
+ * Typing Indicator Service
+ * Manages typing indicator state with auto-refresh for Hailer discussions
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypingIndicatorService = void 0;
+class TypingIndicatorService {
+    botConnection;
+    logger;
+    static TYPING_REFRESH_MS = 3000;
+    typingIntervals = new Map();
+    constructor(botConnection, logger) {
+        this.botConnection = botConnection;
+        this.logger = logger;
+    }
+    /**
+     * Start typing indicator with auto-refresh interval for a discussion
+     */
+    start(discussionId) {
+        if (this.typingIntervals.has(discussionId))
+            return;
+        this.sendSignal(discussionId, true);
+        const interval = setInterval(() => {
+            this.sendSignal(discussionId, true);
+        }, TypingIndicatorService.TYPING_REFRESH_MS);
+        this.typingIntervals.set(discussionId, interval);
+    }
+    /**
+     * Stop typing indicator for a specific discussion, or all discussions (shutdown)
+     */
+    stop(discussionId) {
+        if (discussionId) {
+            const interval = this.typingIntervals.get(discussionId);
+            if (interval) {
+                clearInterval(interval);
+                this.typingIntervals.delete(discussionId);
+                this.sendSignal(discussionId, false);
+            }
+        }
+        else {
+            // Shutdown: clear all
+            for (const [discId, interval] of this.typingIntervals) {
+                clearInterval(interval);
+                this.sendSignal(discId, false);
+            }
+            this.typingIntervals.clear();
+        }
+    }
+    sendSignal(discussionId, isTyping) {
+        this.botConnection.client.socket.request("messenger.set_discussion_typing_state", [
+            discussionId,
+            isTyping
+        ]).catch((error) => {
+            this.logger.debug("Typing indicator failed", { discussionId, isTyping, error: error?.message });
+        });
+    }
+}
+exports.TypingIndicatorService = TypingIndicatorService;
+//# sourceMappingURL=typing-indicator.js.map

package/dist/bot/services/workspace-schema-cache.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Workspace Schema Cache Service
+ *
+ * Dynamically discovers and caches workflow schemas per workspace.
+ * Replaces hardcoded workflow/field IDs with runtime lookup.
+ *
+ * WORKSPACE ISOLATION: Each workspace gets its own workflow IDs.
+ * Never use hardcoded IDs - always lookup via this cache.
+ *
+ * On bot startup:
+ * 1. Check memory cache first
+ * 2. If cache miss: Query list_workflows to find AI Agent workflows by name
+ * 3. If missing, install them from marketplace
+ * 4. Query get_workflow_schema to get field IDs
+ * 5. Store in memory cache for session duration
+ */
+import { Logger } from "../../lib/logger";
+import { McpToolCallback } from "./types";
+/** Cached workflow schema */
+export interface WorkflowSchema {
+    workflowId: string;
+    name: string;
+    phases: Record<string, string>;
+    fields: Record<string, string>;
+}
+/** Per-workspace cache */
+export interface WorkspaceSchemas {
+    workspaceId: string;
+    sessionLog?: WorkflowSchema;
+    agentDirectory?: WorkflowSchema;
+    positions?: WorkflowSchema;
+    teams?: WorkflowSchema;
+    toolRegistry?: WorkflowSchema;
+    mcpConfig?: WorkflowSchema;
+    initialized: boolean;
+}
+export declare class WorkspaceSchemaCacheService {
+    private logger;
+    private callMcpTool;
+    private cache;
+    constructor(logger: Logger, callMcpTool: McpToolCallback);
+    /**
+     * Initialize schema cache for a workspace
+     * Call this on bot startup after connecting to Hailer
+     *
+     * Set SKIP_SCHEMA_DISCOVERY=true to skip API calls on startup.
+     * HAL can discover workflows on-demand via MCP tools when needed.
+     */
+    initializeForWorkspace(workspaceId: string): Promise<WorkspaceSchemas>;
+    /**
+     * Get cached schemas for a workspace
+     */
+    getSchemas(workspaceId: string): WorkspaceSchemas | undefined;
+    /**
+     * Get Session Log schema for a workspace
+     */
+    getSessionLogSchema(workspaceId: string): WorkflowSchema | undefined;
+    /**
+     * Get Agent Directory schema for a workspace
+     */
+    getAgentDirectorySchema(workspaceId: string): WorkflowSchema | undefined;
+    /**
+     * Get Positions schema for a workspace
+     */
+    getPositionsSchema(workspaceId: string): WorkflowSchema | undefined;
+    /**
+     * Get Teams schema for a workspace
+     */
+    getTeamsSchema(workspaceId: string): WorkflowSchema | undefined;
+    /**
+     * Get Tool Registry schema for a workspace
+     */
+    getToolRegistrySchema(workspaceId: string): WorkflowSchema | undefined;
+    /**
+     * Get MCP Config schema for a workspace
+     */
+    getMcpConfigSchema(workspaceId: string): WorkflowSchema | undefined;
+    /**
+     * Check if a workspace has the AI Agent template installed
+     */
+    hasAgentTemplate(workspaceId: string): boolean;
+    /**
+     * Check if workflow name matches a pattern (case insensitive, ignores emojis)
+     */
+    private matchesPattern;
+    /**
+     * Map workflow list to schema slots (using pattern matching)
+     */
+    private mapWorkflowsToSchemas;
+    /**
+     * Load detailed schemas (phases, fields) for all found workflows
+     */
+    private loadDetailedSchemas;
+    /**
+     * Install AI Agent template from marketplace
+     */
+    private installAgentTemplate;
+    /**
+     * Parse workflows from list_workflows response
+     * Handles both raw JSON and markdown-wrapped JSON responses
+     */
+    private parseWorkflows;
+    /**
+     * Load detailed workflow schema (phases and fields) for an existing schema
+     */
+    private loadWorkflowSchemaDetails;
+    /**
+     * Parse phases from list_workflow_phases response
+     * Format: 1. **PhaseName**\n   - Phase ID: `phaseId`
+     */
+    private parsePhases;
+    /**
+     * Parse fields from get_workflow_schema response
+     * Stores fields by both label and key for flexible lookup
+     */
+    private parseFields;
+    /**
+     * Clear cache for a workspace (memory cache only)
+     */
+    clearCache(workspaceId?: string): void;
+}
+//# sourceMappingURL=workspace-schema-cache.d.ts.map