Merge pull request #128 from WecoAI/dev

Merge Dev - Add run subcommands +  bump version (0.3.24)

Author: aliroberts

README.md

@@ -186,14 +186,50 @@ For more advanced examples, including [Triton](/examples/triton/README.md), [CUD
 
 | Command | Description | When to Use |
 |---------|-------------|-------------|
-| `weco run [options]` | Direct optimization execution | **For advanced users** - When you know exactly what to optimize and how |
+| `weco run [options]` | Start a new optimization | When you know what to optimize and how |
 | `weco resume <run-id>` | Resume an interrupted run | Continue from the last completed step |
 | `weco login` | Authenticate with Weco | First-time setup or switching accounts |
-| `weco logout` | Clear authentication credentials | To switch accounts or troubleshoot authentication issues |
+| `weco logout` | Clear authentication credentials | Switch accounts or troubleshoot auth |
 | `weco credits balance` | Check your current credit balance | Monitor usage |
 | `weco credits topup [amount]` | Purchase additional credits | When you need more credits (default: 10) |
 | `weco credits autotopup` | Configure automatic top-up | Set up automatic credit replenishment |
 
+### Run Subcommands
+
+Inspect and manage optimization runs. All output is JSON, designed for programmatic access (AI coding agents, scripts).
+
+| Command | Description |
+|---------|-------------|
+| `weco run status <run-id>` | Run progress, pending nodes, review mode flag |
+| `weco run results <run-id>` | Results sorted by metric |
+| `weco run show <run-id> --step <N\|best>` | Single node detail with code |
+| `weco run diff <run-id> --step <N\|best>` | Unified code diff between steps |
+| `weco run stop <run-id>` | Graceful termination (tree preserved) |
+| `weco run instruct <run-id> "<text>"` | Update instructions mid-run |
+| `weco run review <run-id>` | List pending approval nodes (review mode) |
+| `weco run revise <run-id> --node <id> --source <file>` | Replace a node's code |
+| `weco run submit <run-id> --node <id>` | Evaluate and submit a node |
+
+```bash
+# Check progress
+weco run status 0002e071-1b67-411f-a514-36947f0c4b31
+
+# Top 5 results as JSON
+weco run results 0002e071-1b67-411f-a514-36947f0c4b31 --top 5
+
+# Diff best solution against baseline
+weco run diff 0002e071-1b67-411f-a514-36947f0c4b31 --step best
+
+# Review mode: inspect, optionally edit, and submit
+weco run review 0002e071-1b67-411f-a514-36947f0c4b31
+weco run submit 0002e071-1b67-411f-a514-36947f0c4b31 --node <node-id>
+
+# Submit with your own code (explicit path mapping)
+weco run submit <run-id> --node <id> --source module.py=./my_version.py
+```
+
+**Source path mapping:** When using `--source` with `revise` or `submit`, you can map local files to the run's source paths using `target_path=local_path` syntax (e.g., `--source module.py=./optimized.py`). Without an explicit mapping, files are matched positionally to the run's original source paths.
+
 ### Observe Commands
 
 Track experiments from your own optimization loop (LLM agents, custom scripts, manual experiments) in the Weco dashboard:

pyproject.toml

@@ -8,7 +8,7 @@ name = "weco"
 authors = [{ name = "Weco AI Team", email = "contact@weco.ai" }]
 description = "Documentation for `weco`, a CLI for using Weco AI's code optimizer."
 readme = "README.md"
-version = "0.3.23"
+version = "0.3.24"
 license = { file = "LICENSE" }
 requires-python = ">=3.9"
 dependencies = [

tests/test_byok.py

@@ -31,7 +31,7 @@ def base_params(self, mock_console):
             "search_policy_config": {"num_drafts": 2},
         }
 
-    @patch("weco.api.requests.post")
+    @patch("weco.core.api.requests.Session.post")
     def test_api_keys_included_in_request(self, mock_post, base_params):
         """Test that api_keys are included in the request JSON when provided."""
         mock_response = MagicMock()
@@ -54,7 +54,7 @@ def test_api_keys_included_in_request(self, mock_post, base_params):
         assert "api_keys" in request_json
         assert request_json["api_keys"] == {"openai": "sk-test-key", "anthropic": "sk-ant-test"}
 
-    @patch("weco.api.requests.post")
+    @patch("weco.core.api.requests.Session.post")
     def test_api_keys_not_included_when_none(self, mock_post, base_params):
         """Test that api_keys field is not included when api_keys is None."""
         mock_response = MagicMock()
@@ -75,7 +75,7 @@ def test_api_keys_not_included_when_none(self, mock_post, base_params):
         request_json = call_kwargs.kwargs["json"]
         assert "api_keys" not in request_json
 
-    @patch("weco.api.requests.post")
+    @patch("weco.core.api.requests.Session.post")
     def test_api_keys_not_included_when_empty_dict(self, mock_post, base_params):
         """Test that api_keys field is not included when api_keys is an empty dict."""
         mock_response = MagicMock()
@@ -105,7 +105,7 @@ def mock_console(self):
         """Create a mock console for testing."""
         return MagicMock(spec=Console)
 
-    @patch("weco.api.requests.post")
+    @patch("weco.core.api.requests.Session.post")
     def test_api_keys_included_in_suggest_request(self, mock_post, mock_console):
         """Test that api_keys are included in the suggest request JSON when provided."""
         mock_response = MagicMock()
@@ -135,7 +135,7 @@ def test_api_keys_included_in_suggest_request(self, mock_post, mock_console):
         assert "api_keys" in request_json
         assert request_json["api_keys"] == {"openai": "sk-test-key"}
 
-    @patch("weco.api.requests.post")
+    @patch("weco.core.api.requests.Session.post")
     def test_api_keys_not_included_in_suggest_when_none(self, mock_post, mock_console):
         """Test that api_keys field is not included in suggest request when api_keys is None."""
         mock_response = MagicMock()
@@ -163,7 +163,7 @@ def test_api_keys_not_included_in_suggest_when_none(self, mock_post, mock_consol
         request_json = call_kwargs.kwargs["json"]
         assert "api_keys" not in request_json
 
-    @patch("weco.api.requests.post")
+    @patch("weco.core.api.requests.Session.post")
     def test_api_keys_not_included_in_suggest_when_empty_dict(self, mock_post, mock_console):
         """Test that api_keys field is not included in suggest request when api_keys is None."""
         mock_response = MagicMock()