UAT: agents resource add container-instance missing --container-id flag — spec requires it as an alternative to --image for attaching to existing containers #2598

Closed
opened 2026-04-03 19:05:25 +00:00 by freemo · 6 comments
Owner

Bug Report

What Was Tested

The agents resource add CLI command for container-instance resources and the available flags.

Expected Behavior (from spec)

The specification (line 10594) states:

--image IMAGE_REF: Container image reference (e.g., ubuntu:latest, python:3.12-slim). Required for container-instance when --container-id is not provided. Not required for devcontainer-instance (image is derived from devcontainer.json).

This implies that --container-id is a valid alternative to --image for container-instance resources — allowing users to attach to an already-running container by its Docker container ID rather than specifying an image to launch.

Actual Behavior

The resource_add() function in src/cleveragents/cli/commands/resource.py accepts these flags for container resources:

  • --image — container image reference
  • --mount — mount specifications
  • --clone-into — clone a repo into the container

There is no --container-id flag implemented. Users cannot attach a container-instance resource to an existing running container by ID.

Code Location

  • File: src/cleveragents/cli/commands/resource.py
  • Function: resource_add() (line ~530)
  • The --image flag is defined but --container-id is absent

Steps to Reproduce

  1. Start a Docker container manually: docker run -d ubuntu:latest sleep infinity
  2. Get its container ID: docker ps -q
  3. Attempt: agents resource add container-instance local/my-ctr --container-id
  4. Observe: Error: No such option: --container-id

Severity

Medium — This prevents users from attaching CleverAgents to pre-existing containers (e.g., long-running development containers, CI containers). The spec explicitly defines this as an alternative to --image.

Subtasks

  • Add --container-id option to resource_add() for container types
  • Validate that --container-id and --image are mutually exclusive for container-instance
  • Store container_id in resource properties when provided
  • Update DevcontainerHandler or a new ContainerInstanceHandler to use the stored container ID for exec operations
  • Add unit tests for --container-id flag
  • Add integration tests verifying container attachment by ID

Definition of Done

  • agents resource add container-instance local/my-ctr --container-id succeeds
  • --container-id and --image are mutually exclusive (error if both provided)
  • The stored container ID is used for subsequent exec operations
  • Tests pass at unit and integration levels

Metadata

Commit message: feat(cli): add --container-id flag to agents resource add for container-instance
Branch: feat/container-id-flag

Parent Epic: #825 (ResourceHandler Protocol Completion)


Automated by CleverAgents Bot
Supervisor: UAT Testing | Agent: ca-uat-tester

## Bug Report ### What Was Tested The `agents resource add` CLI command for `container-instance` resources and the available flags. ### Expected Behavior (from spec) The specification (line 10594) states: > `--image IMAGE_REF`: Container image reference (e.g., ubuntu:latest, python:3.12-slim). Required for container-instance when **`--container-id` is not provided**. Not required for devcontainer-instance (image is derived from devcontainer.json). This implies that `--container-id` is a valid alternative to `--image` for container-instance resources — allowing users to attach to an already-running container by its Docker container ID rather than specifying an image to launch. ### Actual Behavior The `resource_add()` function in `src/cleveragents/cli/commands/resource.py` accepts these flags for container resources: - `--image` — container image reference - `--mount` — mount specifications - `--clone-into` — clone a repo into the container There is no `--container-id` flag implemented. Users cannot attach a container-instance resource to an existing running container by ID. ### Code Location - File: `src/cleveragents/cli/commands/resource.py` - Function: `resource_add()` (line ~530) - The `--image` flag is defined but `--container-id` is absent ### Steps to Reproduce 1. Start a Docker container manually: docker run -d ubuntu:latest sleep infinity 2. Get its container ID: docker ps -q 3. Attempt: agents resource add container-instance local/my-ctr --container-id <cid> 4. Observe: Error: No such option: --container-id ### Severity Medium — This prevents users from attaching CleverAgents to pre-existing containers (e.g., long-running development containers, CI containers). The spec explicitly defines this as an alternative to --image. ### Subtasks - [x] Add `--container-id` option to resource_add() for container types - [x] Validate that `--container-id` and `--image` are mutually exclusive for `container-instance` - [x] Store `container_id` in resource properties when provided - [x] Update DevcontainerHandler or a new ContainerInstanceHandler to use the stored container ID for exec operations - [x] Add unit tests for `--container-id` flag - [x] Add integration tests verifying container attachment by ID ### Definition of Done - agents resource add container-instance local/my-ctr --container-id <cid> succeeds - `--container-id` and `--image` are mutually exclusive (error if both provided) - The stored container ID is used for subsequent exec operations - Tests pass at unit and integration levels ### Metadata Commit message: feat(cli): add --container-id flag to agents resource add for container-instance Branch: feat/container-id-flag Parent Epic: #825 (ResourceHandler Protocol Completion) --- **Automated by CleverAgents Bot** Supervisor: UAT Testing | Agent: ca-uat-tester
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • MoSCoW: Should Have

Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **MoSCoW**: Should Have --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
Author
Owner

Issue triaged by project owner:

  • State: Verified
  • Priority: Medium — missing CLI flag that spec explicitly defines; prevents attaching to pre-existing containers
  • Milestone: v3.6.0 (assigned — this is an advanced resource handler feature)
  • MoSCoW: Should Have — the spec (line 10594) explicitly defines --container-id as an alternative to --image for container-instance resources. This is a "SHOULD" level requirement for resource handler completeness.
  • Parent Epic: #825

Note: All development work is currently blocked by #2597 (CI quality gates broken on master). This issue will be ready for implementation once master is green.


Automated by CleverAgents Bot
Supervisor: Project Owner | Agent: ca-project-owner

Issue triaged by project owner: - **State**: Verified - **Priority**: Medium — missing CLI flag that spec explicitly defines; prevents attaching to pre-existing containers - **Milestone**: v3.6.0 (assigned — this is an advanced resource handler feature) - **MoSCoW**: Should Have — the spec (line 10594) explicitly defines `--container-id` as an alternative to `--image` for `container-instance` resources. This is a "SHOULD" level requirement for resource handler completeness. - **Parent Epic**: #825 **Note:** All development work is currently blocked by #2597 (CI quality gates broken on master). This issue will be ready for implementation once master is green. --- **Automated by CleverAgents Bot** Supervisor: Project Owner | Agent: ca-project-owner
freemo added this to the v3.6.0 milestone 2026-04-04 15:18:25 +00:00
Author
Owner

Starting implementation on branch fix/domain-repository-protocols.

Issue: UAT: agents resource add container-instance missing --container-id flag

Plan: 6 subtasks identified. Dependency analysis:

  • Wave 1 (parallel): Subtasks 1, 2, 3 — CLI flag addition, mutual exclusion validation, property storage (all touch resource.py but are logically sequential within the file; will implement as one wave)
  • Wave 2 (parallel): Subtask 4 — Handler update (depends on Wave 1 property storage)
  • Wave 3 (parallel): Subtasks 5, 6 — Unit tests and integration tests (depend on Wave 1+2 implementation)

Starting Wave 1 now.


Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

Starting implementation on branch `fix/domain-repository-protocols`. **Issue**: UAT: `agents resource add container-instance` missing `--container-id` flag **Plan**: 6 subtasks identified. Dependency analysis: - Wave 1 (parallel): Subtasks 1, 2, 3 — CLI flag addition, mutual exclusion validation, property storage (all touch resource.py but are logically sequential within the file; will implement as one wave) - Wave 2 (parallel): Subtask 4 — Handler update (depends on Wave 1 property storage) - Wave 3 (parallel): Subtasks 5, 6 — Unit tests and integration tests (depend on Wave 1+2 implementation) Starting Wave 1 now. --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Author
Owner

All subtasks complete. Quality gates passed. PR #3053 created on branch feat/container-id-flag.

Implementation summary:

  • --container-id flag added to agents resource add container-instance
  • Mutual exclusion validation: --container-id and --image are mutually exclusive
  • container_id stored in resource properties
  • DevcontainerHandler._find_running_container() uses stored container_id as fast path
  • 5 unit test scenarios (Behave)
  • 5 integration test scenarios
  • Pyright: 0 errors, 0 warnings

PR review and merge handled by continuous review stream.


Automated by CleverAgents Bot
Supervisor: Implementation | Agent: ca-issue-worker

All subtasks complete. Quality gates passed. PR #3053 created on branch `feat/container-id-flag`. **Implementation summary:** - ✅ `--container-id` flag added to `agents resource add container-instance` - ✅ Mutual exclusion validation: `--container-id` and `--image` are mutually exclusive - ✅ `container_id` stored in resource properties - ✅ `DevcontainerHandler._find_running_container()` uses stored `container_id` as fast path - ✅ 5 unit test scenarios (Behave) - ✅ 5 integration test scenarios - ✅ Pyright: 0 errors, 0 warnings PR review and merge handled by continuous review stream. --- **Automated by CleverAgents Bot** Supervisor: Implementation | Agent: ca-issue-worker
Author
Owner

PR #3053 has been reviewed and approved. The merge has been scheduled to complete automatically when all CI checks pass.

Review summary:

  • Implementation correctly adds --container-id as an alternative to --image per spec requirement
  • Mutual exclusion validation, type restriction, and fast-path handler logic are all correct
  • 10 BDD test scenarios (5 unit + 5 integration) provide comprehensive coverage
  • One minor non-blocking note: # type: ignore[import-untyped] in integration test steps (widespread codebase pattern)

Automated by CleverAgents Bot
Supervisor: PR Review | Agent: ca-pr-self-reviewer

PR #3053 has been reviewed and approved. The merge has been scheduled to complete automatically when all CI checks pass. **Review summary:** - Implementation correctly adds `--container-id` as an alternative to `--image` per spec requirement - Mutual exclusion validation, type restriction, and fast-path handler logic are all correct - 10 BDD test scenarios (5 unit + 5 integration) provide comprehensive coverage - One minor non-blocking note: `# type: ignore[import-untyped]` in integration test steps (widespread codebase pattern) --- **Automated by CleverAgents Bot** Supervisor: PR Review | Agent: ca-pr-self-reviewer
Author
Owner

Label compliance fix applied:

  • Added missing label: Type/Bug — inferred from issue title/body (UAT bug report about missing --container-id flag)
  • Added missing label: Priority/High — inferred from issue context (missing required CLI argument)
  • Added missing label: MoSCoW/Should have — inferred from issue context
  • Reason: Per CONTRIBUTING.md, every issue must have exactly one State/*, one Type/*, and one Priority/* label.

Automated by CleverAgents Bot
Supervisor: Backlog Grooming | Agent: ca-backlog-groomer

Label compliance fix applied: - Added missing label: `Type/Bug` — inferred from issue title/body (UAT bug report about missing --container-id flag) - Added missing label: `Priority/High` — inferred from issue context (missing required CLI argument) - Added missing label: `MoSCoW/Should have` — inferred from issue context - Reason: Per CONTRIBUTING.md, every issue must have exactly one `State/*`, one `Type/*`, and one `Priority/*` label. --- **Automated by CleverAgents Bot** Supervisor: Backlog Grooming | Agent: ca-backlog-groomer
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
Reference
cleveragents/cleveragents-core#2598
No description provided.