fix: implement actionable review feedback from pending PRs

Addresses unresolved review comments from PRs #6, #13, #25, #26:

- src/index.ts: Add console.log→stderr redirect with unknown[] type
- src/services/xapi.ts: Use URLSearchParams, add Array.isArray guard,
  add since_id pagination, use unknown type, avoid mutating sort
- src/services/agent.ts: Add bounded memory pruning with safe iterator,
  process mentions oldest-first for chronological ordering
- .github/workflows: Add permissions blocks, check labels exist before
  adding, use pull_request_target for fork PR support
- README.md: Add Contributing section with absolute paths
- Add CONTRIBUTING.md, PR_TITLE_GUIDE.md, pull_request_template.md

Co-authored-by: groupthinking <154503486+groupthinking@users.noreply.github.com>

Author: Copilot

.github/PR_TITLE_GUIDE.md

@@ -0,0 +1,54 @@
+# PR Title Quick Reference
+
+## Conventional Commits Format
+
+All PR titles should follow the [Conventional Commits](https://www.conventionalcommits.org/) format:
+
+**Format**: `<type>(<scope>): <description>`
+
+### Types and Examples
+
+| Type | When to Use | Example |
+|------|-------------|---------|
+| `feat` | New feature | `feat(agent): add autonomous reply functionality` |
+| `fix` | Bug fix | `fix(xapi): correct mention polling interval` |
+| `docs` | Documentation only | `docs: update README.md and simplify xAI instructions` |
+| `refactor` | Code restructuring | `refactor(grok): simplify AI decision logic` |
+| `chore` | Maintenance | `chore: update dependencies to latest versions` |
+| `ci` | CI/CD changes | `ci: add PR validation workflow` |
+| `style` | Formatting changes | `style: fix indentation in config files` |
+| `test` | Test updates | `test: add unit tests for agent service` |
+| `perf` | Performance improvements | `perf(xapi): optimize mention polling` |
+
+### How to Update PR Title
+
+1. Go to your PR page on GitHub
+2. Click the "Edit" button next to the PR title
+3. Update the title to follow the format above
+4. Save changes
+
+The PR validation workflow will then pass with no warnings.
+
+## Common Scenarios
+
+### Documentation Updates
+**Problem**: PR title like "updates to the `README.md`"  
+**Solution**: `docs: update README.md and simplify xAI instructions`
+
+### Multiple File Changes
+**Problem**: PR title like "various fixes"  
+**Solution**: Choose the primary change type:
+- `fix: resolve polling and authentication issues`
+- `refactor: restructure API client and services`
+
+### Feature Additions
+**Problem**: PR title like "new stuff"  
+**Solution**: `feat(agent): implement autonomous decision-making`
+
+## Full Guidelines
+
+For comprehensive contribution guidelines, see [CONTRIBUTING.md](/CONTRIBUTING.md).
+
+---
+
+**Note**: The PR validation workflow treats conventional commits format as a **warning** (not an error), so PRs will not be blocked. However, following this format improves project maintainability and changelog generation.

.github/pull_request_template.md

@@ -0,0 +1,39 @@
+## Description
+
+<!-- Provide a clear description of what this PR does -->
+
+## Motivation
+
+<!-- Explain why this change is needed -->
+
+## Changes
+
+<!-- List the main changes made in this PR -->
+- 
+- 
+- 
+
+## Related Issues
+
+<!-- Link related issues using #issue-number -->
+Closes #
+
+## Testing
+
+<!-- Describe how you tested these changes -->
+- [ ] Builds successfully (`npm run build`)
+- [ ] Tested in simulation mode
+- [ ] Tested with real API calls (if applicable)
+
+## Checklist
+
+- [ ] PR title follows [conventional commits format](/CONTRIBUTING.md#pr-title-format) (e.g., `feat:`, `fix:`, `docs:`)
+- [ ] PR description is clear and complete
+- [ ] Code follows project style guidelines
+- [ ] Changes are focused and reasonably sized
+- [ ] Documentation updated (if needed)
+- [ ] No sensitive information (API keys, tokens) committed
+
+## Screenshots / Logs (if applicable)
+
+<!-- Add screenshots or relevant log output -->

.github/workflows/auto-label.yml

@@ -1,7 +1,12 @@
 name: Auto Label
 on:
-  pull_request:
-    types: [opened, reopened, synchronized]
+  pull_request_target:
+    types: [opened, reopened, synchronize]
+
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
   label:
     runs-on: ubuntu-latest

.github/workflows/issue-triage.yml

@@ -2,6 +2,10 @@ name: Issue Triage
 on:
   issues:
     types: [opened]
+
+permissions:
+  issues: write
+
 jobs:
   triage:
     runs-on: ubuntu-latest
@@ -21,12 +25,21 @@ jobs:
 
             labels.push('needs-triage');
 
-            if (labels.length > 0) {
+            // Fetch existing labels to avoid "Label does not exist" errors
+            const { data: repoLabels } = await github.rest.issues.listLabelsForRepo({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              per_page: 100,
+            });
+            const existingLabelNames = new Set(repoLabels.map(label => label.name));
+            const labelsToAdd = labels.filter(label => existingLabelNames.has(label));
+
+            if (labelsToAdd.length > 0) {
               await github.rest.issues.addLabels({
                 owner: context.repo.owner,
                 repo: context.repo.repo,
                 issue_number: issue.number,
-                labels: labels
+                labels: labelsToAdd
               });
             }
 

.github/workflows/pr-checks.yml

@@ -2,6 +2,11 @@ name: PR Checks
 on:
   pull_request:
     types: [opened, reopened, synchronize, edited]
+
+permissions:
+  contents: read
+  pull-requests: write
+
 jobs:
   validate:
     runs-on: ubuntu-latest

CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing to MyXstack
+
+Thank you for contributing to MyXstack! This guide will help you understand our contribution process and conventions.
+
+## Pull Request Guidelines
+
+### PR Title Format
+
+We follow the [Conventional Commits](https://www.conventionalcommits.org/) format for PR titles. This helps us automatically generate changelogs and understand the nature of changes at a glance.
+
+**Format**: `<type>(<scope>): <description>`
+
+**Types**:
+- `feat`: A new feature
+- `fix`: A bug fix
+- `docs`: Documentation changes only
+- `style`: Code style changes (formatting, semicolons, etc.) that don't affect functionality
+- `refactor`: Code changes that neither fix bugs nor add features
+- `perf`: Performance improvements
+- `test`: Adding or updating tests
+- `chore`: Maintenance tasks, dependency updates
+- `ci`: Changes to CI/CD configuration
+- `build`: Changes to build system or dependencies
+- `revert`: Reverting a previous commit
+
+**Scope** (optional): The area of the codebase affected (e.g., `agent`, `xapi`, `grok`, `mcp`)
+
+**Examples**:
+- `docs: update README.md and simplify xAI instructions`
+- `feat(agent): add autonomous reply functionality`
+- `fix(xapi): correct mention polling interval`
+- `chore: update dependencies to latest versions`
+- `ci: add PR validation workflow`
+
+### PR Description
+
+- Provide a clear description of what the PR does (minimum 20 characters)
+- Reference related issues using `#issue-number`
+- Explain the motivation for the change
+- List any breaking changes
+- Include testing steps if applicable
+
+### PR Size
+
+- Try to keep PRs focused and under 500 lines of changes
+- Large PRs (>500 lines) will trigger a warning
+- Consider breaking large changes into smaller, reviewable chunks
+- If a large PR is unavoidable, provide extra context in the description
+
+## Code Style
+
+Follow the guidelines in `.github/copilot-instructions.md`:
+- Use TypeScript strict mode
+- Prefer async/await over raw promises
+- Always wrap API calls in try-catch blocks
+- Use explicit types; avoid `any`
+- Follow naming conventions:
+  - Classes: PascalCase (e.g., `XAPIClient`)
+  - Functions: camelCase (e.g., `fetchMentions`)
+  - Constants: UPPER_SNAKE_CASE (e.g., `DEFAULT_POLLING_INTERVAL`)
+
+## Testing
+
+- Run `npm run build` to verify TypeScript compilation
+- Test changes in simulation mode when possible
+- Ensure existing tests pass before submitting
+
+## Questions?
+
+If you have questions, feel free to:
+- Open an issue for discussion
+- Ask in your PR comments
+- Check the existing documentation in `ARCHITECTURE.md` or `USAGE.md`

README.md

@@ -47,3 +47,13 @@ A2A:
 - `POST /v1/a2a/agents`
 - `GET /v1/a2a/agents/{id}/messages`
 - `POST /v1/a2a/messages`
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](/CONTRIBUTING.md) for guidelines on:
+- PR title format (conventional commits)
+- Code style and conventions
+- Testing requirements
+- How to submit pull requests
+
+For quick reference on PR titles, see [.github/PR_TITLE_GUIDE.md](/.github/PR_TITLE_GUIDE.md).

src/index.ts

@@ -8,6 +8,10 @@ import { AutonomousAgent } from './services/agent.js';
 import { XMCPServer } from './mcp/server.js';
 
 async function main() {
+  // Redirect console.log to stderr so it doesn't conflict with
+  // MCP StdioServerTransport which uses stdout for protocol messages
+  console.log = (...args: unknown[]) => console.error(...args);
+
   console.log('═══════════════════════════════════════════════════');
   console.log('  MyXstack - Autonomous AI Agent on X (Twitter)');
   console.log('═══════════════════════════════════════════════════\n');

src/services/agent.ts

@@ -11,6 +11,7 @@ export class AutonomousAgent {
   private grokService: GrokService;
   private config: AgentConfig;
   private processedMentions: Set<string> = new Set();
+  private static readonly MAX_PROCESSED_MENTIONS = 10000;
   private isRunning: boolean = false;
   private pollingIntervalId: NodeJS.Timeout | null = null;
   private isProcessing: boolean = false;
@@ -90,11 +91,24 @@ export class AutonomousAgent {
 
       console.log(`\n📬 [${new Date().toLocaleTimeString()}] Found ${newMentions.length} new mention(s)!\n`);
 
-      // Process each mention
-      for (const mention of newMentions) {
+      // Process mentions oldest-first for chronological Set insertion order
+      for (const mention of [...newMentions].reverse()) {
         await this.processMention(mention);
         this.processedMentions.add(mention.post.id);
       }
+
+      // Prune oldest entries to prevent unbounded memory growth
+      if (this.processedMentions.size > AutonomousAgent.MAX_PROCESSED_MENTIONS) {
+        const excess = this.processedMentions.size - AutonomousAgent.MAX_PROCESSED_MENTIONS;
+        const iter = this.processedMentions.values();
+        for (let i = 0; i < excess; i++) {
+          const { value, done } = iter.next();
+          if (done) {
+            break;
+          }
+          this.processedMentions.delete(value);
+        }
+      }
     } catch (error) {
       console.error('❌ Error in processing loop:', error);
     } finally {

src/services/xapi.ts

@@ -44,17 +44,31 @@ export class XAPIClient {
         throw new Error('Failed to get user ID from response');
       }
 
-      const mentionsResponse = await this.makeXAPIRequest(
-        `https://api.twitter.com/2/users/${userId}/mentions?max_results=10&expansions=author_id&tweet.fields=created_at,conversation_id,in_reply_to_user_id,referenced_tweets`,
-        'GET'
-      );
+      const params = new URLSearchParams({
+        max_results: '10',
+        expansions: 'author_id',
+        'tweet.fields': 'created_at,conversation_id,in_reply_to_user_id,referenced_tweets',
+      });
+      if (this.lastMentionId) {
+        params.set('since_id', this.lastMentionId);
+      }
+      const mentionsUrl = `https://api.twitter.com/2/users/${userId}/mentions?${params.toString()}`;
+
+      const mentionsResponse = await this.makeXAPIRequest(mentionsUrl, 'GET');
 
       if (!mentionsResponse || !Array.isArray(mentionsResponse.data)) {
         console.warn('Invalid response from X API (mentions)');
         return [];
       }
 
-      return this.parseMentions(mentionsResponse.data);
+      const mentions = this.parseMentions(mentionsResponse.data);
+
+      // Track the newest mention ID for pagination on the next poll
+      if (mentionsResponse.data.length > 0) {
+        this.lastMentionId = mentionsResponse.data[0].id;
+      }
+
+      return mentions;
     } catch (error) {
       console.error('Error fetching mentions:', error);
       return [];
@@ -77,7 +91,17 @@ export class XAPIClient {
         'GET'
       );
 
-      return this.parseThread(response.data || []);
+      if (!response || !response.data) {
+        console.warn('Invalid response from X API (thread)');
+        return null;
+      }
+
+      if (!Array.isArray(response.data)) {
+        console.warn('Unexpected response shape from X API (thread): data is not an array');
+        return null;
+      }
+
+      return this.parseThread(response.data);
     } catch (error) {
       console.error('Error fetching thread:', error);
       return null;
@@ -181,10 +205,10 @@ export class XAPIClient {
     };
   }
 
-  private parseThread(tweets: { created_at: string; [key: string]: any }[]): XThread | null {
+  private parseThread(tweets: { created_at: string; [key: string]: unknown }[]): XThread | null {
     if (tweets.length === 0) return null;
 
-    const sorted = tweets.sort((a, b) => 
+    const sorted = [...tweets].sort((a, b) =>
       new Date(a.created_at).getTime() - new Date(b.created_at).getTime()
     );