meow-swarm 0.2.0 → 0.3.0

package/.context/ANTI_PATTERNS.md

@@ -0,0 +1,56 @@
+# MEOW Anti-Patterns & Lessons Learned
+
+This document tracks recurring mistakes or "hallucination triggers" to prevent them from happening again.
+
+## Current Hallucination Triggers
+- **Sync I/O**: Do not use `fs.readFileSync` in the kernel. It blocks the heartbeat. Use `fs/promises`.
+- **Placeholder Skills**: Some skills are just frontmatter without content. Always check the `body` before assuming a skill is functional.
+- **SQLite Wavefunction Collapse**: Avoid zero-length vectors in embeddings. They cause SQLite-vec to error out. Use the `0.0001` noise floor.
+
+## Git Mistakes
+- **Useless Commits**: Avoid committing after every tool call. Wait until the mission is verified.
+- **Refactor Bloat**: Do not "clean up" `node_modules` or unrelated config files during a feature task.
+
+## Meow Execution Failures (Dogfooding Findings)
+
+### 1. Tool Call Parsing Loops (CRITICAL)
+- **Symptom**: Meow outputs "Using tool: browse..." as TEXT but never actually calls the tool, causing infinite Grover search loops
+- **Root Cause**: LLM (Ollama) is verbose and describes tool usage rather than executing `TOOL:` commands
+- **Impact**: Meow hangs indefinitely when browse/search is attempted
+- **Workaround**: Exclude browse/search from commands, use only local file operations (read, write, ls, grep, run)
+- **Fix Needed**: Improve tool call regex parsing in `src/agent/agent.ts` to handle verbose LLM output
+
+### 2. Subprocess Shadow Audit Mismatch (CRITICAL)
+- **Symptom**: Meow delegates to Claude Code, Claude Code claims success, but Meow's shadow audit rejects the changes
+- **Root Cause**: Meow's subprocess runs a diff check on its own files (package.json, etc.) rather than the delegated task files
+- **Impact**: PDF generation and other delegated tasks fail silently despite Claude Code completing
+- **Workaround**: Verify subprocess outputs manually
+- **Fix Needed**: Meow's summoner should verify the actual task output, not its own repo state
+
+### 3. browse/search Timeout (HIGH)
+- **Symptom**: `browse` and `search` tools hang indefinitely because target sites are blocked/unreachable
+- **Root Cause**: No AbortController/timeout on fetch calls, and network restrictions in the environment
+- **Impact**: Meow freezes when attempting web access
+- **Workaround**: Add 10s timeout to fetch calls (done), avoid browse/search in commands
+- **Fix Needed**: Continue avoiding browse/search in agentic loops
+
+### 4. write Tool Path Corruption (HIGH)
+- **Symptom**: `write` tool receives corrupted paths like "150 scratch/Bifrost-task/answer.md" 
+- **Root Cause**: Tool arguments parsing splits on ` | ` but LLM output contains " | " as prose
+- **Impact**: File writes fail with ENOENT
+- **Workaround**: Ensure commands don't contain " | " except as tool argument delimiter
+- **Fix Needed**: More robust tool argument parsing
+
+### 5. Respawn Not Wired to Heartbeat (MEDIUM)
+- **Symptom**: Watchdog mechanism exists but agent never calls `kernel.pulse()`, so frozen agents aren't detected
+- **Root Cause**: Agent's chat loop doesn't include heartbeat calls to kernel
+- **Impact**: Frozen agents run forever without recovery
+- **Workaround**: None - requires code fix
+- **Fix Needed**: Add `kernel.pulse(process.pid)` periodically in agent chat loop
+
+## Future Prevention
+- [ ] Add a pre-commit hook that runs `bun run check`.
+- [ ] Implement a "Semantic Cross-Check" for mission fulfillment.
+- [ ] Fix tool call parsing to handle verbose LLM output
+- [ ] Wire heartbeat into agent chat loop
+- [ ] Fix shadow audit to check task output, not meow repo

package/.context/ARCHITECTURE.md

@@ -0,0 +1,29 @@
+# MEOW Architecture Map
+
+This document serves as the ground truth for the project's technical structure.
+
+## Directory Layout
+
+- `src/index.ts`: The entry point and main kernel loop.
+- `src/agent/`: Core orchestration logic.
+  - `skills.ts`: Discovers and manages `.md` based skill files.
+  - `kernel.ts`: The "brain" that manages task state and tool execution.
+- `src/extensions/`: Tool definitions and MCP integrations.
+- `skills/`: Markdown-based "Expert Knowledge" modules.
+  - `karpathy_guidelines/`: Core coding standards.
+- `memory/`: Persistent storage for agent findings and long-term context.
+- `REPORTS/`: Audits, reviews, and post-mortems.
+
+## Key Abstractions
+
+### 1. The Kernel
+The central loop that receives a user request, selects the appropriate skills/tools, and executes the "Quantum turn."
+
+### 2. Skills
+Static Markdown files with frontmatter. They provide **Passive Context**. The agent reads them to understand "how" to perform specific tasks (e.g., how to code like Karpathy).
+
+### 3. Extensions
+Code modules that provide **Active Capabilities**. They register tools (read, write, run) that the agent can use to interact with the system.
+
+## Data Flow
+User Input → Kernel → Skill Discovery → Tool Selection → Execution → Verification → Result.

package/.context/ECOSYSTEM.md

@@ -0,0 +1,12 @@
+# MEOW Ecosystem Research Log
+
+This document tracks mature agentic patterns, Claude skills, and MCP tools found during research.
+
+## 🏗️ Agentic Patterns
+- [Pattern Name] - [Description/Link]
+
+## 🛠️ Mature Tools & Skills
+- [Skill Name] - [Ecosystem Reference]
+
+## 📜 Research Notes
+- [Date] - [Topic] - [Findings]

package/.context/MISSION.md

@@ -0,0 +1,13 @@
+# MEOW Mission Statement
+
+## What is MEOW?
+MEOW is a **Sovereign AI Coding Agent** designed to run locally in your terminal. It acts as a meta-orchestrator, capable of managing multiple "skills" (expert knowledge) and "extensions" (tools) to solve complex software engineering tasks autonomously.
+
+## Core Values
+1. **Surgical Precision**: We touch only what is necessary. We do not "cleanup" adjacent code unless explicitly asked.
+2. **Ground Truth Verification**: We do not "guess" if code works. we verify via `typecheck`, `lint`, and (where available) `tests`.
+3. **Quantum-Inspired Orchestration**: We use advanced logic (like amplitude amplification) to prioritize the best reasoning paths, but we ground this in classical software engineering rigor.
+4. **Local-First & Sovereign**: MEOW is designed to empower the user's local environment without excessive reliance on opaque cloud abstractions.
+
+## The Goal
+To provide a friction-less, non-hallucinating coding partner that produces high-quality, production-ready commits.

package/.context/QA_REVIEW.md

@@ -0,0 +1,200 @@
+# MEOW QA Review & Process Guidelines
+
+## Section 1: QA Review of MEOW Outputs
+
+### ✅ PASSED Reviews
+
+#### Task-1: Project Setup
+| File | Lines | Status | Notes |
+|------|-------|--------|-------|
+| `PLAN.md` | 37 | ✅ PASS | Covers architecture, tech stack, priority actions |
+| `RESEARCH.md` | 48 | ✅ PASS | Comprehensive API research for 5 services |
+
+#### Task-2: Patent Analysis
+| File | Lines | Status | Notes |
+|------|-------|--------|-------|
+| `TOP_PATENTS.md` | 119 | ✅ PASS | 10 patents identified with entry points |
+| `ANALYSIS.md` | 100 | ✅ PASS | Methodology and strategic recommendations |
+| `PATENTS_REPORT.md` | 374 | ✅ PASS | Full combined report, well-structured |
+
+### ❌ FAILED Reviews
+
+#### PATENTS_REPORT.pdf
+- **File**: `scratch/task-2/PATENTS_REPORT.pdf`
+- **Size**: 47KB (actual content: placeholder page from converter)
+- **Status**: ❌ **FAIL - INVALID OUTPUT**
+- **Problem**: Tool ran but captured converter's placeholder page, NOT the actual report content
+- **Visual Proof**: PDF shows markdowntopdf.com welcome page, no patent data
+
+---
+
+## Section 2: Root Cause Analysis - Why MEOW Failed
+
+### Failure Chain
+
+1. **Task Assigned**: "Create PDF for task-2"
+2. **MEOW Called Tool**: PDF generation tool
+3. **Tool Returned**: Success signal
+4. **MEOW Verified**: File exists (47KB)
+5. **MEOW Reported**: "PDF created successfully"
+6. **Reality**: File contains wrong content (placeholder page)
+
+### Why MEOW Didn't Catch This
+
+1. **No Visual Verification**: MEOW checked file existence, not content validity
+2. **Trust Without Verification**: Tool reported success → assumed success
+3. **No Screenshot Requirement**: Didn't capture visual proof of output
+4. **Output Quality Not Part of Tool Contract**: Tool said "done" but didn't validate content
+
+### Systemic Issue
+
+MEOW's verification is **binary** (exists vs not exists), not **qualitative** (correct vs incorrect content).
+
+---
+
+## Section 3: Process Guidelines - Visual Verification Required
+
+### New Rule for All Output Generation Tasks
+
+**ANY task that produces a visual output (PDF, HTML, image, etc.) MUST include:**
+
+```
+1. Generate the output file
+2. Capture screenshot of the output
+3. Describe what screenshot shows
+4. If screenshot shows placeholder/error/wrong content → REJECT and retry
+```
+
+### Visual Verification Checklist
+
+For PDF outputs:
+- [ ] Screenshot shows first page of actual document content
+- [ ] Screenshot shows correct title/heading
+- [ ] Screenshot shows actual data (not placeholder text)
+- [ ] File size is reasonable (>1KB for text content)
+
+For file outputs:
+- [ ] First 5 lines match expected content
+- [ ] Last 5 lines match expected content
+- [ ] No truncation or corruption markers
+
+For browser-based outputs:
+- [ ] Screenshot captures actual rendered content
+- [ ] No "loading" or "placeholder" states
+- [ ] Correct data visible in screenshot
+
+---
+
+## Section 4: MEOW QA Protocol (New SOP)
+
+### Before Marking Task Complete
+
+For any output generation:
+
+```
+1. GENERATE output (file/pdf/etc)
+2. VERIFY using method below based on output type:
+
+   PDF/Image → Take screenshot, describe visual content
+   File → Read first/last 10 lines, compare to expected
+   Browser → Take snapshot/screenshot
+   API Response → Log status code and first 200 chars
+```
+
+### Verification by Output Type
+
+| Output Type | Verification Method | Acceptance Criteria |
+|-------------|---------------------|---------------------|
+| PDF | Screenshot of page 1 | Shows actual title, not placeholder |
+| Markdown | Read lines 1-10, -10 to end | Matches expected content |
+| Image | Screenshot | Shows rendered content, not blank |
+| Webpage | Snapshot | Contains expected elements |
+| API Call | Log response | 2xx status, valid JSON |
+
+### MEOW Must Report
+
+For each output generation, MEOW must say:
+```
+VERIFIED: [output type] - [visual confirmation description]
+Example: VERIFIED: PDF - "Shows 'Top 10 Drug Patents' title and table with patent data"
+```
+
+### If Verification Fails
+
+MEOW must:
+1. Log what was expected vs what was found
+2. Attempt re-generation
+3. Report failure if 2 attempts fail
+
+---
+
+## Section 5: Updated SOP for Mission Tasks
+
+### Modified Mission Flow
+
+```
+1. LOAD .context files (SOP, MISSION, ARCHITECTURE, HONESTY)
+2. READ mission file
+3. EXECUTE research/actions
+4. GENERATE outputs
+5. VERIFY outputs with VISUAL CHECK (screenshot required)
+6. If FAIL → retry with corrected approach
+7. If PASS → report with verification evidence
+```
+
+### No Trust Policy
+
+- **NEVER** assume tool succeeded because it returned
+- **ALWAYS** verify output matches expectation
+- **REQUIRE** visual evidence (screenshot) for visual outputs
+- **DOCUMENT** what was verified in completion report
+
+---
+
+## Section 6: Summary of Issues Found
+
+### Code Quality Issues (Fixed)
+
+1. `database.ts`: Removed unused `platform` import
+2. `quantum_memory.ts`: Early return for single candidate bypasses quantum search
+3. `index.ts`: No null check on response (potential "null" string output)
+
+### Output Quality Issues
+
+1. **PATENTS_REPORT.pdf**: Invalid content (placeholder page)
+   - Root cause: Tool used but content not verified
+   - Fix needed: Add screenshot verification step
+
+### Process Gaps
+
+1. No visual verification requirement in output generation
+2. MEOW reports "success" based on tool return, not content check
+3. No explicit QA step before declaring mission complete
+
+---
+
+## Section 7: Recommendations
+
+### Immediate (Applied Now)
+
+1. **Visual Verification Required**: Add to SOP - screenshot required for PDF/image outputs
+2. **Output Type Check**: Different verification methods for different output types
+3. **Fail Reporting**: When output doesn't match expectation, report what was wrong
+
+### Short Term (MEOW Updates)
+
+1. Add verification method to each tool description
+2. Require screenshot/snapshot before marking output generation complete
+3. Implement output quality scoring (0-10) based on content match
+
+### Long Term (System Design)
+
+1. Build "Output Validator" as part of MEOW kernel
+2. Schema-based output verification (e.g., PDF must contain title, table with X rows)
+3. Visual diff capability for comparing expected vs actual output
+
+---
+
+*QA Review completed: 2026-04-30*
+*Issues Found: 3 (1 critical output failure, 2 code quality, 1 process gap)*
+*Fixes Applied: 2 (code fixes)*

package/.husky/pre-commit

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+bun run check

package/.husky/pre-push

@@ -0,0 +1,2 @@
+#!/usr/bin/env bash
+bun run check

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to MEOW will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
+
+## [0.1.0] — 2024-05-16
+
+### Added
+- Initial release
+- `meow -p` headless mode for background task execution
+- MEOW-3-RULE: meow -p (3 retries) → claude -p fixes MEOW (never the task)
+- 4-panel blessed TUI (`meow --tui`)
+- Interactive REPL mode
+- Multi-tier quality gates (NO_MOCKS, TYPE_CHECK, LINT_CLEAN, etc.)
+- MissionReviewer: 7-criterion scoring
+- Convergence logic (stagnation, token budget, diminishing returns)
+- MeowKernel: heartbeat watchdog and respawn
+- SQLite + sqlite-vec for persistent task memory
+- Quantum memory for semantic recall (Grover-based)
+- MCP client integration (40+ external services)
+- L1-L4 orchestration architecture
+- SWARM, SEQUENTIAL, PARALLEL, AUDIT_ONLY execution modes
+- HumanSignoffManager for low-confidence decision escalation
+- CLAUDE.md and .meow/skills/meow-setup/SKILL.md for Claude Code integration

package/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing to MEOW
+
+Welcome! MEOW is an open-source autonomous coding harness and contributions are welcome.
+
+## Getting Started
+
+```bash
+git clone https://github.com/stancsz/meow.git
+cd meow
+npm install
+npx tsx src/index.ts "your task here"
+```
+
+## Dev Workflow
+
+```bash
+npm run dev        # REPL mode
+npm run tui        # TUI mode
+npm run typecheck  # tsc --noEmit
+npm run lint       # ESLint
+npm run test       # Vitest
+```
+
+## Submitting Changes
+
+1. Fork the repo
+2. Create a branch: `git checkout -b fix/my-fix`
+3. Make your changes + add tests
+4. Run `npm run check` to verify typecheck + lint pass
+5. Open a PR
+
+## MEOW-3-RULE for contributors
+
+If you fix MEOW (not a task), after your fix:
+1. Re-run the original task with `meow -p`
+2. If it succeeds → open a PR to stancsz/meow
+
+## Code Structure
+
+```
+src/
+  agent/           # LLM chat, summoner, mission_reviewer, quantum_memory
+  orchestrator/    # Orchestrator, TaskQueue, convergence checks
+  kernel/          # MeowKernel, database
+  cli/             # REPL, TUI
+  extensions/      # Tool definitions
+  types/           # Tool schema
+```
+
+## Style
+
+- TypeScript strict mode
+- ESM modules
+- No `TODO`/`FIXME` in committed code (quality gate: NO_MOCKS)
+- Think-Plan-Verify in commit messages

package/PUBLISH.md

@@ -0,0 +1,268 @@
+# Publishing MEOW to npm
+
+This guide covers everything needed to publish MEOW as a public npm package.
+
+---
+
+## Prerequisite: npm Account
+
+1. Create an account at [npmjs.com](https://www.npmjs.com)
+2. Enable 2FA (required for publishing)
+3. Claim the `meow` or `meow-agent` package name
+
+> ⚠️ The name `meow` is already taken on npm. Options:
+> - `meow-agent` (used in README install instructions)
+> - `@meow/core` (scoped package)
+> - `@stancsz/meow` (scoped with your GitHub username)
+>
+> Check availability: `npm view meow-agent` vs `npm view meow`
+
+---
+
+## Step 1: Prepare the Package
+
+### 1a. Install dependencies
+
+```bash
+cd meow
+npm install
+```
+
+### 1b. Run all checks
+
+```bash
+npm run check   # tsc --noEmit + ESLint
+npm run test    # vitest run
+```
+
+### 1c. Verify the bin works
+
+```bash
+npx tsx src/index.ts --version
+# or
+node src/index.js --version
+```
+
+### 1d. Build a compiled JavaScript version (optional but recommended)
+
+```bash
+# Install tsup for fast compilation
+npm install --save-dev tsup
+
+# Add to package.json scripts:
+# "build": "tsup src/index.ts --out-dir dist"
+
+npx tsup src/index.ts --out-dir dist --format esm --no-external-local
+```
+
+This produces `dist/index.js` which is faster to load than `tsx`.
+
+Update `bin` in `package.json`:
+```json
+{
+  "bin": {
+    "meow": "./dist/index.js"
+  },
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./src/index.ts"
+    }
+  }
+}
+```
+
+---
+
+## Step 2: Version Management
+
+MEOW uses **semantic versioning** (semver):
+
+| Increment | When to use | Example |
+|-----------|-------------|---------|
+| `PATCH` | Bug fixes, no breaking changes | 0.1.0 → 0.1.1 |
+| `MINOR` | New features, backward compatible | 0.1.0 → 0.2.0 |
+| `MAJOR` | Breaking changes | 0.1.0 → 1.0.0 |
+
+```bash
+# Bump version
+npm version patch   # 0.1.0 → 0.1.1
+npm version minor   # 0.1.0 → 0.2.0
+npm version major   # 0.1.0 → 1.0.0
+
+# This creates a git commit + tag automatically
+```
+
+Also update `CHANGELOG.md` before publishing with the new version.
+
+---
+
+## Step 3: Add .npmignore
+
+Create `.npmignore` to exclude files from the package:
+
+```
+node_modules/
+src/
+*.ts
+*.map
+.tsup.config.ts
+vitest.config.ts
+.git/
+.github/
+.context/
+memory/
+scratch/
+*.bak
+*.ts.bak
+*.ts.v2
+```
+
+This ensures only compiled JS + necessary files land in the npm package.
+
+---
+
+## Step 4: Login to npm
+
+```bash
+npm login
+# Enter username, password, and 2FA code
+```
+
+Verify you're logged in:
+```bash
+npm whoami
+```
+
+---
+
+## Step 5: Publish
+
+### For a scoped package (`@stancsz/meow`)
+
+```bash
+# Requires `access: public` for scoped packages
+npm publish --access public
+```
+
+### For an unscoped package (`meow-agent`)
+
+```bash
+npm publish
+```
+
+### Dry run (test without actually publishing)
+
+```bash
+npm publish --dry-run
+```
+
+### Verify what will be published
+
+```bash
+npm pack --dry-run
+```
+
+This shows the exact `.tgz` that will be uploaded.
+
+---
+
+## Step 6: After Publishing
+
+### Verify the package is live
+
+```bash
+npm view meow-agent
+# or
+npm view @stancsz/meow
+```
+
+### Tag the commit
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+### Update GitHub release
+
+Create a GitHub release at:
+https://github.com/stancsz/meow/releases/new
+
+Copy the changelog entry for this version.
+
+---
+
+## CI/CD: Automated Publishing via GitHub Actions
+
+Add `.github/workflows/publish.yml`:
+
+```yaml
+name: Publish to npm
+
+on:
+  push:
+    tags:
+      - 'v*.*.*'
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          registry-url: 'https://registry.npmjs.org'
+
+      - run: npm install
+
+      - run: npm test
+
+      - run: npm run build
+
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+### Get NPM_TOKEN
+
+1. Go to [npmjs.com](https://www.npmjs.com) → Account → Access Tokens
+2. Create an **Automation** token (can publish any package without 2FA)
+3. Add to GitHub repo: Settings → Secrets → `NPM_TOKEN`
+
+Now every `git tag v*.*.*` pushed to GitHub will:
+1. Run tests
+2. Build the package
+3. Publish to npm automatically
+
+---
+
+## Package Name Options (Decision)
+
+| Name | Status | Recommended? |
+|------|--------|-------------|
+| `meow` | ❌ Taken | No |
+| `meow-agent` | ✅ Available | **Yes** — clear, matches README install command |
+| `@stancsz/meow` | ✅ Available | Good if you want scoped + personal brand |
+| `@meow/core` | ✅ Available | Good for ecosystem (`@meow/cli`, `@meow/sdk`) |
+
+Recommend: **`meow-agent`** — available, clear, works with `npm install -g meow-agent`.
+
+---
+
+## npm Organization (optional)
+
+If you want an organization (e.g., `@meow-ai`):
+- Free at npmjs.com
+- Allows multiple packages: `@meow-ai/cli`, `@meow-ai/core`, `@meow-ai/sdk`
+
+Set package name in `package.json` accordingly:
+```json
+{
+  "name": "@meow-ai/cli",
+  "version": "0.1.0"
+}
+```