Files

T

aditya 9273f0d8de fix(estimation): address Hamza code review findings F1–F17 on PR #528

Squash 7 estimation migrations (m6_003, 992484befd85, m6_005, m6_006,
m6_007, m6_008, m7_002) into a single clean m6_003_estimation_schema
with linear dependency on m4_003_plan_env_columns. Rename column
estimation_skipped_json to estimation_skipped for naming consistency.

Domain model hardening: replace deprecated FieldValidationInfo with
ValidationInfo, change historical_basis from list[str] to tuple[str,...]
to prevent mutation on frozen model, add max_length=10_000 to rationale.

Service improvements: remove unnecessary ThreadPoolExecutor wrapping,
add EstimationActorProtocol for pluggable actor dispatch, log unexpected
exceptions at error level, document EstimationService as stateless.

Deduplicate estimation serialization via static helpers on
LifecyclePlanModel used by both from_domain() and _update_plan_row().

Remove 6 out-of-scope coverage-boost files (container_73_lines,
plan_cli_print_coverage, resume_coverage) and revert 3 unrelated
benchmark import fixes.

Add Behave scenario for update_plan_overrides atomic field setting.

ISSUES CLOSED: #209

2026-03-19 15:07:05 +00:00

2.2 KiB

Raw Blame History

Estimation Reference

CleverAgents supports optional pre-execution estimation through the estimation_actor role. The actor produces a structured EstimationReport that is persisted on plans and shown in plan status output.

EstimationReport Schema

{
  "cost_range_usd_min": 0.5,
  "cost_range_usd_max": 2.0,
  "token_estimate_input": 1200,
  "token_estimate_output": 600,
  "expected_steps": 4,
  "expected_child_plans": 1,
  "rollback_risk": 0.25,
  "confidence": 0.75,
  "estimated_duration_minutes": 18.0,
  "rationale": "Derived from plan size and constraints",
  "historical_basis": [],
  "actor_used": "local/estimator",
  "generated_at": "2026-03-12T10:00:00Z"
}

Field Summary

cost_range_usd_min / cost_range_usd_max: Estimated USD cost band.
token_estimate_input / token_estimate_output: LLM token expectations.
expected_steps, expected_child_plans: Work-size projection.
rollback_risk: Rollback likelihood in [0.0, 1.0].
confidence: Model confidence in [0.0, 1.0].
estimated_duration_minutes: Duration estimate in minutes.
rationale: Human-readable explanation of estimate.
historical_basis: Optional prior plan IDs used as basis.
actor_used: Namespaced actor identifier (namespace/name).
generated_at: Timestamp of estimation generation.

Validation Rules

cost_range_usd_max >= cost_range_usd_min
rollback_risk and confidence are bounded to [0.0, 1.0]
all count/duration/token values are non-negative
actor_used (when present) must be namespaced

CLI Integration

Use --no-estimate to explicitly skip estimation:

agents plan use local/refactor my-project --no-estimate

When estimation is skipped, estimation_skipped is recorded with the reason.

Persistence

Estimation data is stored on v3_plans:

estimation_report: JSON-serialized EstimationReport
estimation_skipped: JSON-serialized EstimationSkipped

Runtime Behavior

Estimation runs during plan use:

create plan from action
invoke estimation actor if configured and not skipped
store either estimation_report or estimation_skipped
continue lifecycle (estimation is informational only)

2.2 KiB Raw Blame History