wells-agent 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (181) hide show
  1. wells_agent-0.3.0/.env.example +120 -0
  2. wells_agent-0.3.0/.github/workflows/binary.yml +73 -0
  3. wells_agent-0.3.0/.github/workflows/build-index-wheels.yml +57 -0
  4. wells_agent-0.3.0/.github/workflows/ci.yml +24 -0
  5. wells_agent-0.3.0/.github/workflows/pypi.yml +30 -0
  6. wells_agent-0.3.0/.github/workflows/release-index.yml +68 -0
  7. wells_agent-0.3.0/.gitignore +30 -0
  8. wells_agent-0.3.0/.gitmodules +24 -0
  9. wells_agent-0.3.0/.python-version +1 -0
  10. wells_agent-0.3.0/AGENT.md +178 -0
  11. wells_agent-0.3.0/AGENTS.md +81 -0
  12. wells_agent-0.3.0/PKG-INFO +1776 -0
  13. wells_agent-0.3.0/README.md +1746 -0
  14. wells_agent-0.3.0/RULES.md +155 -0
  15. wells_agent-0.3.0/about.html +401 -0
  16. wells_agent-0.3.0/debug_api.py +90 -0
  17. wells_agent-0.3.0/handoff.md +172 -0
  18. wells_agent-0.3.0/install-remote.ps1 +40 -0
  19. wells_agent-0.3.0/install-remote.sh +44 -0
  20. wells_agent-0.3.0/install.ps1 +24 -0
  21. wells_agent-0.3.0/install.sh +40 -0
  22. wells_agent-0.3.0/output_sample.txt +537 -0
  23. wells_agent-0.3.0/packaging/entry.py +10 -0
  24. wells_agent-0.3.0/packaging/wells.spec +72 -0
  25. wells_agent-0.3.0/pyproject.toml +69 -0
  26. wells_agent-0.3.0/scripts/evolve_handoff_to_autoloop.sh +60 -0
  27. wells_agent-0.3.0/scripts/wells_resumable_launch.sh +261 -0
  28. wells_agent-0.3.0/skills/add-provider-profile/SKILL.md +19 -0
  29. wells_agent-0.3.0/skills/worktree-agents/SKILL.md +84 -0
  30. wells_agent-0.3.0/src/wells/AGENT.md +111 -0
  31. wells_agent-0.3.0/src/wells/__init__.py +25 -0
  32. wells_agent-0.3.0/src/wells/__main__.py +10 -0
  33. wells_agent-0.3.0/src/wells/_gitutils.py +63 -0
  34. wells_agent-0.3.0/src/wells/acp_server.py +390 -0
  35. wells_agent-0.3.0/src/wells/agents/__init__.py +0 -0
  36. wells_agent-0.3.0/src/wells/agents/architect.py +58 -0
  37. wells_agent-0.3.0/src/wells/agents/coder.py +253 -0
  38. wells_agent-0.3.0/src/wells/agents/planner.py +115 -0
  39. wells_agent-0.3.0/src/wells/agents/reviewer.py +113 -0
  40. wells_agent-0.3.0/src/wells/agents/tester.py +170 -0
  41. wells_agent-0.3.0/src/wells/background.py +668 -0
  42. wells_agent-0.3.0/src/wells/browser.py +435 -0
  43. wells_agent-0.3.0/src/wells/builtin_skills/benchmark-before-claiming/SKILL.md +16 -0
  44. wells_agent-0.3.0/src/wells/builtin_skills/dependency-audit/SKILL.md +23 -0
  45. wells_agent-0.3.0/src/wells/builtin_skills/incremental-refactor/SKILL.md +16 -0
  46. wells_agent-0.3.0/src/wells/builtin_skills/project-recon/SKILL.md +18 -0
  47. wells_agent-0.3.0/src/wells/builtin_skills/safe-migration/SKILL.md +17 -0
  48. wells_agent-0.3.0/src/wells/builtin_skills/verify-external-api/SKILL.md +15 -0
  49. wells_agent-0.3.0/src/wells/chat.py +196 -0
  50. wells_agent-0.3.0/src/wells/checkers.py +223 -0
  51. wells_agent-0.3.0/src/wells/cli.py +2789 -0
  52. wells_agent-0.3.0/src/wells/codeact.py +234 -0
  53. wells_agent-0.3.0/src/wells/codemode.py +243 -0
  54. wells_agent-0.3.0/src/wells/commands.py +103 -0
  55. wells_agent-0.3.0/src/wells/compress.py +92 -0
  56. wells_agent-0.3.0/src/wells/config.py +627 -0
  57. wells_agent-0.3.0/src/wells/context.py +128 -0
  58. wells_agent-0.3.0/src/wells/control.py +291 -0
  59. wells_agent-0.3.0/src/wells/embeddings.py +641 -0
  60. wells_agent-0.3.0/src/wells/evolve/__init__.py +65 -0
  61. wells_agent-0.3.0/src/wells/evolve/autoloop.py +280 -0
  62. wells_agent-0.3.0/src/wells/evolve/corpus.py +571 -0
  63. wells_agent-0.3.0/src/wells/evolve/mutate.py +526 -0
  64. wells_agent-0.3.0/src/wells/evolve/runner.py +799 -0
  65. wells_agent-0.3.0/src/wells/evolve/schema.py +168 -0
  66. wells_agent-0.3.0/src/wells/executor.py +3008 -0
  67. wells_agent-0.3.0/src/wells/finisher.py +232 -0
  68. wells_agent-0.3.0/src/wells/fleet.py +357 -0
  69. wells_agent-0.3.0/src/wells/gitops.py +375 -0
  70. wells_agent-0.3.0/src/wells/graph.py +167 -0
  71. wells_agent-0.3.0/src/wells/hooks.py +215 -0
  72. wells_agent-0.3.0/src/wells/index_tools.py +560 -0
  73. wells_agent-0.3.0/src/wells/index_watcher.py +164 -0
  74. wells_agent-0.3.0/src/wells/logger.py +107 -0
  75. wells_agent-0.3.0/src/wells/logo.py +24 -0
  76. wells_agent-0.3.0/src/wells/main.py +1702 -0
  77. wells_agent-0.3.0/src/wells/mcp_client.py +448 -0
  78. wells_agent-0.3.0/src/wells/mcp_server.py +826 -0
  79. wells_agent-0.3.0/src/wells/memory.py +296 -0
  80. wells_agent-0.3.0/src/wells/memory_bridge.py +195 -0
  81. wells_agent-0.3.0/src/wells/notify.py +142 -0
  82. wells_agent-0.3.0/src/wells/personas.py +454 -0
  83. wells_agent-0.3.0/src/wells/pricing.py +109 -0
  84. wells_agent-0.3.0/src/wells/principles.py +117 -0
  85. wells_agent-0.3.0/src/wells/providers.py +462 -0
  86. wells_agent-0.3.0/src/wells/recovery_hints.py +121 -0
  87. wells_agent-0.3.0/src/wells/reflections.py +552 -0
  88. wells_agent-0.3.0/src/wells/repomap.py +256 -0
  89. wells_agent-0.3.0/src/wells/rules.py +546 -0
  90. wells_agent-0.3.0/src/wells/runtime.py +86 -0
  91. wells_agent-0.3.0/src/wells/safety.py +244 -0
  92. wells_agent-0.3.0/src/wells/sandbox.py +235 -0
  93. wells_agent-0.3.0/src/wells/schedule.py +362 -0
  94. wells_agent-0.3.0/src/wells/sessions.py +210 -0
  95. wells_agent-0.3.0/src/wells/settings.py +845 -0
  96. wells_agent-0.3.0/src/wells/setup.py +322 -0
  97. wells_agent-0.3.0/src/wells/skill_authoring.py +479 -0
  98. wells_agent-0.3.0/src/wells/skills.py +537 -0
  99. wells_agent-0.3.0/src/wells/spend_guard.py +113 -0
  100. wells_agent-0.3.0/src/wells/state.py +60 -0
  101. wells_agent-0.3.0/src/wells/subagents.py +251 -0
  102. wells_agent-0.3.0/src/wells/summarize.py +89 -0
  103. wells_agent-0.3.0/src/wells/todo.py +118 -0
  104. wells_agent-0.3.0/src/wells/tokens.py +277 -0
  105. wells_agent-0.3.0/src/wells/tools.py +1248 -0
  106. wells_agent-0.3.0/src/wells/traces.py +465 -0
  107. wells_agent-0.3.0/src/wells/tui.py +4366 -0
  108. wells_agent-0.3.0/src/wells/user_memory.py +303 -0
  109. wells_agent-0.3.0/src/wells/vision.py +164 -0
  110. wells_agent-0.3.0/src/wells/web.py +249 -0
  111. wells_agent-0.3.0/src/wells/worktree.py +245 -0
  112. wells_agent-0.3.0/tests/__init__.py +0 -0
  113. wells_agent-0.3.0/tests/conftest.py +26 -0
  114. wells_agent-0.3.0/tests/test_acp_server.py +371 -0
  115. wells_agent-0.3.0/tests/test_background.py +304 -0
  116. wells_agent-0.3.0/tests/test_background_worktrees.py +333 -0
  117. wells_agent-0.3.0/tests/test_batch_masking.py +240 -0
  118. wells_agent-0.3.0/tests/test_browser.py +250 -0
  119. wells_agent-0.3.0/tests/test_chat.py +120 -0
  120. wells_agent-0.3.0/tests/test_codeact.py +204 -0
  121. wells_agent-0.3.0/tests/test_codemode.py +119 -0
  122. wells_agent-0.3.0/tests/test_commands.py +135 -0
  123. wells_agent-0.3.0/tests/test_crossharness.py +87 -0
  124. wells_agent-0.3.0/tests/test_embeddings.py +403 -0
  125. wells_agent-0.3.0/tests/test_evolve.py +779 -0
  126. wells_agent-0.3.0/tests/test_evolve_autoloop.py +224 -0
  127. wells_agent-0.3.0/tests/test_evolve_mutate.py +323 -0
  128. wells_agent-0.3.0/tests/test_executor.py +1773 -0
  129. wells_agent-0.3.0/tests/test_fleet.py +341 -0
  130. wells_agent-0.3.0/tests/test_headless.py +254 -0
  131. wells_agent-0.3.0/tests/test_hooks.py +234 -0
  132. wells_agent-0.3.0/tests/test_layer3.py +259 -0
  133. wells_agent-0.3.0/tests/test_logger.py +39 -0
  134. wells_agent-0.3.0/tests/test_mcp_client.py +270 -0
  135. wells_agent-0.3.0/tests/test_mcp_server.py +197 -0
  136. wells_agent-0.3.0/tests/test_memory.py +117 -0
  137. wells_agent-0.3.0/tests/test_memory_bridge.py +129 -0
  138. wells_agent-0.3.0/tests/test_notify.py +192 -0
  139. wells_agent-0.3.0/tests/test_orchestrator.py +369 -0
  140. wells_agent-0.3.0/tests/test_personas.py +333 -0
  141. wells_agent-0.3.0/tests/test_platform.py +344 -0
  142. wells_agent-0.3.0/tests/test_principles.py +122 -0
  143. wells_agent-0.3.0/tests/test_providers_and_settings.py +530 -0
  144. wells_agent-0.3.0/tests/test_quality.py +393 -0
  145. wells_agent-0.3.0/tests/test_recovery_hints.py +45 -0
  146. wells_agent-0.3.0/tests/test_reflections.py +278 -0
  147. wells_agent-0.3.0/tests/test_rules.py +465 -0
  148. wells_agent-0.3.0/tests/test_sandbox.py +186 -0
  149. wells_agent-0.3.0/tests/test_schedule.py +284 -0
  150. wells_agent-0.3.0/tests/test_skill_authoring.py +276 -0
  151. wells_agent-0.3.0/tests/test_skills.py +585 -0
  152. wells_agent-0.3.0/tests/test_spend_guard.py +123 -0
  153. wells_agent-0.3.0/tests/test_stepwise.py +200 -0
  154. wells_agent-0.3.0/tests/test_stop_banner.py +188 -0
  155. wells_agent-0.3.0/tests/test_todo.py +177 -0
  156. wells_agent-0.3.0/tests/test_tools.py +400 -0
  157. wells_agent-0.3.0/tests/test_trace_analysis.py +392 -0
  158. wells_agent-0.3.0/tests/test_traces.py +150 -0
  159. wells_agent-0.3.0/tests/test_tui.py +662 -0
  160. wells_agent-0.3.0/tests/test_user_memory.py +237 -0
  161. wells_agent-0.3.0/tests/test_vision.py +129 -0
  162. wells_agent-0.3.0/tests/test_vision_cli.py +203 -0
  163. wells_agent-0.3.0/tests/test_web.py +256 -0
  164. wells_agent-0.3.0/uv.lock +2405 -0
  165. wells_agent-0.3.0/wells +109 -0
  166. wells_agent-0.3.0/wells-index/Cargo.lock +859 -0
  167. wells_agent-0.3.0/wells-index/Cargo.toml +38 -0
  168. wells_agent-0.3.0/wells-index/README.md +218 -0
  169. wells_agent-0.3.0/wells-index/build.rs +76 -0
  170. wells_agent-0.3.0/wells-index/pyproject.toml +33 -0
  171. wells_agent-0.3.0/wells-index/python/wells_index/__init__.py +12 -0
  172. wells_agent-0.3.0/wells-index/src/detect.rs +84 -0
  173. wells_agent-0.3.0/wells-index/src/engine.rs +147 -0
  174. wells_agent-0.3.0/wells-index/src/graph.rs +127 -0
  175. wells_agent-0.3.0/wells-index/src/hash.rs +17 -0
  176. wells_agent-0.3.0/wells-index/src/lib.rs +175 -0
  177. wells_agent-0.3.0/wells-index/src/parse.rs +535 -0
  178. wells_agent-0.3.0/wells-index/src/query.rs +20 -0
  179. wells_agent-0.3.0/wells-index/src/store.rs +377 -0
  180. wells_agent-0.3.0/wells.bat +117 -0
  181. wells_agent-0.3.0/wells_logo.png +0 -0
@@ -0,0 +1,120 @@
1
+ # Wells harness — example configuration.
2
+ # Copy to .env and edit. Or run `wells config` for an interactive menu.
3
+
4
+ # ===========================================================================
5
+ # Provider profiles (model-agnostic core)
6
+ # ===========================================================================
7
+ # A *profile* is a named bundle of (provider kind, model, api key, base url).
8
+ # Configure each profile with MODEL_<name> / API_KEY_<name> / BASE_URL_<name>.
9
+
10
+ # Which profiles are configured (comma-separated) and which is active.
11
+ MODEL_PROFILES=zai
12
+ MODEL_PROFILE=zai
13
+ # Optional: cheaper model for low-stakes subtasks (summarize/compress/etc).
14
+ # MODEL_PROFILE_CHEAP=zai
15
+ # Optional: vision-capable profile, routed to automatically when a task has
16
+ # image attachments and the active profile isn't vision-capable (see
17
+ # wells.vision.provider_supports_vision). Blank = same as active. Manage
18
+ # from `wells config` -> "v) Add / switch / clear vision provider profile".
19
+ # MODEL_PROFILE_VISION=openrouter
20
+
21
+ # --- Built-in `zai` profile (Z.ai GLM, OpenAI-compatible) ------------------
22
+ # Uses the CODING endpoint (/api/coding/paas/v4/) required by GLM-4.x/5.x.
23
+ # NOTE: legacy ZAI_* vars below ALSO work and seed this same profile; explicit
24
+ # MODEL_zai / BASE_URL_zai / API_KEY_zai take precedence when both are set.
25
+ MODEL_zai=glm-5.2
26
+ API_KEY_zai=your-zai-api-key-here
27
+ BASE_URL_zai=https://api.z.ai/api/coding/paas/v4/
28
+
29
+ # --- Example: add more profiles (uncomment + edit) -------------------------
30
+ # Google Gemini (requires: pip install langchain-google-genai):
31
+ # MODEL_gemini=gemini-2.0-flash
32
+ # API_KEY_gemini=your-gemini-api-key
33
+ #
34
+ # OpenAI direct:
35
+ # MODEL_OPENAI=gpt-5o-mini
36
+ # API_KEY_OPENAI=sk-...
37
+ #
38
+ # OpenRouter (hundreds of models via one key; also reads OPENROUTER_API_KEY
39
+ # automatically, so you don't need to duplicate it as API_KEY_openrouter):
40
+ # MODEL_openrouter=anthropic/claude-sonnet-4-5
41
+ # API_KEY_openrouter=sk-or-...
42
+ #
43
+ # OpenRouter free vision model, as a dedicated vision profile (:free models
44
+ # have low rate limits and vary in availability -- check openrouter.ai/models
45
+ # for the current :free vision lineup):
46
+ # MODEL_openrouter=nvidia/nemotron-nano-12b-v2-vl:free
47
+ # MODEL_PROFILE_VISION=openrouter
48
+ #
49
+ # Anthropic direct (requires: pip install langchain-anthropic):
50
+ # MODEL_anthropic=claude-sonnet-4-5
51
+ # API_KEY_anthropic=sk-ant-...
52
+ #
53
+ # Local Ollama (requires: pip install langchain-ollama):
54
+ # MODEL_ollama=devstral
55
+ # BASE_URL_ollama=http://localhost:11434
56
+ #
57
+ # Any OpenAI-compatible local endpoint (vLLM, LM Studio, etc.):
58
+ # MODEL_local=my-finetune
59
+ # BASE_URL_local=http://localhost:8000/v1
60
+
61
+ # ===========================================================================
62
+ # Legacy Z.ai variables (still supported — seeds the `zai` profile)
63
+ # ===========================================================================
64
+ # ZAI_API_KEY=your-zai-api-key-here
65
+ # ZAI_ENDPOINT=https://api.z.ai/api/coding/paas/v4/
66
+ # ZAI_MODEL=glm-5.2
67
+ # ZAI_MODEL_CHEAP=
68
+
69
+ # ===========================================================================
70
+ # Workspace + safety
71
+ # ===========================================================================
72
+ # Directory the agent is confined to (path escapes are blocked).
73
+ # Defaults to the current working directory.
74
+ # WORKSPACE_ROOT=/path/to/your/project
75
+
76
+ # Safety policy for writes/shell: auto | approve | dryrun
77
+ # auto - execute immediately (confined to WORKSPACE_ROOT)
78
+ # approve - require an approval callback (dry-run if none wired)
79
+ # dryrun - never execute; describe what would happen
80
+ HARNESS_SAFETY=auto
81
+
82
+ # Plan mode: coder plans edits without applying them (review-first workflow).
83
+ PLAN_MODE=0
84
+
85
+ # ===========================================================================
86
+ # Run behaviour
87
+ # ===========================================================================
88
+ # Max coder <-> tester <-> reviewer loop iterations.
89
+ MAX_ITERATIONS=3
90
+ # Max tool-call rounds in a single agentic executor run.
91
+ MAX_TOOL_STEPS=25
92
+ # Max seconds for a single shell command.
93
+ SHELL_TIMEOUT=120
94
+ # When 1, the finisher pushes the branch and opens a PR via `gh` after a run.
95
+ WELLS_OPEN_PR=0
96
+
97
+ # ===========================================================================
98
+ # Token optimization
99
+ # ===========================================================================
100
+ TOKEN_BUDGET_MAX_INPUT=24000
101
+ TOKEN_BUDGET_SMALL_INPUT=8000
102
+ TOKEN_BUDGET_RESERVED_OUTPUT=4000
103
+ # Replace verbatim plan/architecture with a summary on loop iterations once the
104
+ # durable context exceeds this many tokens. Set 0 or SUMMARIZE_ON_LOOP=false
105
+ # to disable (keeps full context verbatim every iteration).
106
+ SUMMARIZE_ON_LOOP=1
107
+ SUMMARIZE_THRESHOLD=1500
108
+
109
+ # ===========================================================================
110
+ # LLM tuning
111
+ # ===========================================================================
112
+ LLM_TIMEOUT=180
113
+ LLM_MAX_RETRIES=5
114
+ LLM_BACKOFF_BASE=2.0
115
+
116
+ # ===========================================================================
117
+ # Command screening (optional)
118
+ # ===========================================================================
119
+ # |-separated regex patterns always refused by run_command, regardless of safety.
120
+ # BLOCKED_COMMANDS=rm\s+-rf\s+/|mkfs|dd\s+if=|:\(\)\s*\{|shutdown|reboot
@@ -0,0 +1,73 @@
1
+ name: Build standalone binaries
2
+
3
+ # Produces the "no Python required" release artifacts: a onedir PyInstaller
4
+ # bundle per platform, zipped and attached to the GitHub Release for the tag.
5
+ # These are what the installers fall back to when a user wants an instant
6
+ # cold start instead of a uv-managed toolchain.
7
+ #
8
+ # push tag v* -> PyPI publish (pypi.yml) + binaries (this file)
9
+
10
+ on:
11
+ push:
12
+ tags: ["v*"]
13
+
14
+ permissions:
15
+ contents: write
16
+
17
+ jobs:
18
+ build:
19
+ name: ${{ matrix.label }}
20
+ runs-on: ${{ matrix.os }}
21
+ strategy:
22
+ fail-fast: false
23
+ matrix:
24
+ include:
25
+ - os: windows-latest
26
+ label: windows-x64
27
+ - os: ubuntu-latest
28
+ label: linux-x64
29
+ - os: macos-14
30
+ label: macos-arm64
31
+ - os: macos-13
32
+ label: macos-x64
33
+
34
+ steps:
35
+ - uses: actions/checkout@v4
36
+
37
+ - uses: actions/setup-python@v5
38
+ with:
39
+ python-version: "3.12"
40
+
41
+ - name: Install the project + PyInstaller
42
+ run: |
43
+ python -m pip install --upgrade pip
44
+ python -m pip install -e .
45
+ python -m pip install pyinstaller
46
+
47
+ - name: Build onedir bundle
48
+ run: pyinstaller packaging/wells.spec --noconfirm --clean
49
+
50
+ - name: Smoke test the binary
51
+ shell: bash
52
+ run: |
53
+ ./dist/wells/wells --version || ./dist/wells/wells.exe --version
54
+
55
+ - name: Package
56
+ shell: bash
57
+ run: |
58
+ VER="${GITHUB_REF_NAME#v}"
59
+ OUT="wells-${VER}-${{ matrix.label }}"
60
+ if [ "${{ runner.os }}" = "Windows" ]; then
61
+ (cd dist && 7z a -tzip "../${OUT}.zip" wells > /dev/null)
62
+ else
63
+ (cd dist && tar -czf "../${OUT}.tar.gz" wells)
64
+ fi
65
+ ls -la "${OUT}".* || true
66
+
67
+ - name: Attach to release
68
+ uses: softprops/action-gh-release@v2
69
+ with:
70
+ files: |
71
+ wells-*.zip
72
+ wells-*.tar.gz
73
+ fail_on_unmatched_files: false
@@ -0,0 +1,57 @@
1
+ name: Build wells-index wheels
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "wells-index-v*"
7
+
8
+ jobs:
9
+ build:
10
+ runs-on: ${{ matrix.os }}
11
+ strategy:
12
+ matrix:
13
+ os: [ubuntu-latest, macos-latest, windows-latest]
14
+ python-version: ["3.12"]
15
+ defaults:
16
+ run:
17
+ working-directory: wells-index
18
+
19
+ steps:
20
+ - uses: actions/checkout@v4
21
+ with:
22
+ submodules: recursive
23
+
24
+ - uses: actions/setup-python@v5
25
+ with:
26
+ python-version: ${{ matrix.python-version }}
27
+
28
+ - name: Install Rust
29
+ uses: dtolnay/rust-toolchain@stable
30
+
31
+ - name: Install maturin
32
+ run: pip install maturin
33
+
34
+ - name: Build wheels
35
+ run: maturin build --release
36
+
37
+ - name: Upload artifacts
38
+ uses: actions/upload-artifact@v4
39
+ with:
40
+ name: wheels-${{ matrix.os }}
41
+ path: wells-index/target/wheels/
42
+
43
+ publish:
44
+ needs: build
45
+ runs-on: ubuntu-latest
46
+ if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/')
47
+
48
+ steps:
49
+ - uses: actions/download-artifact@v4
50
+ with:
51
+ merge-multiple: true
52
+ path: wheels/
53
+
54
+ - uses: pypa/gh-action-pypi-publish@release/v1
55
+ with:
56
+ password: ${{ secrets.PYPI_API_TOKEN }}
57
+ packages-dir: wheels/
@@ -0,0 +1,24 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches: [master]
6
+ pull_request:
7
+ branches: [master]
8
+
9
+ jobs:
10
+ test:
11
+ runs-on: ubuntu-latest
12
+ steps:
13
+ - uses: actions/checkout@v4
14
+
15
+ - name: Install uv
16
+ uses: astral-sh/setup-uv@v5
17
+ with:
18
+ python-version: "3.12"
19
+
20
+ - name: Sync dependencies
21
+ run: uv sync
22
+
23
+ - name: Run tests
24
+ run: uv run pytest -q
@@ -0,0 +1,30 @@
1
+ name: Publish to PyPI
2
+
3
+ # Trusted publishing (OIDC): no API tokens. Configure once at
4
+ # https://pypi.org/manage/account/publishing/ :
5
+ # PyPI project name: wells-agent
6
+ # owner: corbybender repo: Wells workflow: pypi.yml environment: pypi
7
+ # Then pushing a v* tag builds and publishes.
8
+
9
+ on:
10
+ push:
11
+ tags: ["v*"]
12
+
13
+ permissions:
14
+ id-token: write
15
+
16
+ jobs:
17
+ build-and-publish:
18
+ runs-on: ubuntu-latest
19
+ environment: pypi
20
+ steps:
21
+ - uses: actions/checkout@v4
22
+ - uses: astral-sh/setup-uv@v5
23
+ with:
24
+ python-version: "3.12"
25
+ - name: Build sdist + wheel
26
+ run: uv build
27
+ - name: Check metadata
28
+ run: uvx twine check dist/*
29
+ - name: Publish to PyPI
30
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,68 @@
1
+ name: Release wells-index
2
+
3
+ # Builds wells-index wheels for Linux/macOS/Windows on Python 3.12 + 3.13 and
4
+ # publishes them to PyPI. Trigger by pushing a tag like `index-v0.1.1`, or run
5
+ # manually from the Actions tab (workflow_dispatch builds without publishing
6
+ # unless "publish" is set to true).
7
+ #
8
+ # Publishing auth: PyPI "trusted publishing" (configure this repo + workflow
9
+ # as a trusted publisher for the wells-index project on pypi.org — no token
10
+ # needed). The pypi environment + id-token permission below are required.
11
+
12
+ on:
13
+ push:
14
+ tags: ["index-v*"]
15
+ workflow_dispatch:
16
+ inputs:
17
+ publish:
18
+ description: "Publish to PyPI"
19
+ type: boolean
20
+ default: false
21
+
22
+ jobs:
23
+ build:
24
+ strategy:
25
+ matrix:
26
+ os: [ubuntu-latest, macos-latest, windows-latest]
27
+ runs-on: ${{ matrix.os }}
28
+ steps:
29
+ - uses: actions/checkout@v4
30
+
31
+ - uses: actions/setup-python@v5
32
+ with:
33
+ python-version: |
34
+ 3.12
35
+ 3.13
36
+
37
+ - name: Build wheels
38
+ uses: PyO3/maturin-action@v1
39
+ with:
40
+ working-directory: wells-index
41
+ command: build
42
+ args: --release --interpreter python3.12 python3.13
43
+ manylinux: auto
44
+
45
+ - uses: actions/upload-artifact@v4
46
+ with:
47
+ name: wheels-${{ matrix.os }}
48
+ path: wells-index/target/wheels/*.whl
49
+
50
+ publish:
51
+ needs: build
52
+ if: startsWith(github.ref, 'refs/tags/index-v') || inputs.publish
53
+ runs-on: ubuntu-latest
54
+ environment: pypi
55
+ permissions:
56
+ id-token: write
57
+ steps:
58
+ - uses: actions/download-artifact@v4
59
+ with:
60
+ pattern: wheels-*
61
+ merge-multiple: true
62
+ path: dist
63
+
64
+ - name: Publish to PyPI
65
+ uses: pypa/gh-action-pypi-publish@release/v1
66
+ with:
67
+ packages-dir: dist
68
+ skip-existing: true
@@ -0,0 +1,30 @@
1
+ # Python-generated files
2
+ __pycache__/
3
+ *.py[oc]
4
+ build/
5
+ dist/
6
+ wheels/
7
+ *.egg-info
8
+
9
+ # Virtual environments
10
+ .venv
11
+
12
+ # Environment files
13
+ .env
14
+
15
+ # Local model caches
16
+ .fastembed_cache/
17
+
18
+ # Generated repo index + Rust build artifacts
19
+ .wells_index/
20
+ wells-index/target/
21
+
22
+ # Windows reserved-name artifact
23
+ nul
24
+
25
+ # Runtime traces
26
+ .wells/
27
+
28
+ # Watchdog/launch logs (scripts/wells_resumable_launch.sh) — force-add
29
+ # specific ones deliberately kept as evidence, same convention as .wells/
30
+ logs/
@@ -0,0 +1,24 @@
1
+ [submodule "wells-index/grammars/python"]
2
+ path = wells-index/grammars/python
3
+ url = https://github.com/tree-sitter/tree-sitter-python.git
4
+ [submodule "wells-index/grammars/javascript"]
5
+ path = wells-index/grammars/javascript
6
+ url = https://github.com/tree-sitter/tree-sitter-javascript.git
7
+ [submodule "wells-index/grammars/typescript"]
8
+ path = wells-index/grammars/typescript
9
+ url = https://github.com/tree-sitter/tree-sitter-typescript.git
10
+ [submodule "wells-index/grammars/go"]
11
+ path = wells-index/grammars/go
12
+ url = https://github.com/tree-sitter/tree-sitter-go.git
13
+ [submodule "wells-index/grammars/rust"]
14
+ path = wells-index/grammars/rust
15
+ url = https://github.com/tree-sitter/tree-sitter-rust.git
16
+ [submodule "wells-index/grammars/java"]
17
+ path = wells-index/grammars/java
18
+ url = https://github.com/tree-sitter/tree-sitter-java.git
19
+ [submodule "wells-index/grammars/c"]
20
+ path = wells-index/grammars/c
21
+ url = https://github.com/tree-sitter/tree-sitter-c.git
22
+ [submodule "wells-index/grammars/cpp"]
23
+ path = wells-index/grammars/cpp
24
+ url = https://github.com/tree-sitter/tree-sitter-cpp.git
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,178 @@
1
+ # AGENT.md
2
+
3
+ > A practical set of operating principles for AI coding agents, inspired
4
+ > by the public four-rule CLAUDE.md philosophy and expanded with modern
5
+ > agent engineering practices. This is **not** an official Karpathy
6
+ > document, but a community-informed synthesis.
7
+
8
+ ## 1. Think Before Coding
9
+
10
+ - State assumptions before implementation.
11
+ - Surface tradeoffs and constraints.
12
+ - Ask clarifying questions instead of guessing.
13
+ - If no interactive user is available (bench runs, CI, autonomous
14
+ tasks), do not stall on the question — record the assumption you are
15
+ making, proceed with the safest interpretation, and state it in the
16
+ final report.
17
+ - Recommend a simpler approach when appropriate.
18
+
19
+ ## 2. Simplicity First
20
+
21
+ - Write the minimum code necessary.
22
+ - Avoid speculative abstractions.
23
+ - Do not future-proof unless requested.
24
+ - Prefer readability over cleverness.
25
+
26
+ ## 3. Surgical Changes
27
+
28
+ - Change only what the task requires.
29
+ - Avoid unrelated refactors or cleanup.
30
+ - Match the project's existing style and architecture.
31
+
32
+ ## 4. Goal-Driven Execution
33
+
34
+ - Define success before writing code.
35
+ - Verify that the requested outcome is achieved.
36
+ - Stop when the goal is complete.
37
+ - Name the concrete deliverable before starting work — usually one
38
+ edit in one file. Everything else around it (new tests, changelog
39
+ entries, docs) is secondary, and comes only after that edit is on
40
+ disk.
41
+
42
+ ## 5. Deterministic First
43
+
44
+ Use traditional code whenever logic can be deterministic.
45
+
46
+ LLMs are best for: - Drafting - Summarization - Classification -
47
+ Extraction - Reasoning over unstructured information
48
+
49
+ Use deterministic code for: - Business rules - Routing - Validation -
50
+ Retries - Persistence - Authorization
51
+
52
+ ## 6. Budget Everything
53
+
54
+ Every agent has limits. - Maximum tokens - Maximum cost - Maximum
55
+ runtime - Maximum retries
56
+
57
+ Fail explicitly instead of running indefinitely — and fail early:
58
+
59
+ - Treat the wall-clock deadline as a first-class constraint. Before
60
+ starting any long step (a big read, a full test suite, a retry
61
+ loop), estimate whether it can plausibly finish in the remaining
62
+ time; if it cannot, split it or skip to a cheaper check.
63
+ - Checkpoint progress. Write the best-so-far result — including what
64
+ is verified and what is not — before the clock runs out. A
65
+ delivered, honestly-labeled partial result beats a timeout with
66
+ nothing.
67
+ - Never let a single command, verification pass, or investigation loop
68
+ consume the whole budget.
69
+ - Budget by phase, roughly: no more than a third of the run on
70
+ investigation, half on making the change, and keep the final fifth
71
+ in reserve for verification and writing up. If investigation is
72
+ still going past its share, stop reading and act on what is known.
73
+ - Investigate cheaply: prefer indexed symbol lookups over grepping
74
+ whole files, read only the lines you need, never re-read a file you
75
+ have already read, and batch independent lookups into one round
76
+ trip.
77
+ - Land the edit before perfecting it. A concrete change already
78
+ written to disk beats a flawless plan still being polished when the
79
+ clock runs out. Draft the change as soon as you know the file and
80
+ the lines, then refine if time remains.
81
+ - Give every command a hard timeout, and never re-run a command that
82
+ already succeeded just to see it again.
83
+ - Match effort to the size of the ask. A patch of a few lines should
84
+ take minutes end to end; when peripheral work — environment setup,
85
+ installing dependencies, authoring new tests, updating changelogs —
86
+ grows bigger than the change itself, cut the peripheral work, not
87
+ the change.
88
+ - Treat a setup or test command that fails twice as blocked: stop
89
+ retrying it, make the edit anyway, and report which verification
90
+ could not run. Never spend the delivery budget unblocking a checker.
91
+
92
+ ## 7. Verify Before Trust
93
+
94
+ Treat every model output as a hypothesis.
95
+
96
+ Before making impactful changes: - Run tests - Validate outputs -
97
+ Confirm assumptions - Prefer automated verification
98
+
99
+ Verification is budgeted, not repeated: run the exact failing check (and
100
+ one rerun per fix iteration) rather than re-running broad suites on a
101
+ loop.
102
+
103
+ Run the cheapest check that can actually fail. One targeted test, a
104
+ snippet against the real API, or a compile of the touched file usually
105
+ settles the question; a full suite or a hand-built reproduction harness
106
+ that costs more than the fix itself is scope creep, not verification.
107
+ If building the reproduction would eat the implementation budget, make
108
+ the change, verify what you cheaply can, and say what went unverified.
109
+
110
+ ## 8. Fail Loud
111
+
112
+ Never silently continue after uncertainty.
113
+
114
+ If confidence is low: - Explain why - Present options - Ask for
115
+ clarification
116
+
117
+ Avoid confident but incorrect behavior.
118
+
119
+ ## 9. Isolate Side Effects
120
+
121
+ Separate reasoning from execution.
122
+
123
+ The harness gates high-risk side effects via its safety system (the
124
+ `HARNESS_SAFETY` setting). When the harness permits an action — including
125
+ deployments, publishing, and external API calls — the agent **must execute
126
+ it** using the available tools. Do not refuse or simulate an action that the
127
+ harness has allowed; that decision already happened upstream.
128
+
129
+ The harness is responsible for: - Blocking destructive commands - Requiring
130
+ approval for sensitive operations - Constraining the workspace
131
+
132
+ The agent is responsible for: - Reading the right files before acting -
133
+ Running commands and observing the actual output - Reporting results
134
+ accurately, including failures
135
+
136
+ ## 10. Check Before Declaring Done
137
+
138
+ Before finishing, confirm: - The request was fully addressed. - No
139
+ unnecessary complexity was introduced. - Only relevant code was
140
+ changed. - The solution was verified. - Remaining assumptions are
141
+ documented. - The result was delivered inside the time budget — if it
142
+ wasn't, say so explicitly rather than letting the run time out silently.
143
+
144
+ If the task started from a specific failing check — a failing test, a
145
+ reproducible bug, an error message — re-run that *exact* check one more
146
+ time immediately before declaring done. A fix that hasn't been
147
+ confirmed against the specific thing it was meant to fix is not
148
+ verified, no matter how confident the reasoning behind it looks.
149
+ Passing a *different* or *related* check is not the same as passing
150
+ *this* one.
151
+
152
+ Delivering the change outranks verifying it. When the clock is nearly
153
+ out, write the edit first and report plainly which checks ran and which
154
+ did not — an unverified diff in hand is recoverable, a timeout with
155
+ nothing on disk is not.
156
+
157
+ ## 11. Evidence Over Confidence
158
+
159
+ Always distinguish between:
160
+
161
+ - **Observed** --- verified directly.
162
+ - **Inferred** --- logically concluded.
163
+ - **Hypothesized** --- plausible but unverified.
164
+ - **Recommended** --- suggested next action.
165
+
166
+ Never claim to have: - Run tests you did not run. - Read files you did
167
+ not inspect. - Verified behavior you did not verify. - Reproduced bugs
168
+ you did not reproduce.
169
+
170
+ Trust is built through evidence, not confidence.
171
+
172
+ ------------------------------------------------------------------------
173
+
174
+ **Guiding Principle**
175
+
176
+ > Slow down. Think clearly. Change as little as necessary. Verify
177
+ > everything. Be explicit about uncertainty. Land the change early, and
178
+ > finish inside the budget.