@hailer/mcp 0.1.2 → 0.1.4

package/.claude/skills/insight-join-patterns/SKILL.md

@@ -1,22 +1,24 @@
-# Insight JOIN Patterns
+---
+name: insight-join-patterns
+description: Correct JOIN syntax for Hailer insights with ActivityLink fields
+triggers: JOIN query errors, missing columns, NULL results in insight queries
+---
 
-## Pattern
+<problem>
 When joining workflows with ActivityLink fields in Hailer insights, you must:
 1. Include `_id` meta field in BOTH source definitions
 2. Join ON the activitylink field value equals target _id
 3. Use the activitylink fieldId (NOT the key) for the JOIN condition
+</problem>
 
-## Critical Rules
-
-**Always Required:**
+<rules>
 - Both workflows need `{ name: 'id', meta: '_id' }` in their fields array
 - JOIN condition: `source1.activityLinkFieldName = source2.id`
 - Use LEFT JOIN for optional relationships (activitylink can be null)
 - Use INNER JOIN only when relationship must exist
+</rules>
 
-## Correct Examples
-
-### Basic ActivityLink JOIN
+<correct>
 ```javascript
 // Players workflow has "club" field (activitylink to Clubs workflow)
 {
@@ -42,7 +44,38 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
   query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
 }
 ```
+</correct>
+
+<wrong>
+```javascript
+// ❌ WRONG - Missing _id in clubs source
+{
+  sources: [
+    {
+      name: 'p',
+      workflowId: 'players-id',
+      fields: [
+        { name: 'player_name', meta: 'name' },
+        { name: 'id', meta: '_id' },
+        { name: 'club', fieldId: 'club-field-id' }
+      ]
+    },
+    {
+      name: 'c',
+      workflowId: 'clubs-id',
+      fields: [
+        { name: 'club_name', meta: 'name' }
+        // Missing: { name: 'id', meta: '_id' }
+      ]
+    }
+  ],
+  query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
+}
+// Error: "no such column: c.id"
+```
+</wrong>
 
+<examples>
 ### Three-Way JOIN (Tasks -> Topics -> Projects)
 ```javascript
 {
@@ -53,7 +86,7 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
       fields: [
         { name: 'task_name', meta: 'name' },
         { name: 'id', meta: '_id' },
-        { name: 'topic', fieldId: 'topic-field-id' }  // Links to Topics
+        { name: 'topic', fieldId: 'topic-field-id' }
       ]
     },
     {
@@ -62,7 +95,7 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
       fields: [
         { name: 'topic_name', meta: 'name' },
         { name: 'id', meta: '_id' },
-        { name: 'project', fieldId: 'project-field-id' }  // Links to Projects
+        { name: 'project', fieldId: 'project-field-id' }
       ]
     },
     {
@@ -75,10 +108,7 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
     }
   ],
   query: `
-    SELECT
-      t.task_name,
-      top.topic_name,
-      p.project_name
+    SELECT t.task_name, top.topic_name, p.project_name
     FROM t
     LEFT JOIN top ON t.topic = top.id
     LEFT JOIN p ON top.project = p.id
@@ -109,76 +139,16 @@ When joining workflows with ActivityLink fields in Hailer insights, you must:
     }
   ],
   query: `
-    SELECT
-      teams.team_name,
-      COUNT(*) as match_count
+    SELECT teams.team_name, COUNT(*) as match_count
     FROM matches
     LEFT JOIN teams ON matches.home_team = teams.id
     GROUP BY teams.team_name
   `
 }
 ```
+</examples>
 
-## Wrong Examples
-
-### Missing _id Field
-```javascript
-// ❌ WRONG - Missing _id in clubs source
-{
-  sources: [
-    {
-      name: 'p',
-      workflowId: 'players-id',
-      fields: [
-        { name: 'player_name', meta: 'name' },
-        { name: 'id', meta: '_id' },
-        { name: 'club', fieldId: 'club-field-id' }
-      ]
-    },
-    {
-      name: 'c',
-      workflowId: 'clubs-id',
-      fields: [
-        { name: 'club_name', meta: 'name' }
-        // Missing: { name: 'id', meta: '_id' }
-      ]
-    }
-  ],
-  query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.id'
-}
-// Error: "no such column: c.id"
-```
-
-### Using Key Instead of FieldId
-```javascript
-// ❌ WRONG - Using field key instead of fieldId
-{
-  sources: [
-    {
-      name: 'p',
-      workflowId: 'players-id',
-      fields: [
-        { name: 'player_name', meta: 'name' },
-        { name: 'id', meta: '_id' },
-        { name: 'club', key: 'club' }  // Wrong! Use fieldId
-      ]
-    }
-  ]
-}
-```
-
-### Wrong JOIN Syntax
-```javascript
-// ❌ WRONG - Trying to join on name instead of id
-query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.club = c.club_name'
-
-// ❌ WRONG - Using field key in JOIN instead of column name
-query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.clubId = c.id'
-// (Should use column name from sources definition: p.club = c.id)
-```
-
-## Troubleshooting
-
+<troubleshooting>
 **Error: "no such column: c.id"**
 - Missing `{ name: 'id', meta: '_id' }` in target workflow source
 
@@ -189,21 +159,13 @@ query: 'SELECT p.player_name, c.club_name FROM p LEFT JOIN c ON p.clubId = c.id'
 **NULL results for joined data**
 - ActivityLink field is empty/null for some activities (expected with LEFT JOIN)
 - Use INNER JOIN if you only want activities with relationships
+</troubleshooting>
 
-## Workflow
-
-1. Get schema: `get_workflow_schema({ workflowId, phaseId })`
-2. Find ActivityLink field ID and target workflow ID
-3. Build sources with BOTH _id fields
-4. Preview query: `preview_insight({ sources, query })`
-5. Fix errors, re-preview
-6. Create insight when preview succeeds
-
-## Quick Checklist
-
+<checklist>
 Before creating an insight with JOINs:
 - [ ] Both workflow sources include `{ name: 'id', meta: '_id' }`
 - [ ] ActivityLink field uses `fieldId` (NOT `key`)
 - [ ] JOIN condition uses column names from sources (e.g., `p.club = c.id`)
 - [ ] Using LEFT JOIN (unless relationship required)
 - [ ] Tested with `preview_insight` first
+</checklist>

package/.claude/skills/json-only-output/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: json-only-output
+description: Fix agents adding prose after JSON responses
+triggers: Agent outputs explanation text after valid JSON
+---
+
+<problem>
+Agents violate JSON-only protocol by adding prose explanations AFTER their JSON response.
+</problem>
+
+<correct>
+```json
+{"status":"success","result":{"fields":["taskName","priority"]},"summary":"Read 2 fields"}
+```
+**STOP HERE. Nothing after closing brace.**
+</correct>
+
+<wrong>
+```json
+{"status":"success","result":{"fields":["taskName","priority"]},"summary":"Read 2 fields"}
+```
+
+The workflow has 2 fields defined in workspace/Tasks_123/fields.ts. You can now use these field IDs with dmitri for activity creation.
+
+**Action Required**: Run `npm run pull` to refresh.
+</wrong>
+
+<fix>
+1. Add to `<identity>`: "Output JSON. Full stop."
+2. Add to `<rules>`: **JSON ONLY** - Output closing brace, then STOP. Zero prose after JSON.
+3. Protocol section is NOT enough - agents ignore it without identity/rules reinforcement.
+</fix>

package/.claude/skills/optional-parameters/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: optional-parameters
+description: Omit optional parameters instead of passing empty values
+triggers: Tool error about empty array/string when parameter should be omitted
+---
+
+<problem>
+Tool parameter is required in schema but should be OMITTED (not passed at all) when not needed, rather than passed as empty array/string.
+</problem>
+
+<correct>
+```typescript
+// Update insight - only changing public flag
+// sources parameter exists in schema but NOT needed for this update
+update_insight({
+  insightId: "abc123",
+  public: false
+  // sources: NOT included - omit entirely
+});
+
+// Update insight - changing sources
+update_insight({
+  insightId: "abc123",
+  sources: [{
+    name: 'tasks',
+    workflowId: 'wf123',
+    fields: [{ name: 'title', meta: 'name' }]
+  }]
+  // Include sources when actually updating them
+});
+```
+</correct>
+
+<wrong>
+```typescript
+// ❌ WRONG - Passing empty array when parameter should be omitted
+update_insight({
+  insightId: "abc123",
+  public: false,
+  sources: []  // Error: sources must contain at least 1 items
+});
+
+// ❌ WRONG - Passing empty string
+update_activity({
+  activityId: "xyz",
+  name: ""  // Error: name cannot be empty
+});
+```
+</wrong>
+
+<fix>
+**Key distinction:**
+- **OMIT parameter**: Don't include it in the function call at all
+- **NOT same as empty value**: `[]`, `""`, `null`, `undefined` are NOT valid replacements for omission
+
+**When to omit:**
+- Updating insight public/name but NOT sources → omit sources
+- Updating activity field but NOT name → omit name
+- Any "required" schema parameter that's not relevant to current operation
+
+**Rule of thumb:**
+If you're not changing/using a value, OMIT the parameter entirely rather than passing empty/null.
+</fix>

package/.claude/skills/tool-response-verification/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: tool-response-verification
+description: Ensure agents verify tool execution before claiming success
+triggers: Agent returns success without checking tool result
+---
+
+<problem>
+Agent fabricates success response without verifying actual tool execution result.
+</problem>
+
+<correct>
+```typescript
+// Call tool
+const result = await update_insight({
+  insightId: "abc123",
+  public: false
+});
+
+// Verify tool response before returning to orchestrator
+if (result.error) {
+  return {
+    status: "error",
+    error: result.error,
+    summary: "Update failed"
+  };
+}
+
+return {
+  status: "success",
+  result: { updated: true, insight_id: result.id },
+  summary: "Updated insight"
+};
+```
+</correct>
+
+<wrong>
+```typescript
+// Call tool (that might fail)
+update_insight({ insightId: "abc123", public: false });
+
+// Immediately return success WITHOUT checking tool result
+return {
+  status: "success",
+  result: { updated: true },
+  summary: "Updated insight"
+};
+```
+</wrong>
+
+<fix>
+1. **NEVER assume tool success** - Always capture and check tool response
+2. **Return actual error messages** - If tool fails, return error status with real error message
+3. **Verify before claiming success** - Only return success after confirming tool execution succeeded
+4. **Test error paths** - If unsure about tool behavior, preview/test first
+
+This is a violation of Rule 1: "NEVER FABRICATE - Must call tools."
+Fabricating a success response when tool failed is the same as not calling the tool.
+</fix>

package/CLAUDE.md

@@ -2,163 +2,166 @@
 
 MCP tools for Hailer workspaces: workflows, activities, insights, and apps.
 
-**Core features:**
-- MCP Tools: Direct Hailer API access
-- Local Config: Synced workspace in `workspace/` directory
-- Type Generation: TypeScript enums for IDs
-
 ---
 
-# Default Agent System (Customizable)
-
-Ships with pre-configured agents. **These are defaults - modify, replace, or remove them.**
-
-| Action | How |
-|--------|-----|
-| Create custom | `agent-builder` or add to `.claude/agents/` |
-| Modify defaults | Edit `.claude/agents/*.md` |
-| Disable agents | Move to `docs/agents/`, update this file |
-
-## You Are The Orchestrator
+<identity>
+YOU ARE THE ORCHESTRATOR.
 
-**You (Claude Code) are the orchestrator.** You route requests to specialized agents and run commands they return.
+You route tasks to specialized agents. You run commands they return. You summarize results for users.
 
-**Do directly:** Answer from context, summarize results, run push/sync commands returned by agents
-**Delegate:** File reads, API calls, creation, updates, complex reasoning
+NEVER forget: You delegate, agents execute, you report back.
+</identity>
 
-## Default Agents
+<orchestrator-rules>
+DO DIRECTLY: Answer from context, summarize agent results, run push/sync commands
+DELEGATE TO AGENTS: File reads, API calls, data creation/updates, complex reasoning
 
-> Customize by editing `.claude/agents/` files.
+Agents return JSON. You interpret it for the user.
+</orchestrator-rules>
 
+<agents>
 | Pattern | Agent | Model |
 |---------|-------|-------|
-| Read data/schema | `kenji` | Haiku |
-| Activity CRUD | `dmitri` | Haiku |
-| Discussions/chat | `yevgeni` | Haiku |
-| Config audit | `bjorn` | Haiku |
-| **Create workflows, fields, phases** | `helga` | Sonnet |
-| **Workspace setup** | `helga` | Sonnet |
-| SQL insights | `viktor` | Sonnet |
-| Function fields | `alejandro` | Sonnet |
-| MCP tools | `gunther` | Sonnet |
-| Hailer apps | `giuseppe` | Sonnet |
-| Code review | `svetlana` | Sonnet |
-| New agents | `agent-builder` | Sonnet |
-| Create/update skills, improve agents | `ada` | Sonnet |
-| Document templates | `ingrid` | Sonnet |
-
-## Delegation Protocol
-
+| Read data/schema | `kenji` | haiku |
+| Activity CRUD | `dmitri` | haiku |
+| Discussions/chat | `yevgeni` | haiku |
+| Config audit | `bjorn` | haiku |
+| Workflows, fields, phases | `helga` | sonnet |
+| SQL insights | `viktor` | sonnet |
+| Function fields | `alejandro` | sonnet |
+| MCP tools | `gunther` | sonnet |
+| Hailer apps | `giuseppe` | sonnet |
+| Code review | `svetlana` | sonnet |
+| New agents | `agent-builder` | sonnet |
+| Skills, agent improvements | `ada` | sonnet |
+| Document templates | `ingrid` | sonnet |
+</agents>
+
+<delegation-protocol>
 ```
-Task(subagent_type="agent-name", prompt="JSON task spec", model="haiku")
+Task(subagent_type="agent-name", prompt="JSON task spec", model="haiku|sonnet")
 ```
 
-**Task spec:**
+INPUT:
 ```json
-{ "task": "action", "context": { "workflow_id": "...", "field_ids": {} }, "requirements": {}, "output": [] }
+{ "task": "action", "context": { "workflow_id": "...", "field_ids": {} }, "output": [] }
 ```
 
-**Response (JSON only, no prose):**
+OUTPUT (JSON only, no prose):
 ```json
-{ "status": "success", "result": {}, "summary": "max 50 chars" }
+{ "status": "success|error|ready_to_push|needs_confirmation", "result": {}, "summary": "max 50 chars" }
 ```
 
-**Critical:** Get IDs first (via kenji), then pass to execution agents.
-
-## Handling Push/Sync Commands
-
-**Safety hooks only trigger for YOUR (Claude Code) tool calls, not subagent tool calls.**
+FLOW: Get IDs first (kenji) → pass to execution agents (dmitri, helga, etc.)
+</delegation-protocol>
 
+<push-commands>
 When agents return `"status": "ready_to_push"`:
-
 ```json
 { "status": "ready_to_push", "commands": ["npm run fields-push"], "summary": "..." }
 ```
 
-**YOU must run these commands using the Bash tool.** This triggers the sdk-delete-guard hook which asks user for confirmation before destructive operations.
+YOU run these commands via Bash tool. This triggers safety hooks.
+Do NOT ask user to run them manually.
+</push-commands>
 
-Do NOT ask the user to run them manually - run them yourself so hooks work.
-
----
-
-# Workspace Setup
-
-**Use SDK commands, NOT MCP tools for workspace configuration.**
-
-Creating workflows, fields, phases:
-1. `npm run pull` - Get current state
-2. Edit TypeScript files in `workspace/`
-3. `npm run workflows-sync` (create/delete workflows)
-4. `npm run fields-push`, `npm run phases-push` (push changes)
+<needs-confirmation>
+When agents return `"status": "needs_confirmation"`:
+```json
+{
+  "status": "needs_confirmation",
+  "result": {
+    "pending_command": "npm run fields-push",
+    "safe_command": "yes | npm run fields-push",
+    "reason": "May delete resources"
+  },
+  "summary": "Needs user confirmation"
+}
+```
 
-**Never use `install_workflow`** - Always delegate to `helga` who uses SDK commands.
+YOU must:
+1. Use AskUserQuestion to confirm with user
+2. If confirmed: run the `safe_command` via Bash
+3. If declined: report cancellation to user
+</needs-confirmation>
 
 ---
 
-# Local-First Principle
-
-**Check local files BEFORE API calls.**
+<local-first>
+Check workspace/ BEFORE API calls.
 
-After `npm run pull`:
 ```
 workspace/
-├── workflows.ts          # Workflow IDs, names
-├── enums.ts              # Type-safe ID constants
-├── teams.ts, groups.ts   # Team/group definitions
+├── workflows.ts, enums.ts, teams.ts, groups.ts
 └── [Workflow]_[id]/
-    ├── fields.ts         # Field definitions
-    └── phases.ts         # Phase definitions
+    ├── fields.ts
+    └── phases.ts
 ```
 
-| Use Local | Use API |
-|-----------|---------|
-| Workflow/field/phase IDs | Activity data (live) |
-| Field types, labels, options | Activity counts |
-| Team/group definitions | Discussion messages |
+LOCAL: Workflow/field/phase IDs, field types, labels, options
+API: Activity data, counts, discussion messages
 
-**Refresh:** `npm run pull` (after changes, start of session, before building apps)
+REFRESH: `npm run pull`
+</local-first>
 
----
-
-# Safety Rules
+<safety>
+PROTECTED (hooks confirm): npm run push, *-push, *-sync
+SAFE: npm run pull, npm run generate
+</safety>
 
-**Protected (hooks confirm):** `npm run push`, `*-push`, `*-sync`
-**Safe:** `npm run pull`, `npm run generate`
+---
 
+<agent-structure>
+```markdown
+---
+name: lowercase-name
+description: What it does.\n\n<example>\nuser: "request"\nassistant: { "status": "success", "result": {}, "summary": "" }\n</example>
+model: haiku|sonnet
+tools: tool_1, tool_2
 ---
 
-# Directory Structure
+<identity>
+I am [Name]. [Philosophy].
+</identity>
+
+<handles>
+- Task 1
+- Task 2
+</handles>
+
+<skills>
+Load `skill-name` before complex tasks.
+</skills>
+
+<rules>
+1. **NEVER FABRICATE** - Must call tools.
+2. Rule 2
+3. Rule 3
+</rules>
+
+<protocol>
+Input: JSON task spec
+Output: JSON only
+Schema: { "status": "success|error", "result": {}, "summary": "" }
+</protocol>
+```
+</agent-structure>
+
+<customization>
+CREATE: Add to `.claude/agents/` following structure above
+MODIFY: Edit `.claude/agents/*.md`
+DISABLE: Move to `docs/agents/`
+WITHOUT AGENTS: Use MCP tools directly
+</customization>
 
+<directory>
 ```
 workspace/              # Local config (check FIRST)
 .claude/
-  agents/               # Agent definitions
+  agents/               # Agent definitions (XML tags, JSON output)
   hooks/                # Safety hooks
-  skills/               # Documentation
+  skills/               # On-demand documentation
   commands/             # Slash commands
   settings.json         # Permissions
 ```
-
----
-
-# Customization
-
-## Create Agent
-```yaml
-# .claude/agents/your-agent.md
----
-name: your-agent
-description: What it does.\n\n<example>...</example>
-model: haiku
----
-[Agent body with responsibilities]
-```
-
-## Modify Agents
-Edit `.claude/agents/*.md` - change personality, responsibilities, model, tools.
-
-## Disable Agents
-Move from `.claude/agents/` to `docs/agents/`, remove from delegation table.
-
-## Without Agents
-Use MCP tools directly: `list_workflows`, `create_activity`, `get_workflow_schema`, etc.
+</directory>

package/dist/client/mcp-assistant.d.ts

@@ -0,0 +1,21 @@
+/**
+ * MCP Assistant (Lightweight)
+ *
+ * Pure pass-through chatbot. System prompt is loaded on AI PC side.
+ * Just forwards user messages, no local processing.
+ */
+export declare class McpAssistant {
+    private client;
+    constructor(config: {
+        apiKey: string;
+        baseURL?: string;
+    });
+    /**
+     * Chat - pure pass-through to local LLM
+     */
+    chat(userMessage: string, conversationHistory?: Array<{
+        role: 'user' | 'assistant';
+        content: string;
+    }>): Promise<string>;
+}
+//# sourceMappingURL=mcp-assistant.d.ts.map