From b4ee51c5ad74293f7dec2717dfdab0bc41fb7194 Mon Sep 17 00:00:00 2001 From: Jeffrey Phillips Freeman Date: Sun, 5 Apr 2026 06:36:23 +0000 Subject: [PATCH] docs: update CHANGELOG, MCP API, plan CLI, and CI/CD docs for recent merged PRs Document changes from PRs merged 2026-04-03 through 2026-04-05: - CHANGELOG: add entries for CI artifact capture (#2782), ASV provider benchmarks (#3022), CI quality gate restoration (#2629), plan list --namespace option (#2616), and MCP 1.4.0 error extraction fix (#2600) - docs/api/mcp.md: document MCP 1.4.0 error extraction from content[0].text in MCPToolAdapter.invoke() with protocol note and usage example - docs/reference/plan_cli.md: add --namespace/-n option to agents plan list options table, update Filters panel description, add usage examples - docs/development/ci-cd.md: document CI artifact capture for all 8 nox jobs, artifact naming convention, retention policy, and agent integration --- CHANGELOG.md | 29 +++++++++++++++++++++++++++++ docs/api/mcp.md | 16 +++++++++++++++- docs/development/ci-cd.md | 26 ++++++++++++++++++++++++++ docs/reference/plan_cli.md | 19 +++++++++++++++++-- 4 files changed, 87 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b8d8162a..102eb4c7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -93,8 +93,37 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This eliminates redundant Alembic migrations across all test suites and reduces total test suite wall-clock time. (#2334) +- **CI — Nox output captured as Forgejo artifacts**: All 8 nox-running CI + jobs in `.forgejo/workflows/ci.yml` now capture their stdout+stderr as + named Forgejo artifacts. Agent definition files are updated to consume + these artifacts, enabling automated agents to read CI failure output + without cloning the repository. (#2782) + +- **Tests — ASV performance benchmark suite for providers module**: Five new + ASV benchmark files under `benchmarks/` cover all performance-sensitive + paths in the `providers` module that previously lacked benchmark coverage, + closing the gap identified in issue #280. (#3022) + ### Fixed +- **CI — All quality gates restored to passing on master**: Lint, typecheck, + security scan, unit tests, integration tests, and coverage gates all pass + on master. No gates were suppressed or bypassed — all fixes are to actual + source code and test expectations. (#2629) + +- **CLI — `agents plan list` now accepts `--namespace`/`-n` option**: The + `plan list` command gains a `--namespace`/`-n` filter flag, bringing it + into alignment with the specification and achieving parity with + `agents action list`. The active namespace filter is shown in the + **Filters** panel. (#2616) + +- **MCP — Error message extracted from `content[0].text` per MCP 1.4.0 + protocol**: `MCPToolAdapter.invoke()` previously returned `"unknown error"` + for all real MCP 1.4.0 server errors because it was reading the wrong + field. The adapter now correctly extracts the error text from + `result["content"][0]["text"]` when `result["isError"]` is true, surfacing + the actual server error message to callers. (#2600) + - Fixed session leak in all `AutomationProfileRepository` public methods (`get_by_name()`, `list_all()`, `upsert()`, and `delete()`): added `finally: if self._auto_commit: session.close()` blocks matching the diff --git a/docs/api/mcp.md b/docs/api/mcp.md index ec333db8..7990f263 100644 --- a/docs/api/mcp.md +++ b/docs/api/mcp.md @@ -66,7 +66,21 @@ await adapter.disconnect() | `disconnect()` | Clean shutdown | | `discover_tools(filter)` | Enumerate tools from the server | | `invoke(name, arguments)` | Call a tool with input validation | -| `register_tools(registry)` | Bulk-register discovered tools | +| `register_tools(registry, namespace, filter)` | Discover and bulk-register tools with namespace prefix | + +### Error Handling in `invoke()` + +> **Protocol note (MCP 1.4.0+):** When a server returns `isError: true`, +> the error message is embedded in `content[0].text` — not in a top-level +> `error` field. `MCPToolAdapter.invoke()` reads `content[0].text` and +> surfaces it in `MCPToolResult.error`. Prior to this fix (PR #2600), +> all server errors were silently replaced with `"unknown error"`. + +```python +result = await adapter.invoke("bash", {"command": "invalid-cmd"}) +if not result.success: + print(result.error) # e.g. "bash: invalid-cmd: command not found" +``` --- diff --git a/docs/development/ci-cd.md b/docs/development/ci-cd.md index 6f6bf748..94cf43eb 100644 --- a/docs/development/ci-cd.md +++ b/docs/development/ci-cd.md @@ -171,6 +171,32 @@ tools directly. This ensures that the CI environment matches local development exactly. Each job runs `pip install uv nox` and then delegates to the appropriate nox session. +### CI Artifact Capture + +All 8 nox-running CI jobs capture their full stdout+stderr output as named +Forgejo artifacts (PR #2782). This enables automated agents and developers to +inspect CI failure output without cloning the repository or re-running jobs +locally. + +**Artifact naming convention:** `-output` (e.g., `lint-output`, +`typecheck-output`, `unit_tests-output`). + +**Retention:** Artifacts are retained for 30 days by default. + +**Agent integration:** Agent definition files reference these artifacts so +that automated agents (e.g., `ca-test-infra-improver`) can read CI failure +output via the Forgejo API and propose targeted fixes without needing +repository access. + +To download a CI artifact manually: + +```bash +# Via Forgejo API +curl -H "Authorization: token " \ + "https://git.cleverthis.com/api/v1/repos/cleveragents/cleveragents-core/actions/artifacts" \ + | jq '.[] | select(.name == "typecheck-output")' +``` + ### Quality Gates Summary All gates must pass for a PR to be mergeable: diff --git a/docs/reference/plan_cli.md b/docs/reference/plan_cli.md index 17c7e5d8..051709f2 100644 --- a/docs/reference/plan_cli.md +++ b/docs/reference/plan_cli.md @@ -109,6 +109,7 @@ agents plan list [REGEX] [OPTIONS] | Flag | Description | |-------------------------|--------------------------------------------------| +| `--namespace`, `-n` | Filter by plan namespace | | `--phase` | Filter by phase (strategize, execute, apply) | | `--state` | Filter by processing state | | `--processing-state` | Alias for `--state` | @@ -131,10 +132,24 @@ The `rich` format renders a **Plans** table with columns: After the table: -- **Filters** panel — shown only when at least one filter (`--phase`, `--state`, - `--project`, `--action`) is active. Lists the active filter values. +- **Filters** panel — shown only when at least one filter (`--namespace`, + `--phase`, `--state`, `--project`, `--action`) is active. Lists the + active filter values. - **Summary** panel — total plans, processing count, completed count, and errored count. +### Examples + +```bash +# Filter by namespace +agents plan list --namespace myteam + +# Combine namespace and phase filters +agents plan list --namespace myteam --phase execute + +# JSON output with namespace filter +agents plan list -n myteam --format json +``` + Followed by a `✓ OK N plan(s) listed` success message. ## `agents plan execute`