gemini-helper-friend 2.0.0

package/dist/config/types.d.ts

@@ -0,0 +1,90 @@
+/**
+ * TypeScript interfaces for YAML tool configuration
+ * Matches structure defined in yaml/tools.yaml
+ */
+/**
+ * Validation rules for parameters
+ */
+export interface YamlValidation {
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    format?: 'uri' | 'email' | 'uuid';
+    min?: number;
+    max?: number;
+    int?: boolean;
+    positive?: boolean;
+    negative?: boolean;
+    minItems?: number;
+    maxItems?: number;
+}
+/**
+ * Parameter definition in YAML
+ */
+export interface YamlParameter {
+    type: 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object';
+    required?: boolean;
+    default?: unknown;
+    description?: string;
+    validation?: YamlValidation;
+    items?: YamlParameter;
+    properties?: Record<string, YamlParameter>;
+}
+/**
+ * Tool definition in YAML
+ */
+export interface YamlToolConfig {
+    name: string;
+    category?: string;
+    capability?: string;
+    description: string;
+    parameters?: Record<string, YamlParameter>;
+}
+/**
+ * Global settings from YAML
+ */
+export interface YamlSettings {
+    defaults: {
+        model: string;
+        yolo_mode: boolean;
+        append_instructions: boolean;
+    };
+    cli: {
+        command: string;
+        flags: {
+            yolo: string;
+            model: string;
+            sandbox: string;
+            output_format: string;
+            approval_mode: string;
+            include_directories: string;
+        };
+    };
+}
+/**
+ * Root YAML configuration structure
+ */
+export interface YamlConfig {
+    version: string;
+    metadata: {
+        name: string;
+        displayName: string;
+        description: string;
+    };
+    settings: YamlSettings;
+    task_types: Record<string, any>;
+    tools: YamlToolConfig[];
+}
+/**
+ * MCP Tool definition (matches SDK)
+ */
+export interface McpTool {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/config/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,KAAK,GAAG,OAAO,GAAG,MAAM,CAAC;IAClC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;IACvE,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAAC;CAC5C;AAED;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,QAAQ,EAAE;QACR,KAAK,EAAE,MAAM,CAAC;QACd,SAAS,EAAE,OAAO,CAAC;QACnB,mBAAmB,EAAE,OAAO,CAAC;KAC9B,CAAC;IACF,GAAG,EAAE;QACH,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE;YACL,IAAI,EAAE,MAAM,CAAC;YACb,KAAK,EAAE,MAAM,CAAC;YACd,OAAO,EAAE,MAAM,CAAC;YAChB,aAAa,EAAE,MAAM,CAAC;YACtB,aAAa,EAAE,MAAM,CAAC;YACtB,mBAAmB,EAAE,MAAM,CAAC;SAC7B,CAAC;KACH,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,WAAW,EAAE,MAAM,CAAC;KACrB,CAAC;IACF,QAAQ,EAAE,YAAY,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAChC,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAED;;GAEG;AACH,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE;QACX,IAAI,EAAE,QAAQ,CAAC;QACf,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACpC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;KACrB,CAAC;CACH"}

package/dist/config/types.js

@@ -0,0 +1,6 @@
+/**
+ * TypeScript interfaces for YAML tool configuration
+ * Matches structure defined in yaml/tools.yaml
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/config/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/config/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/config/yaml/subagents.yaml

@@ -0,0 +1,449 @@
+# Gemini Helper Friend MCP - Subagent Configuration
+# YAML for metadata only - prompt templates in MDX files
+# Version: 2.0
+
+version: "2.0"
+
+metadata:
+  name: "gemini-helper-friend-mcp"
+  displayName: "Gemini - Helper Friend MCP"
+  description: "Autonomous AI helper with specialized task types"
+
+# ============================================================================
+# GLOBAL SETTINGS
+# ============================================================================
+
+settings:
+  defaults:
+    model: ""  # Uses fallback chain (see below)
+    yolo_mode: true
+    append_instructions: true
+  
+  # Model fallback chain - tries in order until one succeeds
+  # 1. gemini-3-flash-preview (fastest, newest)
+  # 2. gemini-3-pro-preview (more capable)
+  # 3. gemini-3-pro (stable)
+  # 4. gemini-2.5-flash (reliable fallback)
+  
+  cli:
+    command: "gemini"
+    # Per gemini --help: use positional prompt (--prompt is deprecated)
+    flags:
+      yolo: "--yolo"
+      model: "--model"
+      sandbox: "--sandbox"
+      output_format: "--output-format"
+      approval_mode: "--approval-mode"
+      include_directories: "--include-directories"
+
+# ============================================================================
+# TASK TYPE DEFINITIONS (Metadata Only - Templates in MDX)
+# ============================================================================
+
+task_types:
+  
+  completion-inspector:
+    display_name: "Completion Inspector"
+    description: "CTO-level code inspector that verifies if a task is TRULY 100% complete"
+    category: "verification"
+    default_model: ""  # Auto-select
+    template_file: "completion-inspector.mdx"
+    
+    tool_limits:
+      sequentialthinking_max: 30
+      sequentialthinking_min: 15
+      warpgrep_max: 20
+      warpgrep_min: 8
+      deep_research_max: 30
+      web_search_keywords_max: 100
+  
+  helper-friend:
+    display_name: "Helper Friend"
+    description: "Research companion for deep analysis, bug investigation, and informed decision-making"
+    category: "research"
+    default_model: ""  # Auto-select
+    template_file: "helper-friend.mdx"
+    
+    tool_limits:
+      sequentialthinking_max: 30
+      sequentialthinking_min: 10
+      warpgrep_max: 20
+      warpgrep_min: 4
+      deep_research_questions_max: 100
+      deep_research_per_call: 10
+      web_search_keywords_max: 500
+      web_search_per_call: 50
+      scrape_urls_max: 100
+      scrape_per_call: 30
+      reddit_posts_max: 100
+      reddit_per_call: 50
+  
+  manual-tester:
+    display_name: "Manual Tester"
+    description: "QA engineer who manually tests implementation using real Chrome browser and terminal"
+    category: "testing"
+    default_model: ""  # Auto-select
+    template_file: "manual-tester.mdx"
+    
+    tool_limits:
+      sequentialthinking_max: 30
+      sequentialthinking_min: 15
+      browser_interactions_max: 50
+      viewports_max: 5
+      screenshots_max: 30
+      api_calls_max: 50
+      warpgrep_max: 10
+
+# ============================================================================
+# TOOL DEFINITION (Single consolidated tool)
+# ============================================================================
+
+tools:
+  - name: check_subagent_task
+    category: status
+    capability: query
+    
+    description: |
+      **🔔 CHECK IF TASK IS READY - Notification-Aware Status Check**
+      
+      Check if an async subagent task is ready to retrieve results.
+      
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      📣 MCP NOTIFICATIONS (Automatic!)
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      
+      **You will receive automatic notifications when tasks complete!**
+      
+      When a task finishes, the server sends:
+      - `notifications/resources/list_changed` → New result resource available
+      - `notifications/resources/updated` → Specific task resource updated
+      
+      **If your client supports MCP notifications:**
+      - You'll see "🎉 Task 34567 is READY!" in the resources list
+      - Just read the `task://34567` resource to get the result
+      - No polling needed!
+      
+      **If your client doesn't support notifications:**
+      - Use this tool to poll the task status
+      - Check every 5-10 seconds until `status: completed`
+      
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      📚 RESOURCES (Best Practice!)
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      
+      **Completed tasks are also exposed as MCP Resources:**
+      
+      - **URI:** `task://34567`
+      - **Name:** `✅ Task 34567 - helper-friend`
+      - **Description:** `🎉 Task 34567 is READY! Result available.`
+      
+      You can read the resource directly instead of using this tool:
+      ```
+      Read resource: task://34567
+      ```
+      
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      📊 TASK STATES
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      
+      - `pending` - Task queued, not yet started
+      - `running` - 🔄 Task in progress (check back soon!)
+      - `completed` - ✅ **READY!** Result available
+      - `failed` - ❌ Task failed (error message available)
+      - `not_found` - Invalid task ID or expired (1 hour TTL)
+      
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      📋 RESPONSE EXAMPLES
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      
+      **🔄 Still Running:**
+      ```json
+      {
+        "task_id": 34567,
+        "status": "running",
+        "progress": 45,
+        "task_type": "helper-friend",
+        "started_at": "2024-01-15T10:30:00Z"
+      }
+      ```
+      → Wait and check again, or wait for notification!
+      
+      **✅ READY - Task Completed:**
+      ```json
+      {
+        "task_id": 34567,
+        "status": "completed",
+        "result": "## Helper Friend Result\n\n...",
+        "task_type": "helper-friend",
+        "completed_at": "2024-01-15T10:35:00Z",
+        "duration_seconds": 300
+      }
+      ```
+      → 🎉 Result is in the response! Also available as resource `task://34567`
+      
+      **❌ Task Failed:**
+      ```json
+      {
+        "task_id": 34567,
+        "status": "failed",
+        "error": "API quota exceeded",
+        "task_type": "helper-friend"
+      }
+      ```
+
+    parameters:
+      task_id:
+        type: integer
+        required: true
+        description: |
+          **[REQUIRED] 5-digit task ID**
+          
+          The task ID returned by `gemini-subagent` when called with `async: true`.
+          
+          Example: `34567`
+          
+          **Pro tip:** If your client supports notifications, you'll see completed
+          tasks appear in the resources list automatically!
+
+  - name: gemini-subagent
+    category: execution
+    capability: autonomous
+    
+    description: |
+      **🤖 GEMINI SUBAGENT - Specialized Task Execution**
+      
+      Single unified tool with three specialized modes via strict task_type enum.
+      
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      📋 TASK TYPE ENUM (Required - NO STRINGS, NO GUESSING!)
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      
+      Must be EXACTLY one of these three values:
+      
+      **1. `completion-inspector`** - CTO-Level Code Review
+      
+      **Purpose:** Verifies if a task is TRULY 100% complete
+      
+      **Uses:**
+      - Git diff analysis (line-by-line change review)
+      - Codebase search (find duplicates, missed abstractions)
+      - Pattern detection (consistency with existing code)
+      - Quality assessment (cleanup opportunities)
+      
+      **When to use:**
+      - ✅ After implementation, before marking "done"
+      - ✅ After major refactoring or feature work
+      - ✅ Before committing final changes
+      - ✅ When you suspect cleanup is needed
+      
+      **When NOT to use:**
+      - ❌ Task clearly still in progress
+      - ❌ Haven't made any changes yet
+      - ❌ Simple one-line changes
+      
+      **Output:** Completion %, requirements met/not met, quality issues, action items
+      
+      **Model:** Auto-select (Gemini CLI chooses best)
+      
+      ---
+      
+      **2. `helper-friend`** - Research Companion
+      
+      **Purpose:** Deep analysis, bug investigation, informed decision-making
+      
+      **Uses:**
+      - Codebase search (understand code structure)
+      - Web research (best practices, documentation)
+      - Deep research (technical questions with file attachments)
+      - Reddit consensus (community experiences)
+      
+      **When to use:**
+      - ✅ Bug investigation & root cause analysis
+      - ✅ Architecture & technology decisions
+      - ✅ Codebase understanding & discovery
+      - ✅ Best practices & pattern research
+      - ✅ Pre-implementation research
+      
+      **When NOT to use:**
+      - ❌ Already know what to do, just need to code
+      - ❌ Simple questions you can answer yourself
+      - ❌ Tasks needing immediate action, not research
+      
+      **Output:** Research findings, recommendations, trade-offs, sources
+      
+      **Model:** Auto-select (Gemini CLI chooses best)
+      
+      ---
+      
+      **3. `manual-tester`** - QA Engineer with Real Browser
+      
+      **Purpose:** Tests if implementation actually WORKS using real Chrome browser
+      
+      **Uses:**
+      - Chrome DevTools MCP (real browser interactions)
+      - Terminal/curl (API testing)
+      - Screenshots (visual verification)
+      - Console monitoring (JS error detection)
+      - Network inspection (API call verification)
+      
+      **When to use:**
+      - ✅ After completion-inspector confirms 100% code complete
+      - ✅ Frontend changes need testing
+      - ✅ Backend/API changes need testing
+      - ✅ Full flow verification
+      - ✅ Responsive design verification
+      
+      **When NOT to use:**
+      - ❌ Code isn't complete yet
+      - ❌ No user-facing changes to test
+      - ❌ Pure refactoring with no behavior changes
+      
+      **Output:** Test report with pass/fail, reproduction steps, screenshots, console errors
+      
+      **Model:** Auto-select (Gemini CLI chooses best)
+      
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      ⚙️ HOW IT WORKS
+      ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+      
+      1. You select task_type enum (strict validation)
+      2. System loads corresponding MDX template
+      3. Merges template + your prompt
+      4. Executes: `gemini --yolo -p "[merged_prompt]"`
+      5. Returns specialized result
+      
+      **No shell commands, no intermediate steps** - Pure CLI-to-prompt translation.
+
+    parameters:
+      task_type:
+        type: string
+        required: true
+        validation:
+          pattern: "^(completion-inspector|helper-friend|manual-tester)$"
+        description: |
+          **[REQUIRED] Task type enum - NO STRINGS, NO GUESSING**
+          
+          Must be EXACTLY one of:
+          - `completion-inspector` - Code review and verification
+          - `helper-friend` - Research and investigation
+          - `manual-tester` - QA testing with browser
+          
+          The system will load the appropriate MDX template and merge with your prompt.
+
+      prompt:
+        type: string
+        required: true
+        validation:
+          minLength: 20
+        description: |
+          **[REQUIRED] Your task-specific prompt**
+          
+          This will be merged with the task type's MDX template.
+          
+          **For completion-inspector, provide:**
+          - Original task requirements
+          - Acceptance criteria
+          - Implementation summary
+          - Files changed with descriptions
+          - START_COMMIT hash
+          - Why you think it's complete
+          
+          **For helper-friend, provide:**
+          - Ultimate goal and success criteria
+          - Current situation
+          - Files involved with descriptions
+          - What you've tried
+          - Current blocker/question
+          - Constraints
+          
+          **For manual-tester, provide:**
+          - Frontend URL (MANDATORY!)
+          - Backend URL (if applicable)
+          - Auth credentials
+          - Feature description
+          - Expected behaviors
+          - Test data
+          - Edge cases to test
+          
+          Minimum 20 characters required.
+
+      model:
+        type: string
+        required: false
+        description: |
+          **[OPTIONAL] Override model selection**
+          
+          Leave empty to use task type's default:
+          - completion-inspector: gemini-3-pro
+          - helper-friend: auto-select
+          - manual-tester: gemini-3-pro
+          
+          Available: `gemini-3-pro`, `gemini-3-flash`
+
+      sandbox:
+        type: boolean
+        required: false
+        default: false
+        description: |
+          **[OPTIONAL] Run in sandbox mode**
+          
+          Enables sandbox isolation for safer execution.
+          Flag: --sandbox / -s
+
+      approval_mode:
+        type: string
+        required: false
+        description: |
+          **[OPTIONAL] Override approval mode**
+          
+          Valid values:
+          - `default` - Prompt for approval
+          - `auto_edit` - Auto-approve edit tools
+          - `yolo` - Auto-approve all tools
+          
+          Leave empty to use --yolo (auto-approve all)
+
+      include_directories:
+        type: string
+        required: false
+        description: |
+          **[OPTIONAL] Include additional directories**
+          
+          Comma-separated list of directories to include.
+          Example: "src,docs,tests"
+
+      include_instructions:
+        type: boolean
+        required: false
+        default: true
+        description: |
+          Include task-specific instructions from MDX template.
+          Default: true (recommended)
+          Set false: For custom prompts that don't need template
+
+      async:
+        type: boolean
+        required: false
+        default: true
+        description: |
+          **[OPTIONAL] Async execution mode**
+          
+          **Default: true (async)**
+          - Returns immediately with a 5-digit task ID (e.g., 34567)
+          - Task runs in background
+          - Query status with `check_subagent_task` tool using the task ID
+          - Results stored in memory until retrieved
+          
+          **Set to false (sync/blocking):**
+          - Blocks until task completes
+          - Returns full result directly
+          - Use for quick tasks where you need immediate result
+          
+          **Example async flow:**
+          1. Call `gemini-subagent` with `async: true` (default)
+          2. Receive: `{"task_id": 34567, "status": "running"}`
+          3. Later: Call `check_subagent_task` with `task_id: 34567`
+          4. Receive: `{"status": "completed", "result": "..."}` or `{"status": "running"}`
+          
+          **⚠️ IMPORTANT:** When async=true, the response is NOT the result!
+          You MUST call `check_subagent_task` to get the actual result.

package/dist/constants.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=constants.d.ts.map

package/dist/constants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":""}

package/dist/constants.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=constants.js.map

package/dist/constants.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"constants.js","sourceRoot":"","sources":["../src/constants.ts"],"names":[],"mappings":""}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * Gemini Helper Friend MCP
+ * Your autonomous AI assistant that works on your codebase using Gemini CLI
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}