monkeybot 2.1.1__tar.gz

monkeybot-2.1.1/.dockerignore

@@ -0,0 +1,17 @@
+.git
+.github
+**/.venv
+**/node_modules
+**/__pycache__
+**/*.py[cod]
+**/.pytest_cache
+**/.mypy_cache
+**/.ruff_cache
+demo_agent/.emonk
+demo_agent/workspace/data/*.db
+demo_agent/workspace/data/*.db-*
+**/.env
+**/*.db-shm
+**/*.db-wal
+legacy
+tests

monkeybot-2.1.1/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master, develop]
+  pull_request:
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install ripgrep and GitHub CLI
+        run: sudo apt-get update && sudo apt-get install -y ripgrep gh
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Sync dependencies
+        run: uv sync --extra claude --extra vertex-claude --extra bedrock
+
+      - name: Mypy
+        run: uv run mypy src/monkeybot
+
+      - name: Pytest
+        run: uv run pytest tests/ -q
+
+      - name: CLI pytest
+        working-directory: cli
+        run: |
+          uv sync
+          uv run pytest -q
+
+      - name: Browser MCP pytest
+        working-directory: integrations/browser-mcp
+        run: |
+          uv sync --dev
+          uv run pytest -q
+
+      - name: Evals self-checks (no live agent, no model calls)
+        run: |
+          uv sync --extra evals
+          uv run python evals/test_assertions.py
+          uv run python evals/test_report.py
+          uv run python evals/test_runner_sse.py

monkeybot-2.1.1/.github/workflows/live-eval-smoke.yml

@@ -0,0 +1,158 @@
+name: Live eval smoke
+
+# Runs the live eval smoke suite (see docs/eval-pr-scorecard.md) and posts a Markdown
+# scorecard as a PR comment. Only two trigger points, gated in the `gate` job below —
+# LLM-judge calls cost money and take minutes, so this does not run on ordinary
+# feature-branch -> develop PRs:
+#   (a) any PR from develop into main (release-promotion gate)
+#   (b) any PR that touches a dependency lockfile (catches silent SDK breakage,
+#       e.g. provider request/response shape changes, that code review won't see)
+#
+# Cost/time budget: smoke suite is ~7 scenarios x 2-5 turns x (agent call + judge call).
+# Expect roughly $0.50-2.00 and 5-10 minutes per run depending on model pricing.
+#
+# Secrets required: NVIDIA_API_KEY (agent model, matches demo_agent's default free-tier
+# provider) and OPENAI_API_KEY (deepeval judge model — JUDGE_PROVIDER/JUDGE_MODEL below
+# pin it explicitly so scoring doesn't silently drift with deepeval's own default).
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+  pull-requests: write
+
+jobs:
+  gate:
+    runs-on: ubuntu-latest
+    outputs:
+      run: ${{ steps.decide.outputs.run }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - id: decide
+        env:
+          BASE_REF: ${{ github.base_ref }}
+          HEAD_REF: ${{ github.head_ref }}
+          BASE_SHA: ${{ github.event.pull_request.base.sha }}
+          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
+        run: |
+          run=false
+          if [[ "$BASE_REF" == "main" && "$HEAD_REF" == "develop" ]]; then
+            run=true
+          fi
+          changed="$(git diff --name-only "$BASE_SHA" "$HEAD_SHA")"
+          for f in uv.lock cli/uv.lock demo_agent/uv.lock; do
+            if grep -qxF "$f" <<<"$changed"; then
+              run=true
+            fi
+          done
+          echo "run=$run" >> "$GITHUB_OUTPUT"
+
+  secrets:
+    needs: gate
+    if: needs.gate.outputs.run == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Require live-eval secrets
+        env:
+          NVIDIA_API_KEY: ${{ secrets.NVIDIA_API_KEY }}
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          missing=()
+          [[ -z "$NVIDIA_API_KEY" ]] && missing+=("NVIDIA_API_KEY (agent model, https://build.nvidia.com)")
+          [[ -z "$OPENAI_API_KEY" ]] && missing+=("OPENAI_API_KEY (deepeval judge model)")
+          if [[ ${#missing[@]} -gt 0 ]]; then
+            echo "::error::Live eval smoke requires repository secrets that are not configured:"
+            for m in "${missing[@]}"; do echo "::error::  - $m"; done
+            exit 1
+          fi
+
+  live-eval:
+    needs: [gate, secrets]
+    if: needs.gate.outputs.run == 'true'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Sync root deps (evals/report.py needs deepeval, langfuse)
+        run: uv sync --extra evals
+
+      - name: Sync demo_agent deps
+        working-directory: demo_agent
+        run: uv sync
+
+      - name: Boot monkeybot gateway (demo_agent workspace)
+        working-directory: demo_agent
+        env:
+          NVIDIA_API_KEY: ${{ secrets.NVIDIA_API_KEY }}
+          SANDBOX_ENABLED: "false" # no Docker socket in this runner
+          # Small context window so context/summarization_trigger.yaml actually crosses the
+          # real summarization threshold; the other smoke scenarios are short enough to fit.
+          MODEL_CONTEXT_WINDOW: "8000"
+        run: |
+          uv run -m monkeybot.gateway.main > /tmp/gateway.log 2>&1 &
+          echo $! > /tmp/gateway.pid
+          for i in $(seq 1 30); do
+            if curl -sf http://127.0.0.1:8787/health > /dev/null; then
+              echo "gateway healthy"
+              exit 0
+            fi
+            sleep 2
+          done
+          echo "gateway did not become healthy" >&2
+          cat /tmp/gateway.log >&2
+          exit 1
+
+      - name: Run smoke suite report
+        env:
+          AGENT_URL: http://127.0.0.1:8787
+          JUDGE_PROVIDER: openai
+          JUDGE_MODEL: gpt-4o-mini
+          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
+        run: |
+          uv run python -m evals.report \
+            --suite smoke \
+            --baseline evals/baselines/smoke.json \
+            --fail-on-regression \
+            | tee eval-report.md
+
+      - name: Post report as PR comment
+        if: always()
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const fs = require("fs");
+            const body = fs.existsSync("eval-report.md")
+              ? fs.readFileSync("eval-report.md", "utf8")
+              : "## monkeybot Eval Scorecard\n\n`FAIL` — the report step did not complete " +
+                "(gateway boot or the report command itself errored before writing a report). " +
+                "See the workflow run logs for details.";
+            await github.rest.issues.createComment({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              body,
+            });
+
+      - name: Upload run + report artifacts
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: live-eval-smoke-${{ github.run_id }}
+          path: |
+            evals/runs/
+            eval-report.md
+          if-no-files-found: ignore
+
+      - name: Stop gateway
+        if: always()
+        working-directory: demo_agent
+        run: kill "$(cat /tmp/gateway.pid)" 2>/dev/null || true

monkeybot-2.1.1/.github/workflows/prepare-release.yml

@@ -0,0 +1,36 @@
+name: Prepare release
+
+on:
+  workflow_dispatch:
+    inputs:
+      package:
+        description: "Which package to release"
+        required: true
+        type: choice
+        options: [core, cli]
+      bump:
+        description: "Version bump"
+        required: true
+        type: choice
+        options: [patch, minor, major]
+
+permissions:
+  contents: write
+  pull-requests: write
+
+jobs:
+  prepare:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: develop
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - run: python3 scripts/release.py prepare ${{ inputs.package }} ${{ inputs.bump }}
+        env:
+          GH_TOKEN: ${{ github.token }}

monkeybot-2.1.1/.github/workflows/publish-release.yml

@@ -0,0 +1,98 @@
+name: Publish release
+
+# Fires whenever main moves - i.e. right after an admin merges a release PR.
+# Branch protection on main (require PR + restrict merges to admins) is the
+# actual access control; this tags + GitHub-Releases + Trusted-Publishes to PyPI.
+#
+# PyPI Pending Trusted Publishers (one per project — environments must differ):
+#   monkeybot:     Owner human-plus-machine / Repo monkeybot /
+#                  Workflow publish-release.yml / Environment pypi
+#   monkeybot-cli: Owner human-plus-machine / Repo monkeybot /
+#                  Workflow publish-release.yml / Environment pypi-cli
+#
+# GitHub: create Environments named exactly `pypi` and `pypi-cli`.
+on:
+  push:
+    branches: [main]
+    paths:
+      - "pyproject.toml"
+      - "cli/pyproject.toml"
+      - "CHANGELOG.md"
+
+permissions:
+  contents: write
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    outputs:
+      packages: ${{ steps.release.outputs.packages }}
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Configure git identity
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+
+      - id: release
+        run: python3 scripts/release.py publish
+        env:
+          GH_TOKEN: ${{ github.token }}
+
+  # Core before CLI (separate jobs / environments — required for two pending publishers).
+  pypi-core:
+    needs: publish
+    if: contains(format(',{0},', needs.publish.outputs.packages), ',core,')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/monkeybot
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build core
+        run: uv build --out-dir dist/core .
+      - name: Publish core to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/core
+          skip-existing: true
+
+  pypi-cli:
+    needs: [publish, pypi-core]
+    # Run when cli is in the release set. If core wasn't released this run,
+    # pypi-core is skipped — treat that as success so cli can still publish.
+    if: |
+      always() &&
+      needs.publish.result == 'success' &&
+      contains(format(',{0},', needs.publish.outputs.packages), ',cli,') &&
+      (needs.pypi-core.result == 'success' || needs.pypi-core.result == 'skipped')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi-cli
+      url: https://pypi.org/p/monkeybot-cli
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build cli
+        run: uv build --out-dir dist/cli cli
+      - name: Publish cli to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/cli
+          skip-existing: true

monkeybot-2.1.1/.gitignore

@@ -0,0 +1,64 @@
+# Internal (not shipped in OSS)
+internal/
+
+# Environment
+.env
+.env.*
+!.env.example
+
+# Local scaffolded harness config (defaults ship in monkeybot-cli scaffold_defaults/)
+/monkeybot_config/
+
+# Demo agent live config (materialized from monkeybot_config_example/ by demo_agent/run.sh)
+demo_agent/monkeybot_config/
+
+# Live eval run artifacts (only evals/baselines/ is versioned)
+/evals/runs/
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+
+# uv
+.venv/
+.uv/
+
+# Data (SQLite DB + memory files — never commit)
+data/
+
+# Testing & coverage
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# macOS
+.DS_Store
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Docker
+docker/data/
+
+# Planning Documents
+.prt/
+.monkeymode/
+
+# Reference clones (read-only)
+code/
+
+# Local venv for evals dependency experiments
+.evals-venv/

monkeybot-2.1.1/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+# Pre-commit hooks for monkeybot
+# Install: uv run pre-commit install
+# Run manually: uv run pre-commit run --all-files
+
+repos:
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy (src/monkeybot)
+        entry: uv run mypy src/monkeybot
+        language: system
+        pass_filenames: false
+        always_run: true
+
+      - id: pytest
+        name: pytest (changed tests or collection check)
+        entry: bash scripts/precommit-pytest.sh
+        language: system
+        files: ^(src/monkeybot|tests)/.*\.py$
+        pass_filenames: true

monkeybot-2.1.1/AGENTS.md

@@ -0,0 +1,34 @@
+# AGENTS.md
+
+## Cursor Cloud specific instructions
+
+monkeybot is a Python 3.11+ framework (managed with `uv`) whose product is the **FastAPI SSE gateway** (`python -m monkeybot.gateway.main`). Satellite sub-projects each have their own `pyproject.toml`/`uv.lock`/`.venv` and depend on the core via an editable path: `cli/` (the `monkeybot` CLI, recommended entrypoint), `integrations/browser-mcp/` (MCP server), and `evals/` (standalone eval service). Standard install/lint/test/build commands are documented in `README.md`, `docs/getting-started.md`, and `.github/workflows/ci.yml` (the authoritative CI recipe) — refer to those rather than duplicating them.
+
+The startup update script already runs `uv sync` for the root (with the CI extras plus `evals` and `web-search`) and for `cli/` and `integrations/browser-mcp/`, so dependencies are ready. `uv` installs to `~/.local/bin`; if `uv` is not found, add that to `PATH`.
+
+Non-obvious gotchas discovered during setup:
+
+- **Run the gateway with no cloud credentials via `MODEL_PROVIDER=fake`.** It injects a deterministic scripted provider (default reply `hello`), exercising the full session → SSE → agent-loop → SQLite path without any API keys. Real providers (`gemini`, `openai`, `anthropic`, …) need keys/ADC in a repo-root `.env`.
+- **Running the gateway requires scaffolded config** at the process cwd: `cd cli && uv run monkeybot new --dest .. --yes` creates `monkeybot_config/`, `workspace/`, and `data/` at the repo root (all gitignored except the stray `.env.example`/`scripts/setup-workspace.sh` — do not commit those). Do NOT put scaffolding in the update script.
+- **The root pytest suite must NOT be run with the scaffold present.** A scaffolded `monkeybot_config/` + `workspace/` at the repo root makes 2 workspace-resolution tests fail (`tests/gateway/sse/test_routes.py::test_workspace_tree_and_file` and `tests/skills/test_generate_image_script.py::test_generate_image_script_success_mocked_vertex`); both pass in isolation. CI passes because it runs from a fresh checkout with no scaffold. Before `uv run pytest tests/ -q`, run tests in a clean tree (move `monkeybot_config/`, `workspace/`, `data/` aside, or use a checkout that was never scaffolded).
+- **`ruff` is not enforced by CI** and currently reports pre-existing failures across `src/` and `tests/`. CI gates only `mypy src/monkeybot` + pytest (root, `cli/`, `integrations/browser-mcp/`) + the three `evals/test_*.py` standalone self-check scripts. Do not treat existing `ruff check .` failures as regressions.
+- **`monkeybot doctor` reporting port 8080 "in use" or "no provider credentials" is expected** when the gateway is already running and/or you are using the `fake` provider — it is not a setup failure.
+
+## Git workflow
+
+Always sync with the remote **before** writing code — do not assume the local checkout is current.
+
+**Starting a new feature:**
+
+1. `git fetch origin develop && git checkout develop && git pull origin develop`
+2. Create the feature branch from that fresh tip: `git checkout -b cursor/<descriptive-name>-<suffix>`
+
+**Continuing an existing feature branch:**
+
+1. `git fetch origin <branch-name> && git checkout <branch-name> && git pull origin <branch-name>`
+
+**When the base branch (`develop`) has moved** and you need those changes on your feature branch:
+
+- `git fetch origin develop` then `git merge origin/develop` (or `git rebase origin/develop` if that is the project convention)
+
+Check `git status` and `git branch -a` first when the environment starts on a detached `HEAD` or an unfamiliar checkout.

monkeybot-2.1.1/BACKLOG.md

@@ -0,0 +1,77 @@
+# monkeybot Backlog
+
+---
+
+## Up Next — Major Priorities
+
+### 1. Chat Integration
+- **Google Chat gateway** — incoming webhook + event handler for Google Chat spaces.
+- **Slack gateway** — Slack Events API / socket mode integration.
+
+### 2. Evals *(in progress)*
+- Integrate eval framework (langfuse, deepeval, or similar) into the harness — not just playground-level; needs to be first-class traceability in the agent loop.
+- **Memory accuracy verification** — script exists (`scripts/verify_memory.py`) but needs a real eval strategy, not a one-off script.
+
+### 3. Scheduler
+- Wire a `Scheduler` into the FastAPI lifespan as an optional background task when `config.yaml` has `scheduler.jobs` (reference: `legacy/src/monkeybot/core/scheduler.py`).
+- Needs significant design work for cloud runtimes: Lambda/Cloud Functions have no persistent process, GKE/ECS can use sidecar or CronJob, etc. Think through heartbeat / self-scheduling before implementing.
+
+### 4. Sandbox Workspace Protection
+- Add a hard-coded deny layer inside `SandboxExecutor` that blocks `run_command` from targeting harness-owned paths: `.monkeybot/`, `monkeybot.yaml`, `*.env`, `.agents/`, `config/`.
+- Path-level policy at the executor — distinct from `command_allowlist.yaml` which is command-level. Agent should retain free rw access to `./code/`, `./data/`, etc.
+
+### 5. HITL Completion
+- The loop and `/tool-confirmations` API endpoint exist; inspectors have `confirm` as a valid `Decision.kind` but no inspector currently returns it ("Story 5" placeholder).
+- Wire an inspector that returns `confirm` for configurable tool patterns, flowing through the existing `_await_user_response` path.
+
+### 6. DurableRunStore Wiring (crash recovery) — DONE
+- Subagent runs are persisted via `CoreToolExecutor` (`record_started` / `record_completed` / `record_failed`).
+- Queue mode: set `MONKEYBOT_TASK_QUEUE=1` to enqueue with `record_pending` instead of inline spawn.
+- Worker pool: standalone `python -m monkeybot.subagents.worker` consumes queued runs with atomic `claim()` (recommended for production — its own event loop, scales independently of the gateway). `MONKEYBOT_WORKER_POOL=1` runs the same loop in-process on the gateway and is development-only (competes with the SSE event loop).
+
+### 7. CLI-managed optional service dependencies
+- `monkeybot chat` / `run` only spawn the gateway process; they don't start the Docker-backed optional services some `monkeybot.yaml` configs require: OpenSandbox (`sandbox.enabled`), Firestore emulator (`paths.db_url: firestore://...`), or the observability stack (Phoenix/Langfuse/OTel collector). `demo_agent/run.sh` currently does this orchestration via bash (build/start/health-check/cleanup), which means the CLI alone can't fully run an agent that uses those features.
+- Decide and implement: should the CLI (`doctor`, `run`, `chat`) detect these from config and actually start/stop the containers (matching `run.sh` behavior, retiring the bash script), or just validate/warn with remediation hints while the user manages Docker manually?
+- Open sub-questions if going the "CLI starts services" route: where do per-project Docker assets live (`opensandbox.docker.toml`, OTel collector yaml, compose files) — agent-project-owned files referenced from `monkeybot.yaml`, or CLI-shipped generic templates; and is the sandbox worker image (project-specific extra deps) something the CLI should build, or stay manual/documented.
+
+---
+
+## Do Later
+
+### Connectors
+- **CLI gateway** — interactive stdin/stdout (reference: `legacy/src/monkeybot/gateway/cli.py`).
+- **Webhook gateway** — generic HTTP + HMAC (reference: `legacy/src/monkeybot/gateway/webhook.py`).
+- **`python -m monkeybot` CLI** — `run` / `serve` / `usage` / `schedule` subcommands (reference: `legacy/src/monkeybot/cli.py`).
+
+### Cloud Deployments
+- **GCP server** — GCE / GKE deployment option (docs + examples exist; no IaC).
+- **AWS serverless** — Lambda + API Gateway (example handler exists; not a full deploy path).
+- **AWS server** — EC2 / ECS deployment option.
+- **Docker CI image matrix** — multi-extras build matrix in CI.
+
+### Infra
+- **Postgres as production default** — backend exists; gateway still defaults to SQLite; decide when/if this becomes the default.
+
+### Memory
+- **INDEX.md size cap** *(deferred 2026-05-15)* — `MemoryOrganizer` appends without bound; acceptable for now via `ContextCurator` selection. When indices grow wastefully large, cap with a sliding window (N=200, archive to `INDEX.archive.md`) in `core/memory_organizer.py`.
+
+### MCP
+- **MCP distro linkage** — confirm `monkeybot_config_example/monkeybot.example.yaml` paths (`paths.mcp_config`, `paths.skills_path`) match deployment; smoke-test against real MCP servers beyond the bundled LangChain docs URL.
+
+### Future platforms *(not scheduled)*
+
+Moved from README — longer-term / speculative integrations without active implementation:
+
+- **Azure OpenAI** — Azure-hosted OpenAI models
+- **Azure Blob Storage** — memory backend (`[azure]` extra; docs note as planned)
+- **Azure Key Vault** — secrets for Azure deployments
+- **AWS Secrets Manager** — secret resolver at runtime
+- **GCP Secret Manager** — finish `secrets.provider: gcp_secret_manager` wiring (schema exists; resolver not shipped)
+- **Microsoft Teams** — Teams bot interface
+- **Telegram** — Telegram bot interface
+- **DynamoDB** — checkpointer / job storage backend
+- **Cosmos DB** — Azure-native persistence options
+
+### Tooling
+- **File-op tool audit** — evaluate removing `write_file` in favor of `create_file` + `find_and_replace` in `core_tool_executor.py` and `workspace_tools.py` (reference: Claude Code patterns).
+- **Custom subagents** — allow operators to pre-configure named subagent profiles (own AGENT.md, restricted skill set, specific MCP servers) in `core_tool_executor.py`, `subagent_proto.py`, and `subagent_worker.py`.