mercury-agent 0.4.22 → 0.4.24

package/docs/ARCHITECTURE.md

@@ -0,0 +1,30 @@
+# {Project Name} — Architecture Reference
+
+> On-demand reference. Do not auto-load. Read when a task is cross-cutting or you need to understand inter-package data flow.
+
+## Packages
+
+| Package | Purpose | Stack | Runs On |
+|---------|---------|-------|---------|
+| `{package}/` | {purpose} | {stack} | {where it runs} |
+
+## Deployment Topology
+
+```
+{ASCII diagram of your deployment — servers, services, databases, CDNs, etc.}
+```
+
+## Data Flow
+
+> How data moves between packages, services, and external systems. Include request paths, event flows, and storage interactions.
+
+## Key Invariants
+
+> Rules that must always hold true across the system. Breaking these causes cascading failures.
+
+- {Invariant 1}
+- {Invariant 2}
+
+## Extension Points
+
+> Where the system is designed to be extended — plugin interfaces, hook points, configuration surfaces.

package/docs/DESIGN.md

@@ -0,0 +1,42 @@
+# {Project Name} — Design System
+
+> Fill this in if your project has a UI. Skip if it's a backend-only project.
+
+## 1. Visual Theme
+
+> Design principles — what the UI should feel like.
+
+## 2. Color Roles
+
+> CSS variable inventory. All colors must be defined as variables — never hardcode hex in component files.
+
+| Token | Dark Value | Light Value | Role |
+|-------|-----------|-------------|------|
+| `--bg` | {hex} | {hex} | Page background |
+| `--surface` | {hex} | {hex} | Card/panel background |
+| `--text` | {hex} | {hex} | Primary text |
+| `--muted` | {hex} | {hex} | Secondary text |
+| `--accent` | {hex} | {hex} | Interactive elements |
+| `--border` | {hex} | {hex} | Borders and dividers |
+| `--color-success` | {hex} | {hex} | Success states |
+| `--color-error` | {hex} | {hex} | Error states |
+| `--color-warning` | {hex} | {hex} | Warning states |
+
+## 3. Typography
+
+> Font families, sizes, weights. Which fonts for which contexts.
+
+## 4. Layout & Spacing
+
+> Grid system, breakpoints, spacing scale. Include RTL/logical property conventions if applicable.
+
+## 5. Components
+
+> Component conventions — buttons, inputs, cards, modals, status indicators, etc.
+
+## 6. Hard Rules
+
+> Violations block merge. Examples:
+> - No hardcoded hex colors in component files — use CSS variables
+> - No physical CSS properties (`left`/`right`) — use logical properties
+> - All interactive elements must have visible focus rings

package/docs/ROADMAP.md

@@ -0,0 +1,41 @@
+# {Project Name} — Roadmap
+
+Single source of truth for priority. Rule: ≤15 min/week to maintain.
+
+---
+
+## Inbox
+
+> Uncategorized ideas. Triage into Now / Next / Later or drop.
+
+| Item | Doc | Notes |
+|------|-----|-------|
+| — | — | — |
+
+## Now
+
+> Max 2 items. What you're actively working on.
+
+| Item | Doc | Started | Notes |
+|------|-----|---------|-------|
+| — | — | — | — |
+
+## Next
+
+| # | Item | Doc | Depends on | Why now |
+|---|------|-----|-----------|---------|
+| 1 | **autonomous-planning-tier** | [doc](backlog/autonomous-planning-tier.md) | — | Let agents decompose ideas, keep human gate |
+
+## Later
+
+| Item | Doc | Notes |
+|------|-----|-------|
+| — | — | — |
+
+---
+
+## Shipped
+
+| Item | Shipped | What |
+|------|---------|------|
+| — | — | — |

package/docs/VISION.md

@@ -0,0 +1,32 @@
+# {Project Name} — Product Vision
+
+## What {Project Name} Is
+
+> One-sentence pitch.
+
+## Target User
+
+> Who is this for? Be specific — role, context, what they're trying to accomplish.
+
+## What Makes {Project Name} Different
+
+| Differentiator | Why it matters |
+|---------------|----------------|
+| {differentiator} | {why} |
+
+## Non-Goals
+
+> Explicit list of what this project does NOT try to be. Helps filter feature requests.
+
+- {Non-goal 1}
+- {Non-goal 2}
+
+## Guiding Questions for New Ideas
+
+> Use these to evaluate whether a feature idea fits the product:
+
+1. Does this serve the target user directly?
+2. Does this align with the differentiators above?
+3. Does this conflict with any non-goal?
+4. Can the user benefit from this without configuration or documentation?
+5. Would removing this make the product worse for the target user?

package/docs/bugs/bwrap-privileged-linux-docker.md

@@ -0,0 +1,140 @@
+# Bug: bwrap fails to mount /proc on Linux Docker Engine (non-Desktop)
+
+**Severity:** P1 — blocks all agent responses on standard Linux Docker hosts  
+**Affected:** Linux servers running Docker Engine (not Docker Desktop, not gVisor)  
+**File:** `src/agent/container-runner.ts`, bwrap compat branch (~line 980)
+
+## Symptom
+
+```
+Container error: Container failed (exit code 1): Error: pi CLI failed (1):
+bwrap: Can't mount proc on /newroot/proc: Operation not permitted
+```
+
+Happens on Linux servers (e.g. Hetzner, AWS EC2, DigitalOcean) running
+Docker Engine with the default kernel config. The existing bwrap Docker compat
+flags (`seccomp=unconfined`, `apparmor=unconfined`, `CAP_SYS_ADMIN`) are not
+sufficient for bwrap to mount `/proc` inside the container.
+
+## Root cause
+
+On Linux Docker Engine, the default seccomp + AppArmor + capability set does
+not allow `mount(2)` inside a user namespace, even with:
+- `--security-opt seccomp=unconfined`
+- `--security-opt apparmor=unconfined`
+- `--cap-add SYS_ADMIN`
+
+This is a known limitation: Docker's default behavior strips many mount-related
+permissions that `--privileged` restores (device cgroup rules, all capabilities,
+full /sys and /proc access).
+
+**Verified:** `--privileged` makes bwrap work:
+```bash
+# Fails:
+docker run --rm --entrypoint bwrap \
+  --security-opt seccomp=unconfined --security-opt apparmor=unconfined \
+  --cap-add SYS_ADMIN mercury-agent:latest \
+  --ro-bind /usr /usr --proc /proc --dev /dev --unshare-pid echo hello
+# → bwrap: Can't mount proc on /newroot/proc: Operation not permitted
+
+# Works:
+docker run --rm --entrypoint bwrap --privileged mercury-agent:latest \
+  --ro-bind /usr /usr --proc /proc --dev /dev --unshare-pid echo hello
+# → execvp echo: No such file or directory  (bwrap ran fine, echo just not in /usr)
+```
+
+## Fix
+
+### Option A: Add `--privileged` flag to bwrap compat (recommended short-term)
+
+In `container-runner.ts` (~line 985), replace the current compat flags with
+`--privileged` when `containerBwrapDockerCompat` is explicitly set to `true`:
+
+```typescript
+    } else if (this.config.containerBwrapDockerCompat || isDockerDesktop()) {
+      logger.info("Enabling bwrap Docker compat (seccomp/apparmor/SYS_ADMIN)", {
+        configFlag: this.config.containerBwrapDockerCompat,
+        dockerDesktop: isDockerDesktop(),
+      });
+      if (this.config.containerBwrapDockerCompat) {
+        // Explicit opt-in: Linux Docker Engine needs --privileged for bwrap
+        // to mount /proc inside a user namespace. The finer-grained flags
+        // (seccomp=unconfined + apparmor=unconfined + SYS_ADMIN) are not
+        // sufficient on standard Linux kernels.
+        args.push("--privileged");
+      } else {
+        // Docker Desktop auto-detection: use the lighter-weight flags
+        // (Docker Desktop's VM has a more permissive kernel config)
+        args.push(
+          "--security-opt",
+          "seccomp=unconfined",
+          "--security-opt",
+          "apparmor=unconfined",
+          "--cap-add",
+          "SYS_ADMIN",
+        );
+      }
+    }
+```
+
+This keeps the lighter flags for Docker Desktop (where they work) and uses
+`--privileged` only when the user explicitly opted in via
+`MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT=true`.
+
+### Option B: Add a separate `MERCURY_CONTAINER_PRIVILEGED` config flag
+
+If you prefer to keep the compat flag behavior unchanged, add a new flag:
+
+In `config.ts`, add:
+```typescript
+containerPrivileged: boolean; // default: false
+```
+
+In `config-file.ts`, add the env mapping:
+```typescript
+containerPrivileged: "MERCURY_CONTAINER_PRIVILEGED",
+```
+
+In `container-runner.ts`, after the existing compat block:
+```typescript
+    if (this.config.containerPrivileged) {
+      args.push("--privileged");
+    }
+```
+
+User sets `MERCURY_CONTAINER_PRIVILEGED=true` in `.env`.
+
+### Option C: Auto-detect and use --privileged as fallback
+
+Run a probe container on startup to test if bwrap works with the lighter
+flags. If it fails, automatically escalate to `--privileged` and log a
+warning. This is the most user-friendly but adds startup latency.
+
+## Workaround (immediate)
+
+Until the fix is in place, users can work around this by manually running
+mercury with Docker's `--privileged` flag. However, since `mercury run`
+doesn't expose extra Docker args, the only current workaround is to
+modify `MERCURY_AGENT_IMAGE` to point to a locally-built image and skip
+bwrap entirely by setting `MERCURY_CONTAINER_RUNTIME=runsc` (requires
+gVisor installed), or to apply the code change.
+
+## Linux server setup checklist
+
+These sysctl settings are needed regardless of the fix above:
+
+```bash
+sysctl -w kernel.unprivileged_userns_clone=1
+sysctl -w kernel.apparmor_restrict_unprivileged_userns=0
+cat > /etc/sysctl.d/99-bubblewrap.conf << 'EOF'
+kernel.unprivileged_userns_clone=1
+kernel.apparmor_restrict_unprivileged_userns=0
+EOF
+```
+
+## How to verify
+
+1. Set `MERCURY_CONTAINER_BWRAP_DOCKER_COMPAT=true` in `.env`
+2. Start mercury: `pm2 restart all` or `mercury service install`
+3. Run: `mercury chat 'hello'`
+4. Check logs — should see successful container run, no bwrap errors

package/docs/bugs/registry-pull-no-local-fallback.md

@@ -0,0 +1,168 @@
+# Bug: mercury run fails when registry pull fails but local build exists
+
+**Severity:** P1 — blocks users who build locally but have a registry image configured  
+**Introduced in:** 0.4.22 (commit 75e8e71)  
+**File:** `src/cli/mercury.ts`, `runAction()` (~line 187)
+
+## Symptom
+
+```
+$ mercury build          # succeeds → mercury-agent:latest exists locally
+$ mercury run
+Image 'ghcr.io/avishai-tsabari/mercury-agent:latest' not found locally, pulling...
+Error response from daemon: unauthorized
+
+Error: Failed to pull 'ghcr.io/avishai-tsabari/mercury-agent:latest'.
+If this is a private registry, authenticate first:
+  docker login ghcr.io
+```
+
+The user has a working local image (`mercury-agent:latest`) from `mercury build`,
+but `mercury run` exits with an error because the configured registry image
+can't be pulled (private registry, no auth, offline, etc.).
+
+## Root cause
+
+The 0.4.22 change replaced the local-fallback logic with auto-pull. The old
+code tried `mercury-agent:latest` as a fallback when the configured image
+wasn't found. The new code attempts `docker pull` and hard-exits on failure —
+it never checks whether a locally built image exists.
+
+### Before (0.4.21)
+
+```
+configured image not found?
+  → try mercury-agent:latest locally
+    → found? use it (with warning)
+    → not found? error: pull or build
+```
+
+### After (0.4.22)
+
+```
+configured image not found?
+  → is registry image? attempt pull
+    → pull fails? hard exit  ← BUG: should fall back to local
+  → not registry? error: run mercury build
+```
+
+## Fix
+
+After a failed pull of a registry image, check if `mercury-agent:latest`
+exists locally before giving up. If it does, use it with a warning.
+
+### Implementation (lines ~187–213 of `src/cli/mercury.ts`)
+
+Replace the current block:
+
+```typescript
+if (imageCheck.status !== 0) {
+    const isRegistryImage = imageName.includes("/");
+    if (isRegistryImage) {
+      console.log(`Image '${imageName}' not found locally, pulling...`);
+      const pull = spawnSync("docker", ["pull", imageName], {
+        stdio: "inherit",
+      });
+      if (pull.signal) {
+        process.exit(1);
+      }
+      if (pull.status !== 0) {
+        const firstSegment = imageName.split("/")[0];
+        const registry = firstSegment.includes(".")
+          ? firstSegment
+          : "docker.io";
+        console.error(`\nError: Failed to pull '${imageName}'.`);
+        console.error(
+          "If this is a private registry, authenticate first:\n" +
+            `  docker login ${registry}`,
+        );
+        process.exit(1);
+      }
+    } else {
+      console.error(`Error: Container image '${imageName}' not found.`);
+      console.error("Run 'mercury build' to build it.");
+      process.exit(1);
+    }
+  }
+```
+
+With:
+
+```typescript
+if (imageCheck.status !== 0) {
+    const isRegistryImage = imageName.includes("/");
+    let resolved = false;
+
+    if (isRegistryImage) {
+      console.log(`Image '${imageName}' not found locally, pulling...`);
+      const pull = spawnSync("docker", ["pull", imageName], {
+        stdio: "inherit",
+      });
+      if (pull.signal) {
+        process.exit(1);
+      }
+      if (pull.status === 0) {
+        resolved = true;
+      }
+    }
+
+    // Fallback: if the configured image isn't available (pull failed, not a
+    // registry image, or never pulled), try the local build tag.
+    if (!resolved) {
+      const localTag = "mercury-agent:latest";
+      if (imageName !== localTag) {
+        const localCheck = spawnSync("docker", ["image", "inspect", localTag], {
+          stdio: "pipe",
+        });
+        if (localCheck.status === 0) {
+          console.log(
+            `\nℹ️  Using locally built ${localTag} (configured image unavailable)\n`,
+          );
+          process.env.MERCURY_AGENT_IMAGE = localTag;
+          resolved = true;
+        }
+      }
+    }
+
+    if (!resolved) {
+      if (isRegistryImage) {
+        const firstSegment = imageName.split("/")[0];
+        const registry = firstSegment.includes(".")
+          ? firstSegment
+          : "docker.io";
+        console.error(`\nError: Failed to pull '${imageName}'.`);
+        console.error(
+          "If this is a private registry, authenticate first:\n" +
+            `  docker login ${registry}\n` +
+            "Or build locally:\n" +
+            "  mercury build",
+        );
+      } else {
+        console.error(`Error: Container image '${imageName}' not found.`);
+        console.error("Run 'mercury build' to build it.");
+      }
+      process.exit(1);
+    }
+  }
+```
+
+### Behavior after fix
+
+```
+configured image not found?
+  → is registry image? attempt pull
+    → pull succeeds? use it ✓
+    → pull fails? continue to fallback
+  → try mercury-agent:latest locally
+    → found? use it (with info message) ✓
+    → not found? error with both suggestions (login + build) ✓
+```
+
+## How to verify
+
+1. Build locally: `mercury build`
+2. Ensure no GHCR auth: `docker logout ghcr.io`
+3. Set `.env` to `MERCURY_AGENT_IMAGE=ghcr.io/avishai-tsabari/mercury-agent:latest`
+4. Run `mercury run` — should fall back to local image with info message
+5. Remove local image: `docker rmi mercury-agent:latest`
+6. Run `mercury run` — should error with both `docker login` and `mercury build` suggestions

package/docs/runbooks/publish-checklist.md

@@ -0,0 +1,8 @@
+# Publish Checklist
+
+Before publishing a new version to npm:
+
+1. **`bun run check`** — typecheck + lint + tests
+2. **`mercury build`** — if you touched build path, Dockerfiles, or file-copy logic
+3. **`mercury init` + `mercury service install`** in a test project — if you touched CLI flow, config loading, or service management
+4. **Smoke test assistants** — send a message, verify they respond

package/docs/templates/TEMPLATE-AUTOPILOT-CONFIG.yaml

@@ -0,0 +1,35 @@
+# Autopilot Configuration
+# Copy this file to docs/autopilot/config.yaml and customize.
+# The orchestrator script reads this file each iteration.
+
+gates:
+  max_iterations: 10                   # stop after N iterations per session
+  max_features_without_review: 3       # stop after completing N features/bugs without human review
+  max_retries_same_task: 3             # skip a task after N failed attempts
+  iteration_timeout_minutes: 30        # kill a single execute phase after this long
+
+risk:
+  sensitive_paths:                     # changes to these = immediate stop for review
+    - "**/auth/**"
+    - "**/migration*"
+    - "**/.env*"
+    - "**/schema*"
+  auto_stop_risk_threshold: 8          # risk_score >= this from assess = stop
+
+scope:
+  allowed_actions:                     # which actions the autopilot may take
+    - implement_feature
+    - continue_feature
+    - fix_bug
+    - sync_docs
+    # - propose_decomposition          # uncomment to enable autonomous planning (requires allow_autonomous_planning: true)
+  skip_slugs:                           # slugs to never touch autonomously
+    # - my-feature-slug
+
+planning:
+  allow_autonomous_planning: false     # when true, autopilot can decompose ideas into draft plans (requires propose_decomposition in allowed_actions)
+                                       # plans land as Status: Proposed and always stop for human review
+
+notifications:
+  on_stop: console                     # "console" | "file" (future: "slack", "email")
+  decision_log: docs/autopilot/decision-log.md

package/docs/templates/TEMPLATE-BUG.md

@@ -0,0 +1,71 @@
+# Bug: {Title}
+
+**Status**: Open | In-Progress | Fixed
+**Severity**: minor | moderate | major
+**Slug**: {slug}
+**Reported**: {YYYY-MM-DD}
+**Last updated**: {YYYY-MM-DD}
+
+---
+
+## Summary
+
+{One-sentence description of what's broken and where.}
+
+## Steps to Reproduce
+
+1. 
+2. 
+3. 
+
+## Expected Behavior
+
+{What should happen.}
+
+## Actual Behavior
+
+{What actually happens. Include any error messages or observable symptoms.}
+
+## Impact
+
+- {Who or what is affected, and how severely.}
+
+## Suspected Location
+
+- {File path(s) or component(s) most likely responsible.}
+
+## Notes
+
+- {Workarounds, related issues, env var context, etc.}
+
+---
+
+## Implementation Checklist
+
+- [ ] Root cause identified
+- [ ] Fix implemented
+- [ ] `{your check command}` passes
+- [ ] No secrets or `.env` files committed
+- [ ] No unrelated files modified
+
+---
+
+## Post-Mortem
+
+> Fill in after the fix is complete.
+
+### Investigation
+
+{How you traced the bug — files read, code paths followed, assumptions tested.}
+
+### Root Cause
+
+{Precise explanation of the defective code and why it caused the symptom.}
+
+### Fix
+
+{What changed and why. Include file paths and key line references.}
+
+### Lessons
+
+- {Takeaways applicable to future work — patterns to avoid, checks to add, etc.}

package/docs/templates/TEMPLATE-CI.yml

@@ -0,0 +1,25 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # TODO: Add stack setup steps, e.g.:
+      # - uses: actions/setup-node@v4
+      #   with: { node-version: 20 }
+      # - run: npm ci
+
+      - name: Run checks
+        run: |
+          # TODO: Paste your check command from .claude/project-checks.md
+          # Example: npm run typecheck && npm run lint && npm test
+          echo "CI not configured — fill in the check command above"
+          exit 1

package/docs/templates/TEMPLATE-DECISIONS.md

@@ -0,0 +1,11 @@
+# Decisions: {Goal Title}
+
+**Goal**: [{goal-slug}](goal.md)
+
+## D-001: {Decision title}
+- **Category:** tech-stack | architecture | scope | pattern | trade-off
+- **Decided:** {what was chosen}
+- **Alternatives considered:** {list}
+- **Reasoning:** {why this choice}
+- **Revisit if:** {condition that would invalidate this decision}
+- **Used by:** {feature-slug-1}, {feature-slug-2}