feat(tool): add tool lifecycle runtime #291

Closed
opened 2026-02-22 23:40:58 +00:00 by freemo · 0 comments
Owner

Metadata

  • Commit: feat(tool): add tool lifecycle runtime
  • Branch: feature/m2-tool-runtime

Subtasks

  • Implement ToolRuntime/ToolInstance interfaces with discover/activate/execute/deactivate hooks and lifecycle state tracking.
  • Add ToolExecutionContext with resolved resource bindings, sandbox paths, plan metadata, and cancellation token.
  • Add lifecycle cache with per-plan activation reuse and guaranteed deactivate on plan completion/cancel.
  • Enforce tool capability flags (read-only/writes/checkpointable) and read-only plan gating at runtime.
  • Validate tool inputs/outputs against JSON schema before/after execution; surface schema errors clearly.
  • Add tool execution tracing (start/end timestamps, duration, result size) for diagnostics.
  • Add cancellation propagation so long-running tools are interrupted on plan cancel.
  • Add docs/reference/tool_lifecycle.md describing hook ordering, capability enforcement, and failure handling.
  • Document schema validation behavior and error payload format for tool failures.
  • Tests (Behave): Add lifecycle scenarios for activate/execute/deactivate ordering and error propagation.
  • Tests (Robot): Add robot/tool_lifecycle.robot runtime smoke tests.
  • Tests (ASV): Add benchmarks/tool_lifecycle_bench.py for lifecycle overhead.
  • Run nox (all default sessions, including benchmark).
  • Verify coverage >=97% via nox -s coverage_report. If coverage is <97% then review the current unit test coverage report at build/coverage.xml and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun nox -s coverage_report to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%.

Section: ### Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead]
Status: Completed

## Metadata - **Commit**: `feat(tool): add tool lifecycle runtime` - **Branch**: `feature/m2-tool-runtime` ## Subtasks - [x] Implement `ToolRuntime`/`ToolInstance` interfaces with `discover/activate/execute/deactivate` hooks and lifecycle state tracking. - [x] Add `ToolExecutionContext` with resolved resource bindings, sandbox paths, plan metadata, and cancellation token. - [x] Add lifecycle cache with per-plan activation reuse and guaranteed `deactivate` on plan completion/cancel. - [x] Enforce tool capability flags (read-only/writes/checkpointable) and read-only plan gating at runtime. - [x] Validate tool inputs/outputs against JSON schema before/after execution; surface schema errors clearly. - [x] Add tool execution tracing (start/end timestamps, duration, result size) for diagnostics. - [x] Add cancellation propagation so long-running tools are interrupted on plan cancel. - [x] Add `docs/reference/tool_lifecycle.md` describing hook ordering, capability enforcement, and failure handling. - [x] Document schema validation behavior and error payload format for tool failures. - [x] Tests (Behave): Add lifecycle scenarios for activate/execute/deactivate ordering and error propagation. - [x] Tests (Robot): Add `robot/tool_lifecycle.robot` runtime smoke tests. - [x] Tests (ASV): Add `benchmarks/tool_lifecycle_bench.py` for lifecycle overhead. - [x] Run `nox` (all default sessions, including benchmark). - [x] Verify coverage >=97% via `nox -s coverage_report`. If coverage is <97% then review the current unit test coverage report at `build/coverage.xml` and use it to write new Behave based unit tests to improve code coverage. Specifically, write Behave style unit tests that are descriptively named and specifically improves coverage on whichever file has the most uncovered lines by writing tests that will target the uncovered lines in the report. Once that is done rerun `nox -s coverage_report` to verify all tests pass and coverage is above >=97%. Only mark this as complete once coverage is >=97%, if not repeat this task as many times as is needed until coverage reaches >=97%. **Section**: ### Section 5: Actors, Skills & Tool Execution [WORKSTREAM C - Aditya Lead] **Status**: Completed
freemo added this to the v3.1.0 milestone 2026-02-22 23:40:58 +00:00
freemo self-assigned this 2026-02-22 23:40:58 +00:00
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
#354 Epic: Actor & Skill Schema + CLI (C0)
cleveragents/cleveragents-core
Depends on
#65 feat(tool): add tool lifecycle runtime
cleveragents/cleveragents-core
Reference
cleveragents/cleveragents-core#291
No description provided.