@hailer/mcp 0.1.6 → 0.1.9

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/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.8] - 15-12-2025
+
+### Fixed
+
+- Corrected marketplace git URL to `git@gitlab.com:hailer-repos/hailer-mcp-marketplace.git`
+
+## [0.1.7] - 15-12-2025
+
+### Changed
+
+- **Marketplace Sync Hook**:
+  - Changed from session-based to hash-based sync (tracks `installed_plugins.json` changes)
+  - Added support for root-level plugin structure: `{marketplace}/{plugin}/agents/`
+  - Per-project sync state to avoid unnecessary re-syncs
+  - Improved logging when plugin changes detected
+
+- **Plugin Documentation**:
+  - Restructured CLAUDE.md with separate `<plugin-setup>` and `<plugin-contributing>` sections
+  - Clearer instructions for marketplace installation and contribution
+
 ## [0.1.5] - 12-12-2025
 
 ### Added

package/CLAUDE.md

@@ -158,33 +158,54 @@ WITHOUT AGENTS: Use MCP tools directly
 <plugin-marketplace>
 Community agents are shared via the Hailer Agent Marketplace (separate git repo).
 
-**Install marketplace:**
-```
-/plugin marketplace add gitlab:hailer-repos/hailer-mcp-marketplace
-/plugin install hailer-agents
-```
-Then restart Claude Code.
+**Marketplace URL:** `git@gitlab.com:hailer-repos/hailer-mcp-marketplace.git`
+
+**Installed marketplace agents:**
+No marketplace agents installed.
+
 
 **Use plugin agents:**
 ```
 Task(subagent_type="plugin:agent-name", prompt="...", model="haiku|sonnet")
 ```
 
-**Installed marketplace agents:**
-No marketplace agents installed.
+**Agent sources:**
+- Default agents: `.claude/agents/` (shipped via npm)
+- Community agents: Plugin marketplace (installed separately)
+</plugin-marketplace>
 
+<plugin-setup>
+When user asks to install plugins or set up the marketplace:
 
+1. Tell user to run these slash commands:
+   ```
+   /plugin marketplace add git@gitlab.com:hailer-repos/hailer-mcp-marketplace.git
+   /plugin install <plugin-name>
+   ```
 
+2. Tell user: "Restart Claude Code to load the plugin. Use `claude -c` to keep your conversation context."
 
-**Contribute agents:**
-1. Clone `gitlab:hailer-repos/hailer-mcp-marketplace`
-2. Add agent to `agents/your-agent.md`
-3. Push to repo
+Available plugins: `permissions-handler`, `voice-notifications`
 
-**Agent sources:**
-- Default agents: `.claude/agents/` (shipped via npm)
-- Community agents: Plugin marketplace (installed separately)
-</plugin-marketplace>
+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>
+To contribute agents to the marketplace:
+
+1. Clone: `git clone git@gitlab.com:hailer-repos/hailer-mcp-marketplace.git`
+2. Create plugin structure:
+   ```
+   my-plugin/
+     .claude-plugin/plugin.json
+     agents/agent-my-agent.md
+   ```
+3. Follow agent structure from `<agent-structure>` section
+4. Push to repo
+</plugin-contributing>
 
 <directory>
 ```

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