agents actor list should not cause an update of the database. #797

Closed
opened 2026-03-12 23:49:24 +00:00 by brent.edwards · 6 comments
Member

Given

From a new checkout of the CleverAgents code, type the following setup:

cd ~
mkdir data
uv venv
source .venv/bin/activate
uv pip install -e /app
agents init --yes

When

agents actor list

Expected

To only list the migrations, something like:

(devuser) ➜  ~ agents actor list
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                          ┃ Provider   ┃ Model                              ┃ Default ┃ Built-in ┃ Unsafe ┃ Updated                    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ anthropic/claude-sonnet-4-20250514            │ Anthropic  │ claude-sonnet-4-20250514           │         │    ✓     │   no   │ 2026-03-12 23:41:05.101923 │
│ gemini/gemini-2.0-flash                       │ Gemini     │ gemini-2.0-flash                   │         │    ✓     │   no   │ 2026-03-12 23:41:05.110322 │
│ google/gemini-2.0-flash                       │ Google     │ gemini-2.0-flash                   │         │    ✓     │   no   │ 2026-03-12 23:41:05.106308 │
│ openai/gpt-4o                                 │ Openai     │ gpt-4o                             │    ✓    │    ✓     │   no   │ 2026-03-12 23:41:05.125662 │
│ openrouter/anthropic-claude-sonnet-4-20250514 │ Openrouter │ anthropic/claude-sonnet-4-20250514 │         │    ✓     │   no   │ 2026-03-12 23:41:05.115784 │
└───────────────────────────────────────────────┴────────────┴────────────────────────────────────┴─────────┴──────────┴────────┴────────────────────────────┘

Actual

(devuser) ➜  ~ agents actor list
Pending database migrations detected (latest: m6_004_resource_type_inherits). Back up your .cleveragents directory before applying.

Apply migrations now? It's recommended to back up the .cleveragents directory first. [y/N]: y
INFO  [alembic.runtime.migration] Context impl SQLiteImpl.
INFO  [alembic.runtime.migration] Will assume non-transactional DDL.
                                                                       Actors (5 total)                                                                       
┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Name                                          ┃ Provider   ┃ Model                              ┃ Default ┃ Built-in ┃ Unsafe ┃ Updated                    ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ anthropic/claude-sonnet-4-20250514            │ Anthropic  │ claude-sonnet-4-20250514           │         │    ✓     │   no   │ 2026-03-12 23:41:05.101923 │
│ gemini/gemini-2.0-flash                       │ Gemini     │ gemini-2.0-flash                   │         │    ✓     │   no   │ 2026-03-12 23:41:05.110322 │
│ google/gemini-2.0-flash                       │ Google     │ gemini-2.0-flash                   │         │    ✓     │   no   │ 2026-03-12 23:41:05.106308 │
│ openai/gpt-4o                                 │ Openai     │ gpt-4o                             │    ✓    │    ✓     │   no   │ 2026-03-12 23:41:05.125662 │
│ openrouter/anthropic-claude-sonnet-4-20250514 │ Openrouter │ anthropic/claude-sonnet-4-20250514 │         │    ✓     │   no   │ 2026-03-12 23:41:05.115784 │
└───────────────────────────────────────────────┴────────────┴────────────────────────────────────┴─────────┴──────────┴────────┴────────────────────────────┘

Notice the addition of the "Pending database migrations detected" in the output.

# Given From a new checkout of the CleverAgents code, type the following setup: ``` cd ~ mkdir data uv venv source .venv/bin/activate uv pip install -e /app agents init --yes ``` # When ``` agents actor list ``` # Expected To only list the migrations, something like: ``` (devuser) ➜ ~ agents actor list ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Name ┃ Provider ┃ Model ┃ Default ┃ Built-in ┃ Unsafe ┃ Updated ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ anthropic/claude-sonnet-4-20250514 │ Anthropic │ claude-sonnet-4-20250514 │ │ ✓ │ no │ 2026-03-12 23:41:05.101923 │ │ gemini/gemini-2.0-flash │ Gemini │ gemini-2.0-flash │ │ ✓ │ no │ 2026-03-12 23:41:05.110322 │ │ google/gemini-2.0-flash │ Google │ gemini-2.0-flash │ │ ✓ │ no │ 2026-03-12 23:41:05.106308 │ │ openai/gpt-4o │ Openai │ gpt-4o │ ✓ │ ✓ │ no │ 2026-03-12 23:41:05.125662 │ │ openrouter/anthropic-claude-sonnet-4-20250514 │ Openrouter │ anthropic/claude-sonnet-4-20250514 │ │ ✓ │ no │ 2026-03-12 23:41:05.115784 │ └───────────────────────────────────────────────┴────────────┴────────────────────────────────────┴─────────┴──────────┴────────┴────────────────────────────┘ ``` # Actual ``` (devuser) ➜ ~ agents actor list Pending database migrations detected (latest: m6_004_resource_type_inherits). Back up your .cleveragents directory before applying. Apply migrations now? It's recommended to back up the .cleveragents directory first. [y/N]: y INFO [alembic.runtime.migration] Context impl SQLiteImpl. INFO [alembic.runtime.migration] Will assume non-transactional DDL. Actors (5 total) ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Name ┃ Provider ┃ Model ┃ Default ┃ Built-in ┃ Unsafe ┃ Updated ┃ ┡━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ anthropic/claude-sonnet-4-20250514 │ Anthropic │ claude-sonnet-4-20250514 │ │ ✓ │ no │ 2026-03-12 23:41:05.101923 │ │ gemini/gemini-2.0-flash │ Gemini │ gemini-2.0-flash │ │ ✓ │ no │ 2026-03-12 23:41:05.110322 │ │ google/gemini-2.0-flash │ Google │ gemini-2.0-flash │ │ ✓ │ no │ 2026-03-12 23:41:05.106308 │ │ openai/gpt-4o │ Openai │ gpt-4o │ ✓ │ ✓ │ no │ 2026-03-12 23:41:05.125662 │ │ openrouter/anthropic-claude-sonnet-4-20250514 │ Openrouter │ anthropic/claude-sonnet-4-20250514 │ │ ✓ │ no │ 2026-03-12 23:41:05.115784 │ └───────────────────────────────────────────────┴────────────┴────────────────────────────────────┴─────────┴──────────┴────────┴────────────────────────────┘ ``` Notice the addition of the "Pending database migrations detected" in the output.
freemo added this to the v3.2.0 milestone 2026-03-13 21:12:12 +00:00
Owner

Dependency (TDD workflow): This bug fix is blocked by TDD issue #841. Per CONTRIBUTING.md Bug Fix Workflow, the TDD test capturing the bug must be written and merged first (@tdd_expected_fail), then the fix PR removes the tag.

Blocked by: #841

**Dependency (TDD workflow):** This bug fix is blocked by TDD issue #841. Per `CONTRIBUTING.md` Bug Fix Workflow, the TDD test capturing the bug must be written and merged first (`@tdd_expected_fail`), then the fix PR removes the tag. **Blocked by:** #841
Owner

PM Triage — Day 34

State: Upgraded from State/Unverified to State/Verified. The bug is clearly reproducible per the report.

Priority exception: Per PM decision, this bug is kept at Priority/Low + MoSCoW/Could Have instead of the mandatory Priority/Critical for bugs. Justification: the migration prompt is cosmetic — it does not block functionality, cause data loss, or affect test suites. The actor list command still works correctly after acknowledging the prompt. This is a UX polish issue, not a correctness issue.

TDD counterpart: #841 (assigned to @aditya, State/Verified).

Assignee: @hurui200320 (Rui) — confirmed.

Note: Removed the repo-level bug label — the org-level Type/Bug label is the correct label per CONTRIBUTING.md.


PM triage comment — Day 34

## PM Triage — Day 34 **State**: Upgraded from `State/Unverified` to `State/Verified`. The bug is clearly reproducible per the report. **Priority exception**: Per PM decision, this bug is kept at **Priority/Low + MoSCoW/Could Have** instead of the mandatory Priority/Critical for bugs. Justification: the migration prompt is cosmetic — it does not block functionality, cause data loss, or affect test suites. The `actor list` command still works correctly after acknowledging the prompt. This is a UX polish issue, not a correctness issue. **TDD counterpart**: #841 (assigned to @aditya, State/Verified). **Assignee**: @hurui200320 (Rui) — confirmed. **Note**: Removed the repo-level `bug` label — the org-level `Type/Bug` label is the correct label per CONTRIBUTING.md. --- *PM triage comment — Day 34*
Owner

Priority exception documented.

Per project policy, all Type/Bug issues should carry Priority/Critical. The PM has justified keeping this at Priority/Low because:

  1. The bug is cosmetic — agents actor list triggers an unnecessary database migration prompt but does not cause data loss or functional failure.
  2. A trivial workaround exists (the user can dismiss the prompt).
  3. The bug does not block any M3 acceptance criteria.

Decision: This exception is accepted with the following conditions:

  • The bug remains MoSCoW/Could have and Priority/Low in recognition of its cosmetic nature.
  • It must still follow the TDD workflow (TDD counterpart #841 exists).
  • If the bug worsens or affects functional behavior in the future, it will be immediately escalated to Critical.
  • This exception is formally recorded for audit purposes.
**Priority exception documented.** Per project policy, all `Type/Bug` issues should carry `Priority/Critical`. The PM has justified keeping this at `Priority/Low` because: 1. The bug is cosmetic — `agents actor list` triggers an unnecessary database migration prompt but does not cause data loss or functional failure. 2. A trivial workaround exists (the user can dismiss the prompt). 3. The bug does not block any M3 acceptance criteria. **Decision:** This exception is accepted with the following conditions: - The bug remains `MoSCoW/Could have` and `Priority/Low` in recognition of its cosmetic nature. - It must still follow the TDD workflow (TDD counterpart #841 exists). - If the bug worsens or affects functional behavior in the future, it will be immediately escalated to Critical. - This exception is formally recorded for audit purposes.
Owner

Priority escalated from Low to Critical.

Per CONTRIBUTING.md bug priority policy, all Type/Bug issues must have Priority/Critical and MoSCoW/Must Have. Bug issues represent broken existing functionality and are always top priority — they take precedence over feature work and cannot be deprioritized without extraordinary justification.

Labels updated: Priority/Critical, MoSCoW/Must Have added. The previous Priority/Low and MoSCoW/Could have labels should be removed if the label system does not auto-replace within the same scope.

This bug has TDD counterpart #841 which is still open. Once #841's TDD PR is merged, the bugfix branch should be created from master immediately.

**Priority escalated from Low to Critical.** Per `CONTRIBUTING.md` bug priority policy, all `Type/Bug` issues must have `Priority/Critical` and `MoSCoW/Must Have`. Bug issues represent broken existing functionality and are always top priority — they take precedence over feature work and cannot be deprioritized without extraordinary justification. Labels updated: `Priority/Critical`, `MoSCoW/Must Have` added. The previous `Priority/Low` and `MoSCoW/Could have` labels should be removed if the label system does not auto-replace within the same scope. This bug has TDD counterpart #841 which is still open. Once #841's TDD PR is merged, the bugfix branch should be created from `master` immediately.
Author
Member

Implementation Notes — Bug Fix

Root Cause

ActorRegistry.list_actors() and ActorRegistry.list() both unconditionally called self.ensure_built_in_actors() before delegating to self._actor_service.list_actors(). The ensure_built_in_actors() method iterates all configured providers and calls _actor_service.upsert_actor() for each — a database WRITE operation. It may also call _actor_service.set_default_actor() if no default exists — another WRITE. This means every read-only agents actor list command triggered database writes and could prompt for migrations.

Fix Applied

Removed the self.ensure_built_in_actors() call from:

  • ActorRegistry.list() (src/cleveragents/actor/registry.py)
  • ActorRegistry.list_actors() (src/cleveragents/actor/registry.py)

Both methods now delegate directly to the service layer without triggering writes. Write-heavy methods (add, upsert_actor, get, get_actor, remove, remove_actor, set_default_actor, get_default_actor) still call ensure_built_in_actors() as before.

TDD Tests

Per the Bug Fix Workflow (CONTRIBUTING.md), the @tdd_expected_fail tag was removed from the TDD tests created in #841:

  • features/tdd_actor_list_no_db_update.feature — 2 Behave scenarios (now @tdd_bug @tdd_bug_797 only)
  • robot/tdd_actor_list_no_db_update.robot — 2 Robot Framework tests (now tdd_bug tdd_bug_797 only)

Test Adjustments

Three existing test suites relied on the old (buggy) behavior where list_actors() called ensure_built_in_actors():

  1. consolidated_actor.feature — Scenario "Registry list_actors delegates to actor service after ensuring built-ins" updated to explicitly call ensure_built_in_actors() before list_actors().
  2. tdd_actor_list_validation (bug #592) — Behave steps and Robot helper updated to call ensure_built_in_actors() explicitly before CLI invocation, since the name sanitization tests need built-in actors to exist.
  3. actor_list_empty (bug #592) — Same pattern: ensure_built_in_actors() called explicitly before CLI invocation; mock service updated to use captured actors pattern.

Quality Gates

Gate Result
nox -e lint Pass
nox -e typecheck Pass (0 errors)
nox -e unit_tests Pass (468 features, 12367 scenarios, 0 failures)
nox -e integration_tests ⚠️ 6 pre-existing failures (timeouts/OOM on container_resolve_crash, m3_e2e, resource_cli)
nox -e coverage_report 98% (>= 97% threshold)

Branch: bugfix/m3-actor-list-no-db-update

## Implementation Notes — Bug Fix ### Root Cause `ActorRegistry.list_actors()` and `ActorRegistry.list()` both unconditionally called `self.ensure_built_in_actors()` before delegating to `self._actor_service.list_actors()`. The `ensure_built_in_actors()` method iterates all configured providers and calls `_actor_service.upsert_actor()` for each — a database WRITE operation. It may also call `_actor_service.set_default_actor()` if no default exists — another WRITE. This means every read-only `agents actor list` command triggered database writes and could prompt for migrations. ### Fix Applied Removed the `self.ensure_built_in_actors()` call from: - `ActorRegistry.list()` (`src/cleveragents/actor/registry.py`) - `ActorRegistry.list_actors()` (`src/cleveragents/actor/registry.py`) Both methods now delegate directly to the service layer without triggering writes. Write-heavy methods (`add`, `upsert_actor`, `get`, `get_actor`, `remove`, `remove_actor`, `set_default_actor`, `get_default_actor`) still call `ensure_built_in_actors()` as before. ### TDD Tests Per the Bug Fix Workflow (CONTRIBUTING.md), the `@tdd_expected_fail` tag was removed from the TDD tests created in #841: - `features/tdd_actor_list_no_db_update.feature` — 2 Behave scenarios (now `@tdd_bug @tdd_bug_797` only) - `robot/tdd_actor_list_no_db_update.robot` — 2 Robot Framework tests (now `tdd_bug tdd_bug_797` only) ### Test Adjustments Three existing test suites relied on the old (buggy) behavior where `list_actors()` called `ensure_built_in_actors()`: 1. **`consolidated_actor.feature`** — Scenario "Registry list_actors delegates to actor service after ensuring built-ins" updated to explicitly call `ensure_built_in_actors()` before `list_actors()`. 2. **`tdd_actor_list_validation` (bug #592)** — Behave steps and Robot helper updated to call `ensure_built_in_actors()` explicitly before CLI invocation, since the name sanitization tests need built-in actors to exist. 3. **`actor_list_empty` (bug #592)** — Same pattern: `ensure_built_in_actors()` called explicitly before CLI invocation; mock service updated to use captured actors pattern. ### Quality Gates | Gate | Result | |------|--------| | `nox -e lint` | ✅ Pass | | `nox -e typecheck` | ✅ Pass (0 errors) | | `nox -e unit_tests` | ✅ Pass (468 features, 12367 scenarios, 0 failures) | | `nox -e integration_tests` | ⚠️ 6 pre-existing failures (timeouts/OOM on container_resolve_crash, m3_e2e, resource_cli) | | `nox -e coverage_report` | ✅ 98% (>= 97% threshold) | Branch: `bugfix/m3-actor-list-no-db-update`
hurui200320 removed their assignment 2026-03-25 01:59:13 +00:00
Owner

Day 48 Planning Escalation — Stalled Bugfix Pipeline

@freemo — The TDD test for this bug was merged to master on Day 44 (PR #1148, by Aditya). As of today (Day 48), no bugfix/ branch exists on the remote for this issue. Per the TDD workflow, once the TDD PR is merged, the assignee must immediately create the fix branch from master and implement the fix.

This bug has been stalled for 4 days since the TDD test landed. The @tdd_expected_fail tag for @tdd_bug_797 remains in the codebase, confirming the bug is still unfixed.

Required action: Create bugfix/m3-actor-list-no-db-update from master and implement the fix. This is an M3 bug — it blocks M3 closure. Bugs are always top priority per CONTRIBUTING.md — this must take precedence over feature work.

The fix should:

  1. Prevent ActorRegistry.list_actors() from triggering ensure_built_in_actors() (which calls upsert_actor() and set_default_actor()) on every invocation.
  2. Remove the @tdd_expected_fail tag from the test, leaving @tdd_bug and @tdd_bug_797 as permanent regression guards.
  3. Pass CI with the test running normally.
**Day 48 Planning Escalation — Stalled Bugfix Pipeline** @freemo — The TDD test for this bug was merged to `master` on Day 44 (PR #1148, by Aditya). As of today (Day 48), **no `bugfix/` branch exists on the remote** for this issue. Per the TDD workflow, once the TDD PR is merged, the assignee must immediately create the fix branch from `master` and implement the fix. This bug has been stalled for **4 days** since the TDD test landed. The `@tdd_expected_fail` tag for `@tdd_bug_797` remains in the codebase, confirming the bug is still unfixed. **Required action**: Create `bugfix/m3-actor-list-no-db-update` from `master` and implement the fix. This is an M3 bug — it blocks M3 closure. Bugs are always top priority per CONTRIBUTING.md — this must take precedence over feature work. The fix should: 1. Prevent `ActorRegistry.list_actors()` from triggering `ensure_built_in_actors()` (which calls `upsert_actor()` and `set_default_actor()`) on every invocation. 2. Remove the `@tdd_expected_fail` tag from the test, leaving `@tdd_bug` and `@tdd_bug_797` as permanent regression guards. 3. Pass CI with the test running normally.
Sign in to join this conversation.
No milestone
No project
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Reference
cleveragents/cleveragents-core#797
No description provided.