@hailer/mcp 0.1.8 → 0.1.9

package/.claude/skills/publish-hailer-app/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: publish-hailer-app
+description: Guide for publishing Hailer apps to production
+---
+
+# Publish Hailer App Skill
+
+Guide for publishing Hailer apps to production using MCP tools.
+
+<critical>
+## MANDATORY: Validate Before Publishing
+
+The `publish_hailer_app` tool will SILENTLY FAIL if manifest.json is misconfigured.
+
+**YOU MUST validate these before calling publish_hailer_app:**
+
+1. Read `public/manifest.json` in the project
+2. Check `appId` exists and is 24 characters
+3. Check `version` exists and is NOT empty (e.g., "1.0.0")
+4. Check `versionDescription` exists and is NOT empty
+
+If ANY are missing/empty, FIX THEM FIRST before publishing.
+</critical>
+
+<validation-code>
+## Validation Steps (DO THIS FIRST)
+
+```
+1. Read({file_path: "{projectDir}/public/manifest.json"})
+
+2. Verify JSON contains:
+   - "appId": "24-char-id"        ← If missing: use create_app first
+   - "version": "1.0.0"           ← If empty: set to "1.0.0"
+   - "versionDescription": "..."  ← If empty: set to "Initial release"
+
+3. If any field missing/empty → Edit manifest.json to fix
+
+4. ONLY THEN call publish_hailer_app
+```
+</validation-code>
+
+<workflow>
+## Full Publishing Workflow
+
+### Step 1: Check if Production App Exists
+
+```javascript
+list_apps()
+```
+Look for your app with a `https://apps.hailer.com/...` URL (NOT localhost).
+
+### Step 2: Create Production App (if needed)
+
+If app doesn't exist or only has localhost URL:
+```javascript
+create_app({
+  name: "My App Name",
+  description: "What the app does"
+})
+```
+Returns new appId with production URL.
+
+### Step 3: Validate & Fix manifest.json
+
+Read the manifest:
+```javascript
+Read({file_path: "{projectDir}/public/manifest.json"})
+```
+
+Required structure:
+```json
+{
+  "appId": "695816e2ba1d8bef3af7e018",
+  "version": "1.0.0",
+  "versionDescription": "Initial production release"
+}
+```
+
+**If appId missing:** Add the ID from Step 2
+**If version empty:** Set to "1.0.0"
+**If versionDescription empty:** Set to "Initial release"
+
+### Step 4: Publish
+
+```javascript
+publish_hailer_app({
+  projectDirectory: "/path/to/app"
+})
+```
+
+### Step 5: Verify
+
+```javascript
+list_apps()
+```
+Confirm URL is `https://apps.hailer.com/...` (not localhost).
+</workflow>
+
+<silent-failure>
+## Why Silent Failures Happen
+
+The SDK publish script requires `version` and `versionDescription` in manifest.json.
+If missing/empty, the tool returns "Success" but files are NOT uploaded.
+
+**Symptoms of silent failure:**
+- Tool says "App Published Successfully!"
+- But app URL is still `http://localhost:3000`
+- Or production URL returns 403/404
+
+**Always validate manifest BEFORE publishing.**
+</silent-failure>
+
+<dev-vs-prod>
+## Dev vs Production Apps
+
+| Type | URL | Created By | Can Publish To |
+|------|-----|------------|----------------|
+| Dev | `http://localhost:3000` | `scaffold_hailer_app` | NO - stays localhost |
+| Prod | `https://apps.hailer.com/...` | `create_app` | YES |
+
+**Key insight:** Dev apps (scaffolded) will ALWAYS use localhost.
+To deploy to production, create a NEW app with `create_app`.
+</dev-vs-prod>
+
+<updating>
+## Updating Published Apps
+
+1. Bump version in manifest.json:
+```json
+{
+  "version": "1.0.1",
+  "versionDescription": "Fixed data loading bug"
+}
+```
+
+2. Publish:
+```javascript
+publish_hailer_app({
+  projectDirectory: "/path/to/app"
+})
+```
+
+New version replaces old at same URL.
+</updating>
+
+<sharing>
+## Sharing Apps
+
+```javascript
+// Entire workspace
+add_app_member({ appId: "...", member: "network_{workspaceId}" })
+
+// Team
+add_app_member({ appId: "...", member: "team_{teamId}" })
+
+// User
+add_app_member({ appId: "...", member: "user_{userId}" })
+```
+</sharing>
+
+<checklist>
+## Pre-Publish Checklist
+
+- [ ] Production app exists (`create_app`, not scaffold)
+- [ ] manifest.json `appId` is 24 chars (not empty)
+- [ ] manifest.json `version` is set (e.g., "1.0.0")
+- [ ] manifest.json `versionDescription` is set (not empty)
+- [ ] node_modules exists (dependencies installed)
+</checklist>

package/.claude/skills/tool-parameter-usage/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: tool-parameter-usage
+description: Extract IDs from context and use correct parameter formats for Hailer tools
+triggers: Tool validation failed with "Required" error, empty receivedArgs, or field format errors
+---
+
+<problem>
+LLM calls tools with empty parameters `{}` even when context contains required IDs, or uses wrong parameter names/formats.
+</problem>
+
+<context-extraction>
+The `<incoming>` tag in messages contains critical IDs. ALWAYS extract and use them:
+
+```xml
+<incoming activityId="69384669b7826c5d9ec4e07c" discussionId="69384669b7826c5d9ec4e07d">
+  User message here
+</incoming>
+```
+
+**Extract before calling tools:**
+- `activityId` → use for `show_activity_by_id`, `update_activity`
+- `discussionId` → use for `get_activity_from_discussion`, `add_discussion_message`
+</context-extraction>
+
+<correct>
+```typescript
+// Context: <incoming activityId="69384669b7826c5d9ec4e07c" discussionId="69384669b7826c5d9ec4e07d">
+
+// ✅ CORRECT - Extract activityId from context
+show_activity_by_id({
+  activityId: "69384669b7826c5d9ec4e07c"
+});
+
+// ✅ CORRECT - Single update mode uses activityId
+update_activity({
+  activityId: "69384669b7826c5d9ec4e07c",
+  fields: { "fieldId123": 78 }
+});
+
+// ✅ CORRECT - Bulk update mode uses _id (NOT activityId)
+update_activity({
+  activities: [{
+    _id: "69384669b7826c5d9ec4e07c",
+    fields: { "fieldId123": 78 }
+  }]
+});
+
+// ✅ CORRECT - numericunit field = plain number
+update_activity({
+  activityId: "69384669b7826c5d9ec4e07c",
+  fields: { "weightFieldId": 78 }
+});
+
+// ✅ CORRECT - Get activity from discussion
+get_activity_from_discussion({
+  discussionId: "69384669b7826c5d9ec4e07d"
+});
+```
+</correct>
+
+<wrong>
+```typescript
+// ❌ WRONG - Empty parameters (ignoring context)
+show_activity_by_id({});
+// Error: activityId: Required, receivedArgs={}
+
+// ❌ WRONG - Using activityId in bulk mode (should be _id)
+update_activity({
+  activities: [{
+    activityId: "69384669b7826c5d9ec4e07c",  // WRONG KEY
+    fields: { "fieldId123": 78 }
+  }]
+});
+// Error: activities.0._id: Required
+
+// ❌ WRONG - Passing object for numericunit field
+update_activity({
+  activityId: "69384669b7826c5d9ec4e07c",
+  fields: {
+    "weightFieldId": { "type": "numericunit", "value": 78 }  // WRONG FORMAT
+  }
+});
+// Error: "Weight" must be a number
+
+// ❌ WRONG - Empty list_activities call
+list_activities({});
+// Error: workflowId: Required, phaseId: Required
+```
+</wrong>
+
+<fix>
+**Before calling ANY tool:**
+1. Check `<incoming>` tag for `activityId` and `discussionId`
+2. Extract these values and pass them to tools
+
+**Parameter rules:**
+| Tool | Single mode | Bulk mode |
+|------|-------------|-----------|
+| `update_activity` | `activityId` | `activities[].\_id` |
+| `show_activity_by_id` | `activityId` | N/A |
+| `get_activity_from_discussion` | `discussionId` | N/A |
+
+**Field value formats:**
+| Field type | Value format |
+|------------|--------------|
+| `numericunit` | Plain number: `78` |
+| `text` | Plain string: `"hello"` |
+| `activitylink` | Activity ID string: `"abc123..."` |
+| `select` | Option key: `"option_key"` |
+
+**Never pass objects with `type` metadata** - Hailer API expects plain values.
+</fix>

package/CLAUDE.md

@@ -163,6 +163,7 @@ Community agents are shared via the Hailer Agent Marketplace (separate git repo)
 **Installed marketplace agents:**
 No marketplace agents installed.
 
+
 **Use plugin agents:**
 ```
 Task(subagent_type="plugin:agent-name", prompt="...", model="haiku|sonnet")
@@ -182,11 +183,14 @@ When user asks to install plugins or set up the marketplace:
    /plugin install <plugin-name>
    ```
 
-2. Tell user: "Restart Claude Code to load the new agents."
+2. Tell user: "Restart Claude Code to load the plugin. Use `claude -c` to keep your conversation context."
 
-Available plugins: `permissions-handler`, `hailer-agents`
+Available plugins: `permissions-handler`, `voice-notifications`
 
 After restart, sync hook updates this file automatically with installed agents.
+
+**IMPORTANT:** After installing OR uninstalling plugins, always tell the user:
+> "Restart required for changes to take effect. Run `claude -c` to restart while keeping your conversation context."
 </plugin-setup>
 
 <plugin-contributing>

package/REFACTOR_STATUS.md

@@ -0,0 +1,127 @@
+# Client Refactor Status
+
+## Completed
+
+### Services Created (src/client/services/)
+1. **message-formatter.ts** - Tag formatting, mention resolution, activity linking
+2. **mcp-client.ts** - MCP server communication, tool schema loading
+3. **session-logger.ts** - Activity session tracking, idle detection, session flushing
+4. **agent-registry.ts** - Agent Directory, Positions, Teams, Tool Registry, MCP Config
+
+### Files Moved (src/client/agents/)
+1. **definitions.ts** (was specialists.ts) - Specialist definitions
+2. **orchestrator.ts** (was orchestrator-daemon.ts) - Updated imports ✓
+3. **specialist.ts** (was specialist-daemon.ts) - Updated imports ✓
+
+### Files Renamed (src/client/)
+1. **factory.ts** (was daemon-factory.ts) - Needs import updates
+2. **bot-manager.ts** (was multi-bot-manager.ts) - Needs import updates
+
+### Types Extracted
+- **types.ts** - Already complete with all interfaces and constants
+
+## Remaining Work
+
+### 1. Create agents/base.ts
+Extract from chat-agent-daemon.ts (2109 lines):
+- Core LLM loop (~500 lines target)
+- Message queue management
+- Abstract getSystemPrompt()
+- Inject services via constructor:
+  - MessageFormatterService
+  - McpClientService
+  - SessionLoggerService
+  - AgentRegistryService
+
+### 2. Update factory.ts imports
+```typescript
+// Change:
+import { ChatAgentDaemon } from "./chat-agent-daemon";
+import { OrchestratorDaemon } from "./orchestrator-daemon";
+import { SpecialistDaemon } from "./specialist-daemon";
+import { SPECIALISTS } from "./specialists";
+import { MultiBotManager, BotClient } from "./multi-bot-manager";
+
+// To:
+import { ChatAgentDaemon } from "./agents/base";
+import { OrchestratorDaemon } from "./agents/orchestrator";
+import { SpecialistDaemon } from "./agents/specialist";
+import { SPECIALISTS } from "./agents/definitions";
+import { MultiBotManager, BotClient } from "./bot-manager";
+```
+
+### 3. Create index.ts (public exports)
+```typescript
+export * from "./types";
+export * from "./bot-manager";
+export * from "./factory";
+export * from "./agents/base";
+export * from "./agents/orchestrator";
+export * from "./agents/specialist";
+export * from "./agents/definitions";
+export * from "./services/message-formatter";
+export * from "./services/mcp-client";
+export * from "./services/session-logger";
+export * from "./services/agent-registry";
+```
+
+### 4. Update all imports in codebase
+Files that import from src/client/:
+- src/core.ts
+- src/config.ts
+- Any test files
+
+### 5. Delete old files
+After verifying build:
+- src/client/chat-agent-daemon.ts (replaced by agents/base.ts)
+
+### 6. Verify build
+```bash
+npm run build
+```
+
+## Architecture
+
+### Before
+```
+src/client/
+├── chat-agent-daemon.ts (2109 lines - BLOATED)
+├── orchestrator-daemon.ts
+├── specialist-daemon.ts
+├── specialists.ts
+├── daemon-factory.ts
+├── multi-bot-manager.ts
+└── types.ts
+```
+
+### After
+```
+src/client/
+├── index.ts                     # Public exports
+├── factory.ts                   # DaemonManager
+├── bot-manager.ts               # MultiBotManager
+├── types.ts                     # All interfaces
+│
+├── agents/
+│   ├── base.ts                  # Core LLM loop (~500 lines)
+│   ├── orchestrator.ts          # HAL orchestrator ✓
+│   ├── specialist.ts            # Domain experts ✓
+│   └── definitions.ts           # SPECIALISTS config ✓
+│
+└── services/
+    ├── message-formatter.ts     # Tags, mentions, links ✓
+    ├── mcp-client.ts            # Tool calling ✓
+    ├── session-logger.ts        # Session logging ✓
+    └── agent-registry.ts        # Agent Directory registration ✓
+```
+
+## Next Steps
+
+1. Create agents/base.ts with service injection
+2. Update factory.ts imports
+3. Update bot-manager.ts imports (if any internal references)
+4. Create index.ts
+5. Update imports in src/core.ts and other files
+6. Run npm run build
+7. Delete chat-agent-daemon.ts
+8. Test the refactored code

package/dist/client/agents/base.d.ts

@@ -0,0 +1,202 @@
+/**
+ * Chat Agent Daemon
+ *
+ * A persistent LLM conversation that monitors all workspace chats.
+ * The LLM maintains context across messages and decides what to respond to.
+ *
+ * Architecture:
+ * - One daemon per bot client
+ * - Subscribes to ALL messenger.new signals (not filtered)
+ * - LLM sees every message with priority markers
+ * - LLM decides: RESPOND / IGNORE / ACTION
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { BotClient } from "../bot-manager";
+import { HailerSignal } from "../../mcp/signal-handler";
+import { Logger } from "../../lib/logger";
+import { ToolSchemaLoader, ToolIndexEntry } from "../tool-schema-loader";
+import { ToolInput, McpToolResult } from "../types";
+import { AgentRegistryService } from "../services/agent-registry";
+import { ConversationManager, ConversationMessage } from "../services/conversation-manager";
+import { McpClientService } from "../services/mcp-client";
+import { MessageFormatterService } from "../services/message-formatter";
+import { MessageClassifier } from "../services/message-classifier";
+import { SessionLoggerService } from "../services/session-logger";
+import { ToolExecutor } from "../services/tool-executor";
+import { WorkspaceSchemaCacheService } from "../services/workspace-schema-cache";
+import { SessionMetrics, ActivitySession, MessagePriority, IncomingMessage, ConversationState } from "../types";
+export type { IncomingMessage, MessagePriority, SessionMetrics, ActivitySession };
+export interface ChatAgentDaemonConfig {
+    botClient: BotClient;
+    mcpServerUrl: string;
+    anthropicApiKey: string;
+    model?: string;
+    maxContextMessages?: number;
+}
+export declare class ChatAgentDaemon {
+    protected logger: Logger;
+    protected client: Anthropic;
+    protected botClient: BotClient;
+    protected config: ChatAgentDaemonConfig;
+    protected toolSchemaLoader: ToolSchemaLoader;
+    protected isProcessing: boolean;
+    protected messageQueue: IncomingMessage[];
+    protected processedMessageIds: Set<string>;
+    private typingInterval;
+    private typingDiscussionId;
+    private static TYPING_REFRESH_MS;
+    protected toolIndex: ToolIndexEntry[];
+    protected minimalTools: Anthropic.Tool[];
+    /** Message classifier - handles message extraction and priority classification */
+    protected messageClassifier: MessageClassifier | null;
+    /** Conversation manager - handles per-discussion context and LRU cache */
+    protected conversationManager: ConversationManager | null;
+    /** MCP client service - handles tool schema loading and execution */
+    protected mcpClient: McpClientService | null;
+    /** Tool executor - handles tool execution and write tracking */
+    protected toolExecutor: ToolExecutor | null;
+    /** Agent registration service - handles Agent Directory, Position, Team, etc. */
+    protected registryService: AgentRegistryService | null;
+    /** Message formatting service - handles tag resolution and formatting */
+    protected messageFormatter: MessageFormatterService | null;
+    /** Session logging service - handles activity session tracking */
+    protected sessionLogger: SessionLoggerService | null;
+    /** Workspace schema cache - dynamic workflow/field ID lookup */
+    protected schemaCache: WorkspaceSchemaCacheService | null;
+    /** Current discussion context for tracking */
+    protected currentDiscussionId: string | null;
+    protected currentLinkedActivityId: string | null;
+    constructor(config: ChatAgentDaemonConfig);
+    /**
+     * Initialize the daemon - load tools and subscribe to signals
+     */
+    initialize(): Promise<void>;
+    /**
+     * Extract and classify incoming message from signal
+     * Can be overridden in subclasses to customize filtering
+     */
+    protected extractIncomingMessage(signal: HailerSignal): Promise<IncomingMessage | null>;
+    /**
+     * Handle incoming signal from Hailer
+     */
+    private handleSignal;
+    /**
+     * Process queued messages through the LLM
+     * Note: Uses flag-first pattern to prevent race conditions
+     */
+    private processQueue;
+    /**
+     * Process a single message through the persistent LLM conversation
+     */
+    private processMessage;
+    /**
+     * Format incoming message for LLM consumption
+     */
+    private formatIncomingMessage;
+    /**
+     * Load and inject memory for an activity into conversation context
+     * Called when entering a new discussion that's linked to an activity
+     */
+    private injectMemoryForActivity;
+    /**
+     * Execute tool calls and continue the conversation
+     * Simple passthrough - just execute tools and return results to LLM
+     */
+    protected executeToolsAndContinue(toolUseBlocks: Anthropic.ToolUseBlock[], originalMessage: IncomingMessage): Promise<void>;
+    /**
+     * Handle LLM response
+     * Override in subclasses to customize response handling
+     */
+    protected handleLlmResponse(response: Anthropic.Message, originalMessage: IncomingMessage): Promise<void>;
+    /**
+     * Start typing indicator with auto-refresh interval
+     * Keeps refreshing every 3 seconds until stopTypingIndicator is called
+     */
+    protected startTypingIndicator(discussionId: string): void;
+    /**
+     * Stop typing indicator and clear refresh interval
+     */
+    protected stopTypingIndicator(): void;
+    /**
+     * Send typing signal to Hailer API
+     * API: messenger.set_discussion_typing_state(discussionId, typingState)
+     */
+    private sendTypingSignal;
+    /**
+     * Post a response to a discussion
+     * Automatically converts @mentions and #activity tags to Hailer tags
+     * Includes links metadata required for tags to work
+     */
+    protected postResponse(discussionId: string, content: string): Promise<void>;
+    /**
+     * Get the system prompt for the daemon
+     * MUST be overridden in subclasses
+     */
+    protected getSystemPrompt(): string;
+    /**
+     * Get tool whitelist for this agent
+     * Override in subclass to limit which tools are available
+     * Return null for all tools, or array of tool names
+     */
+    protected getToolWhitelist(): string[] | null;
+    /**
+     * Preprocess tool input before execution
+     * Override in subclass to inject context (e.g., sourceActivityId)
+     * @param toolName - Name of the tool being called
+     * @param input - Original tool input from LLM
+     * @returns Processed input (may be modified)
+     */
+    protected preprocessToolInput(toolName: string, input: ToolInput): ToolInput;
+    /**
+     * Call MCP tool (delegates to McpClientService)
+     * Protected for subclass access
+     */
+    protected callMcpTool(name: string, args: ToolInput): Promise<McpToolResult>;
+    /**
+     * Stop the daemon
+     * Flushes all pending activity sessions before stopping
+     */
+    stop(): Promise<void>;
+    /**
+     * Get current conversation state (for debugging)
+     */
+    getConversationState(): ConversationState;
+    /**
+     * Get full conversation for a specific discussion (for debugging)
+     */
+    getFullConversation(discussionId?: string): ConversationMessage[];
+    /**
+     * Get agent's display name (override in subclass for custom names)
+     * Default implementation uses the actual Hailer user name from BotClient
+     */
+    protected getAgentName(): {
+        firstName: string;
+        lastName: string;
+    };
+    /**
+     * Get agent's description/system prompt (override in subclass)
+     */
+    protected getAgentDescription(): string;
+    /**
+     * Get default team ID from workspace cache
+     * Returns the first available team, or undefined if no teams exist
+     *
+     * Teams structure in init is: { teams: { workspaceId: { teamId: teamData, ... } } }
+     */
+    protected getDefaultTeamId(): string | undefined;
+    /**
+     * Get agent's Position details (override in subclass for custom positions)
+     */
+    protected getPositionDetails(): {
+        name: string;
+        purpose: string;
+        personaTone: string;
+        coreCapabilities: string;
+        boundaries: string;
+    };
+    /**
+     * Get agent directory ID
+     */
+    getAgentDirectoryId(): string | null;
+}
+//# sourceMappingURL=base.d.ts.map