feat(server)!: implement recursive control condition trees

[lan17]

corresponding docs update: agentcontrol/docs-agent-control#28

Summary

• replace flat control predicates with recursive condition trees across the shared models, engine, server, SDKs, and UI contracts
• normalize legacy flat stored controls during Alembic upgrade and add safe condition_trace metadata for composite evaluation
• regenerate the TypeScript SDK/API types for the new contract and keep rollout-time legacy read compatibility on the server/models

Scope

• User-facing/API changes:
  • ControlDefinition now uses a top-level condition tree instead of top-level selector / evaluator
  • controls now support nested and / or / not composition with a hard API depth limit of 6
  • /api/v1 route structure stays the same, but the canonical contract is a breaking change for SDK consumers that construct control payloads directly
  • the TypeScript SDK release should be marked breaking so npm publishes a new major for the condition-tree input contract
• Internal changes:
  • recursive engine evaluation with short-circuiting and metadata.condition_trace
  • clearer composite error traces (matched: null on error) and preserved raw diagnostics for internal observability while API responses stay sanitized
  • recursive server-side validation with nested field paths
  • Python SDK recursive leaf checks plus non-blocking server-version mismatch warnings
  • UI keeps the existing single-condition editor behavior for leaf conditions; composite trees are shown but preserved on save rather than fully edited in this PR
• Rollout compatibility notes:
  • server/models still canonicalize legacy flat control payloads (selector + evaluator) into condition during rollout
  • legacy flat rows in the database are normalized by Alembic revision 9f2f5a4e6c1b_normalize_legacy_control_conditions
  • the standalone migration script/Make target was removed; Alembic is the one authoritative migration path
• Out of scope:
  • full condition-tree editing in the current UI modal
  • runtime strict rejection of legacy flat control payloads
  • drag-and-drop tree editing

Risk and Rollout

• Risk level: high
• Rollback plan:
  • take a database backup before running alembic upgrade head
  • if rollout fails before the Alembic data migration runs, revert to the previous server/SDK major
  • if rollout fails after the Alembic data migration runs, restore the pre-migration database snapshot before rolling back the server major
• Migration behavior:
  • the Alembic normalization is SQL-only and runs once during upgrade
  • it fails hard if stored control rows are ambiguous/corrupted (mixed canonical+legacy fields, partial legacy fields, non-object JSON, etc.)
  • the migration is intentionally irreversible

Testing

• Added or updated automated tests
• Ran make check
• Manually verified behavior

make check passed, which covered:

• make models-test
• make server-test
• make engine-test
• make sdk-test
• make evaluators-test
• repo linting
• repo typechecking

Additional focused coverage added in this PR includes:

• direct model tests for recursive condition trees and legacy canonicalization
• engine tests for composite traversal, short-circuiting, traces, and composite error handling
• server validation/error-path tests for nested field paths and sanitized evaluator failures
• compatibility tests for legacy flat stored control payloads on read
• dedicated Alembic migration tests covering no-op, rewrite, invalid-row failure, atomic rollback, offline rejection, API post-migration shape, and multi-row rewrite
• UI tests for the current composite-editing limitation and JSON editor behavior

Notes:

• the full check run emitted a few existing third-party warnings (sqlglot[rs] deprecation, Strands resource/deprecation warnings), but the targets passed cleanly

Checklist

• Linked issue/spec: sc-57582, sc-58429
• Updated docs/examples for user-facing changes
• Included any required follow-up tasks

[codecov]

Codecov Report

❌ Patch coverage is 94.10569% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
models/src/agent_control_models/controls.py	91.85%	11 Missing ⚠️
engine/src/agent_control_engine/core.py	93.27%	8 Missing ⚠️
...ver/src/agent_control_server/endpoints/controls.py	91.66%	5 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py	92.00%	4 Missing ⚠️
...ent_control_server/services/control_definitions.py	96.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

flowchart TD
C["condition (root)"] --> A["and"]
C --> O["or"]
C --> N["not"]
A --> L1["leaf: selector + evaluator"]
A --> L2["leaf: selector + evaluator"]
O --> L3["leaf: selector + evaluator"]
O --> A2["and"]
A2 --> L4["leaf: selector + evaluator"]
A2 --> L5["leaf: selector + evaluator"]
N --> L6["leaf: selector + evaluator"]

Loading

[namrataghadi-galileo]

One suggestion from Observability perspective:

Current issue:
- primary_leaf() returns None for composite conditions, so evaluator_name and selector_path become null in observability events.
Suggested change:
- Don’t use primary_leaf() for observability identity.
- Derive a deterministic representative from all leaves (first leaf in traversal order).
- Keep full composite context in metadata.
Proposed behavior:
- evaluator_name = first leaf evaluator
- selector_path = first leaf selector path
- add metadata:
leaf_count
all_evaluators (ordered, deduped)
all_selector_paths (ordered, deduped)
optionally representative_* naming to avoid semantic confusion
Why:
- Prevents null observability dimensions for composite controls.
- Preserves backward compatibility for dashboards filtering by evaluator/selector.
- Still keeps full truth about all leaves in metadata.

[lan17]

Following up on the broader observability note: I aligned server and SDK event emission so composite conditions use a deterministic representative leaf for top-level selector_path / evaluator_name, while preserving the full composite context in metadata (primary_*, leaf_count, ordered/deduped evaluator and selector lists).

[galileo-automation]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[lan17]

corresponding docs update: agentcontrol/docs-agent-control#28

Summary

• replace flat control predicates with recursive condition trees across the shared models, engine, server, SDKs, and UI contracts
• normalize legacy flat stored controls during Alembic upgrade and add safe condition_trace metadata for composite evaluation
• regenerate the TypeScript SDK/API types for the new contract and keep rollout-time legacy read compatibility on the server/models

Scope

• User-facing/API changes:
  • ControlDefinition now uses a top-level condition tree instead of top-level selector / evaluator
  • controls now support nested and / or / not composition with a hard API depth limit of 6
  • /api/v1 route structure stays the same, but the canonical contract is a breaking change for SDK consumers that construct control payloads directly
  • the TypeScript SDK release should be marked breaking so npm publishes a new major for the condition-tree input contract
• Internal changes:
  • recursive engine evaluation with short-circuiting and metadata.condition_trace
  • clearer composite error traces (matched: null on error) and preserved raw diagnostics for internal observability while API responses stay sanitized
  • recursive server-side validation with nested field paths
  • Python SDK recursive leaf checks plus non-blocking server-version mismatch warnings
  • UI keeps the existing single-condition editor behavior for leaf conditions; composite trees are shown but preserved on save rather than fully edited in this PR
• Rollout compatibility notes:
  • server/models still canonicalize legacy flat control payloads (selector + evaluator) into condition during rollout
  • legacy flat rows in the database are normalized by Alembic revision 9f2f5a4e6c1b_normalize_legacy_control_conditions
  • the standalone migration script/Make target was removed; Alembic is the one authoritative migration path
• Out of scope:
  • full condition-tree editing in the current UI modal
  • runtime strict rejection of legacy flat control payloads
  • drag-and-drop tree editing

Risk and Rollout

• Risk level: high
• Rollback plan:
  • take a database backup before running alembic upgrade head
  • if rollout fails before the Alembic data migration runs, revert to the previous server/SDK major
  • if rollout fails after the Alembic data migration runs, restore the pre-migration database snapshot before rolling back the server major
• Migration behavior:
  • the Alembic normalization is SQL-only and runs once during upgrade
  • it fails hard if stored control rows are ambiguous/corrupted (mixed canonical+legacy fields, partial legacy fields, non-object JSON, etc.)
  • the migration is intentionally irreversible

Testing

• Added or updated automated tests
• Ran make check
• Manually verified behavior

make check passed, which covered:

• make models-test
• make server-test
• make engine-test
• make sdk-test
• make evaluators-test
• repo linting
• repo typechecking

Additional focused coverage added in this PR includes:

• direct model tests for recursive condition trees and legacy canonicalization
• engine tests for composite traversal, short-circuiting, traces, and composite error handling
• server validation/error-path tests for nested field paths and sanitized evaluator failures
• compatibility tests for legacy flat stored control payloads on read
• dedicated Alembic migration tests covering no-op, rewrite, invalid-row failure, atomic rollback, offline rejection, API post-migration shape, and multi-row rewrite
• UI tests for the current composite-editing limitation and JSON editor behavior

Notes:

• the full check run emitted a few existing third-party warnings (sqlglot[rs] deprecation, Strands resource/deprecation warnings), but the targets passed cleanly

Checklist

• Linked issue/spec: sc-57582, sc-58429
• Updated docs/examples for user-facing changes
• Included any required follow-up tasks

[codecov]

Codecov Report

❌ Patch coverage is 94.10569% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
models/src/agent_control_models/controls.py	91.85%	11 Missing ⚠️
engine/src/agent_control_engine/core.py	93.27%	8 Missing ⚠️
...ver/src/agent_control_server/endpoints/controls.py	91.66%	5 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py	92.00%	4 Missing ⚠️
...ent_control_server/services/control_definitions.py	96.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

flowchart TD
C["condition (root)"] --> A["and"]
C --> O["or"]
C --> N["not"]
A --> L1["leaf: selector + evaluator"]
A --> L2["leaf: selector + evaluator"]
O --> L3["leaf: selector + evaluator"]
O --> A2["and"]
A2 --> L4["leaf: selector + evaluator"]
A2 --> L5["leaf: selector + evaluator"]
N --> L6["leaf: selector + evaluator"]

Loading

[namrataghadi-galileo]

One suggestion from Observability perspective:

Current issue:
- primary_leaf() returns None for composite conditions, so evaluator_name and selector_path become null in observability events.
Suggested change:
- Don’t use primary_leaf() for observability identity.
- Derive a deterministic representative from all leaves (first leaf in traversal order).
- Keep full composite context in metadata.
Proposed behavior:
- evaluator_name = first leaf evaluator
- selector_path = first leaf selector path
- add metadata:
leaf_count
all_evaluators (ordered, deduped)
all_selector_paths (ordered, deduped)
optionally representative_* naming to avoid semantic confusion
Why:
- Prevents null observability dimensions for composite controls.
- Preserves backward compatibility for dashboards filtering by evaluator/selector.
- Still keeps full truth about all leaves in metadata.

[lan17]

Following up on the broader observability note: I aligned server and SDK event emission so composite conditions use a deterministic representative leaf for top-level selector_path / evaluator_name, while preserving the full composite context in metadata (primary_*, leaf_count, ordered/deduped evaluator and selector lists).

[galileo-automation]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[lan17]

corresponding docs update: agentcontrol/docs-agent-control#28

Summary

• replace flat control predicates with recursive condition trees across the shared models, engine, server, SDKs, and UI contracts
• normalize legacy flat stored controls during Alembic upgrade and add safe condition_trace metadata for composite evaluation
• regenerate the TypeScript SDK/API types for the new contract and keep rollout-time legacy read compatibility on the server/models

Scope

• User-facing/API changes:
  • ControlDefinition now uses a top-level condition tree instead of top-level selector / evaluator
  • controls now support nested and / or / not composition with a hard API depth limit of 6
  • /api/v1 route structure stays the same, but the canonical contract is a breaking change for SDK consumers that construct control payloads directly
  • the TypeScript SDK release should be marked breaking so npm publishes a new major for the condition-tree input contract
• Internal changes:
  • recursive engine evaluation with short-circuiting and metadata.condition_trace
  • clearer composite error traces (matched: null on error) and preserved raw diagnostics for internal observability while API responses stay sanitized
  • recursive server-side validation with nested field paths
  • Python SDK recursive leaf checks plus non-blocking server-version mismatch warnings
  • UI keeps the existing single-condition editor behavior for leaf conditions; composite trees are shown but preserved on save rather than fully edited in this PR
• Rollout compatibility notes:
  • server/models still canonicalize legacy flat control payloads (selector + evaluator) into condition during rollout
  • legacy flat rows in the database are normalized by Alembic revision 9f2f5a4e6c1b_normalize_legacy_control_conditions
  • the standalone migration script/Make target was removed; Alembic is the one authoritative migration path
• Out of scope:
  • full condition-tree editing in the current UI modal
  • runtime strict rejection of legacy flat control payloads
  • drag-and-drop tree editing

Risk and Rollout

• Risk level: high
• Rollback plan:
  • take a database backup before running alembic upgrade head
  • if rollout fails before the Alembic data migration runs, revert to the previous server/SDK major
  • if rollout fails after the Alembic data migration runs, restore the pre-migration database snapshot before rolling back the server major
• Migration behavior:
  • the Alembic normalization is SQL-only and runs once during upgrade
  • it fails hard if stored control rows are ambiguous/corrupted (mixed canonical+legacy fields, partial legacy fields, non-object JSON, etc.)
  • the migration is intentionally irreversible

Testing

• Added or updated automated tests
• Ran make check
• Manually verified behavior

make check passed, which covered:

• make models-test
• make server-test
• make engine-test
• make sdk-test
• make evaluators-test
• repo linting
• repo typechecking

Additional focused coverage added in this PR includes:

• direct model tests for recursive condition trees and legacy canonicalization
• engine tests for composite traversal, short-circuiting, traces, and composite error handling
• server validation/error-path tests for nested field paths and sanitized evaluator failures
• compatibility tests for legacy flat stored control payloads on read
• dedicated Alembic migration tests covering no-op, rewrite, invalid-row failure, atomic rollback, offline rejection, API post-migration shape, and multi-row rewrite
• UI tests for the current composite-editing limitation and JSON editor behavior

Notes:

• the full check run emitted a few existing third-party warnings (sqlglot[rs] deprecation, Strands resource/deprecation warnings), but the targets passed cleanly

Checklist

• Linked issue/spec: sc-57582, sc-58429
• Updated docs/examples for user-facing changes
• Included any required follow-up tasks

[codecov]

Codecov Report

❌ Patch coverage is 94.10569% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
models/src/agent_control_models/controls.py	91.85%	11 Missing ⚠️
engine/src/agent_control_engine/core.py	93.27%	8 Missing ⚠️
...ver/src/agent_control_server/endpoints/controls.py	91.66%	5 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py	92.00%	4 Missing ⚠️
...ent_control_server/services/control_definitions.py	96.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

flowchart TD
C["condition (root)"] --> A["and"]
C --> O["or"]
C --> N["not"]
A --> L1["leaf: selector + evaluator"]
A --> L2["leaf: selector + evaluator"]
O --> L3["leaf: selector + evaluator"]
O --> A2["and"]
A2 --> L4["leaf: selector + evaluator"]
A2 --> L5["leaf: selector + evaluator"]
N --> L6["leaf: selector + evaluator"]

Loading

[namrataghadi-galileo]

One suggestion from Observability perspective:

Current issue:
- primary_leaf() returns None for composite conditions, so evaluator_name and selector_path become null in observability events.
Suggested change:
- Don’t use primary_leaf() for observability identity.
- Derive a deterministic representative from all leaves (first leaf in traversal order).
- Keep full composite context in metadata.
Proposed behavior:
- evaluator_name = first leaf evaluator
- selector_path = first leaf selector path
- add metadata:
leaf_count
all_evaluators (ordered, deduped)
all_selector_paths (ordered, deduped)
optionally representative_* naming to avoid semantic confusion
Why:
- Prevents null observability dimensions for composite controls.
- Preserves backward compatibility for dashboards filtering by evaluator/selector.
- Still keeps full truth about all leaves in metadata.

[lan17]

Following up on the broader observability note: I aligned server and SDK event emission so composite conditions use a deterministic representative leaf for top-level selector_path / evaluator_name, while preserving the full composite context in metadata (primary_*, leaf_count, ordered/deduped evaluator and selector lists).

[galileo-automation]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[lan17]

corresponding docs update: agentcontrol/docs-agent-control#28

Summary

• replace flat control predicates with recursive condition trees across the shared models, engine, server, SDKs, and UI contracts
• normalize legacy flat stored controls during Alembic upgrade and add safe condition_trace metadata for composite evaluation
• regenerate the TypeScript SDK/API types for the new contract and keep rollout-time legacy read compatibility on the server/models

Scope

• User-facing/API changes:
  • ControlDefinition now uses a top-level condition tree instead of top-level selector / evaluator
  • controls now support nested and / or / not composition with a hard API depth limit of 6
  • /api/v1 route structure stays the same, but the canonical contract is a breaking change for SDK consumers that construct control payloads directly
  • the TypeScript SDK release should be marked breaking so npm publishes a new major for the condition-tree input contract
• Internal changes:
  • recursive engine evaluation with short-circuiting and metadata.condition_trace
  • clearer composite error traces (matched: null on error) and preserved raw diagnostics for internal observability while API responses stay sanitized
  • recursive server-side validation with nested field paths
  • Python SDK recursive leaf checks plus non-blocking server-version mismatch warnings
  • UI keeps the existing single-condition editor behavior for leaf conditions; composite trees are shown but preserved on save rather than fully edited in this PR
• Rollout compatibility notes:
  • server/models still canonicalize legacy flat control payloads (selector + evaluator) into condition during rollout
  • legacy flat rows in the database are normalized by Alembic revision 9f2f5a4e6c1b_normalize_legacy_control_conditions
  • the standalone migration script/Make target was removed; Alembic is the one authoritative migration path
• Out of scope:
  • full condition-tree editing in the current UI modal
  • runtime strict rejection of legacy flat control payloads
  • drag-and-drop tree editing

Risk and Rollout

• Risk level: high
• Rollback plan:
  • take a database backup before running alembic upgrade head
  • if rollout fails before the Alembic data migration runs, revert to the previous server/SDK major
  • if rollout fails after the Alembic data migration runs, restore the pre-migration database snapshot before rolling back the server major
• Migration behavior:
  • the Alembic normalization is SQL-only and runs once during upgrade
  • it fails hard if stored control rows are ambiguous/corrupted (mixed canonical+legacy fields, partial legacy fields, non-object JSON, etc.)
  • the migration is intentionally irreversible

Testing

• Added or updated automated tests
• Ran make check
• Manually verified behavior

make check passed, which covered:

• make models-test
• make server-test
• make engine-test
• make sdk-test
• make evaluators-test
• repo linting
• repo typechecking

Additional focused coverage added in this PR includes:

• direct model tests for recursive condition trees and legacy canonicalization
• engine tests for composite traversal, short-circuiting, traces, and composite error handling
• server validation/error-path tests for nested field paths and sanitized evaluator failures
• compatibility tests for legacy flat stored control payloads on read
• dedicated Alembic migration tests covering no-op, rewrite, invalid-row failure, atomic rollback, offline rejection, API post-migration shape, and multi-row rewrite
• UI tests for the current composite-editing limitation and JSON editor behavior

Notes:

• the full check run emitted a few existing third-party warnings (sqlglot[rs] deprecation, Strands resource/deprecation warnings), but the targets passed cleanly

Checklist

• Linked issue/spec: sc-57582, sc-58429
• Updated docs/examples for user-facing changes
• Included any required follow-up tasks

[codecov]

Codecov Report

❌ Patch coverage is 94.10569% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
models/src/agent_control_models/controls.py	91.85%	11 Missing ⚠️
engine/src/agent_control_engine/core.py	93.27%	8 Missing ⚠️
...ver/src/agent_control_server/endpoints/controls.py	91.66%	5 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py	92.00%	4 Missing ⚠️
...ent_control_server/services/control_definitions.py	96.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

flowchart TD
C["condition (root)"] --> A["and"]
C --> O["or"]
C --> N["not"]
A --> L1["leaf: selector + evaluator"]
A --> L2["leaf: selector + evaluator"]
O --> L3["leaf: selector + evaluator"]
O --> A2["and"]
A2 --> L4["leaf: selector + evaluator"]
A2 --> L5["leaf: selector + evaluator"]
N --> L6["leaf: selector + evaluator"]

Loading

[namrataghadi-galileo]

One suggestion from Observability perspective:

Current issue:
- primary_leaf() returns None for composite conditions, so evaluator_name and selector_path become null in observability events.
Suggested change:
- Don’t use primary_leaf() for observability identity.
- Derive a deterministic representative from all leaves (first leaf in traversal order).
- Keep full composite context in metadata.
Proposed behavior:
- evaluator_name = first leaf evaluator
- selector_path = first leaf selector path
- add metadata:
leaf_count
all_evaluators (ordered, deduped)
all_selector_paths (ordered, deduped)
optionally representative_* naming to avoid semantic confusion
Why:
- Prevents null observability dimensions for composite controls.
- Preserves backward compatibility for dashboards filtering by evaluator/selector.
- Still keeps full truth about all leaves in metadata.

[lan17]

Following up on the broader observability note: I aligned server and SDK event emission so composite conditions use a deterministic representative leaf for top-level selector_path / evaluator_name, while preserving the full composite context in metadata (primary_*, leaf_count, ordered/deduped evaluator and selector lists).

[galileo-automation]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[lan17]

corresponding docs update: agentcontrol/docs-agent-control#28

Summary

• replace flat control predicates with recursive condition trees across the shared models, engine, server, SDKs, and UI contracts
• normalize legacy flat stored controls during Alembic upgrade and add safe condition_trace metadata for composite evaluation
• regenerate the TypeScript SDK/API types for the new contract and keep rollout-time legacy read compatibility on the server/models

Scope

• User-facing/API changes:
  • ControlDefinition now uses a top-level condition tree instead of top-level selector / evaluator
  • controls now support nested and / or / not composition with a hard API depth limit of 6
  • /api/v1 route structure stays the same, but the canonical contract is a breaking change for SDK consumers that construct control payloads directly
  • the TypeScript SDK release should be marked breaking so npm publishes a new major for the condition-tree input contract
• Internal changes:
  • recursive engine evaluation with short-circuiting and metadata.condition_trace
  • clearer composite error traces (matched: null on error) and preserved raw diagnostics for internal observability while API responses stay sanitized
  • recursive server-side validation with nested field paths
  • Python SDK recursive leaf checks plus non-blocking server-version mismatch warnings
  • UI keeps the existing single-condition editor behavior for leaf conditions; composite trees are shown but preserved on save rather than fully edited in this PR
• Rollout compatibility notes:
  • server/models still canonicalize legacy flat control payloads (selector + evaluator) into condition during rollout
  • legacy flat rows in the database are normalized by Alembic revision 9f2f5a4e6c1b_normalize_legacy_control_conditions
  • the standalone migration script/Make target was removed; Alembic is the one authoritative migration path
• Out of scope:
  • full condition-tree editing in the current UI modal
  • runtime strict rejection of legacy flat control payloads
  • drag-and-drop tree editing

Risk and Rollout

• Risk level: high
• Rollback plan:
  • take a database backup before running alembic upgrade head
  • if rollout fails before the Alembic data migration runs, revert to the previous server/SDK major
  • if rollout fails after the Alembic data migration runs, restore the pre-migration database snapshot before rolling back the server major
• Migration behavior:
  • the Alembic normalization is SQL-only and runs once during upgrade
  • it fails hard if stored control rows are ambiguous/corrupted (mixed canonical+legacy fields, partial legacy fields, non-object JSON, etc.)
  • the migration is intentionally irreversible

Testing

• Added or updated automated tests
• Ran make check
• Manually verified behavior

make check passed, which covered:

• make models-test
• make server-test
• make engine-test
• make sdk-test
• make evaluators-test
• repo linting
• repo typechecking

Additional focused coverage added in this PR includes:

• direct model tests for recursive condition trees and legacy canonicalization
• engine tests for composite traversal, short-circuiting, traces, and composite error handling
• server validation/error-path tests for nested field paths and sanitized evaluator failures
• compatibility tests for legacy flat stored control payloads on read
• dedicated Alembic migration tests covering no-op, rewrite, invalid-row failure, atomic rollback, offline rejection, API post-migration shape, and multi-row rewrite
• UI tests for the current composite-editing limitation and JSON editor behavior

Notes:

• the full check run emitted a few existing third-party warnings (sqlglot[rs] deprecation, Strands resource/deprecation warnings), but the targets passed cleanly

Checklist

• Linked issue/spec: sc-57582, sc-58429
• Updated docs/examples for user-facing changes
• Included any required follow-up tasks

[codecov]

Codecov Report

❌ Patch coverage is 94.10569% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
models/src/agent_control_models/controls.py	91.85%	11 Missing ⚠️
engine/src/agent_control_engine/core.py	93.27%	8 Missing ⚠️
...ver/src/agent_control_server/endpoints/controls.py	91.66%	5 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py	92.00%	4 Missing ⚠️
...ent_control_server/services/control_definitions.py	96.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

flowchart TD
C["condition (root)"] --> A["and"]
C --> O["or"]
C --> N["not"]
A --> L1["leaf: selector + evaluator"]
A --> L2["leaf: selector + evaluator"]
O --> L3["leaf: selector + evaluator"]
O --> A2["and"]
A2 --> L4["leaf: selector + evaluator"]
A2 --> L5["leaf: selector + evaluator"]
N --> L6["leaf: selector + evaluator"]

Loading

[namrataghadi-galileo]

One suggestion from Observability perspective:

Current issue:
- primary_leaf() returns None for composite conditions, so evaluator_name and selector_path become null in observability events.
Suggested change:
- Don’t use primary_leaf() for observability identity.
- Derive a deterministic representative from all leaves (first leaf in traversal order).
- Keep full composite context in metadata.
Proposed behavior:
- evaluator_name = first leaf evaluator
- selector_path = first leaf selector path
- add metadata:
leaf_count
all_evaluators (ordered, deduped)
all_selector_paths (ordered, deduped)
optionally representative_* naming to avoid semantic confusion
Why:
- Prevents null observability dimensions for composite controls.
- Preserves backward compatibility for dashboards filtering by evaluator/selector.
- Still keeps full truth about all leaves in metadata.

[lan17]

Following up on the broader observability note: I aligned server and SDK event emission so composite conditions use a deterministic representative leaf for top-level selector_path / evaluator_name, while preserving the full composite context in metadata (primary_*, leaf_count, ordered/deduped evaluator and selector lists).

[galileo-automation]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[lan17]

corresponding docs update: agentcontrol/docs-agent-control#28

Summary

• replace flat control predicates with recursive condition trees across the shared models, engine, server, SDKs, and UI contracts
• normalize legacy flat stored controls during Alembic upgrade and add safe condition_trace metadata for composite evaluation
• regenerate the TypeScript SDK/API types for the new contract and keep rollout-time legacy read compatibility on the server/models

Scope

• User-facing/API changes:
  • ControlDefinition now uses a top-level condition tree instead of top-level selector / evaluator
  • controls now support nested and / or / not composition with a hard API depth limit of 6
  • /api/v1 route structure stays the same, but the canonical contract is a breaking change for SDK consumers that construct control payloads directly
  • the TypeScript SDK release should be marked breaking so npm publishes a new major for the condition-tree input contract
• Internal changes:
  • recursive engine evaluation with short-circuiting and metadata.condition_trace
  • clearer composite error traces (matched: null on error) and preserved raw diagnostics for internal observability while API responses stay sanitized
  • recursive server-side validation with nested field paths
  • Python SDK recursive leaf checks plus non-blocking server-version mismatch warnings
  • UI keeps the existing single-condition editor behavior for leaf conditions; composite trees are shown but preserved on save rather than fully edited in this PR
• Rollout compatibility notes:
  • server/models still canonicalize legacy flat control payloads (selector + evaluator) into condition during rollout
  • legacy flat rows in the database are normalized by Alembic revision 9f2f5a4e6c1b_normalize_legacy_control_conditions
  • the standalone migration script/Make target was removed; Alembic is the one authoritative migration path
• Out of scope:
  • full condition-tree editing in the current UI modal
  • runtime strict rejection of legacy flat control payloads
  • drag-and-drop tree editing

Risk and Rollout

• Risk level: high
• Rollback plan:
  • take a database backup before running alembic upgrade head
  • if rollout fails before the Alembic data migration runs, revert to the previous server/SDK major
  • if rollout fails after the Alembic data migration runs, restore the pre-migration database snapshot before rolling back the server major
• Migration behavior:
  • the Alembic normalization is SQL-only and runs once during upgrade
  • it fails hard if stored control rows are ambiguous/corrupted (mixed canonical+legacy fields, partial legacy fields, non-object JSON, etc.)
  • the migration is intentionally irreversible

Testing

• Added or updated automated tests
• Ran make check
• Manually verified behavior

make check passed, which covered:

• make models-test
• make server-test
• make engine-test
• make sdk-test
• make evaluators-test
• repo linting
• repo typechecking

Additional focused coverage added in this PR includes:

• direct model tests for recursive condition trees and legacy canonicalization
• engine tests for composite traversal, short-circuiting, traces, and composite error handling
• server validation/error-path tests for nested field paths and sanitized evaluator failures
• compatibility tests for legacy flat stored control payloads on read
• dedicated Alembic migration tests covering no-op, rewrite, invalid-row failure, atomic rollback, offline rejection, API post-migration shape, and multi-row rewrite
• UI tests for the current composite-editing limitation and JSON editor behavior

Notes:

• the full check run emitted a few existing third-party warnings (sqlglot[rs] deprecation, Strands resource/deprecation warnings), but the targets passed cleanly

Checklist

• Linked issue/spec: sc-57582, sc-58429
• Updated docs/examples for user-facing changes
• Included any required follow-up tasks

[codecov]

Codecov Report

❌ Patch coverage is 94.10569% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
models/src/agent_control_models/controls.py	91.85%	11 Missing ⚠️
engine/src/agent_control_engine/core.py	93.27%	8 Missing ⚠️
...ver/src/agent_control_server/endpoints/controls.py	91.66%	5 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py	92.00%	4 Missing ⚠️
...ent_control_server/services/control_definitions.py	96.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

flowchart TD
C["condition (root)"] --> A["and"]
C --> O["or"]
C --> N["not"]
A --> L1["leaf: selector + evaluator"]
A --> L2["leaf: selector + evaluator"]
O --> L3["leaf: selector + evaluator"]
O --> A2["and"]
A2 --> L4["leaf: selector + evaluator"]
A2 --> L5["leaf: selector + evaluator"]
N --> L6["leaf: selector + evaluator"]

Loading

[namrataghadi-galileo]

One suggestion from Observability perspective:

Current issue:
- primary_leaf() returns None for composite conditions, so evaluator_name and selector_path become null in observability events.
Suggested change:
- Don’t use primary_leaf() for observability identity.
- Derive a deterministic representative from all leaves (first leaf in traversal order).
- Keep full composite context in metadata.
Proposed behavior:
- evaluator_name = first leaf evaluator
- selector_path = first leaf selector path
- add metadata:
leaf_count
all_evaluators (ordered, deduped)
all_selector_paths (ordered, deduped)
optionally representative_* naming to avoid semantic confusion
Why:
- Prevents null observability dimensions for composite controls.
- Preserves backward compatibility for dashboards filtering by evaluator/selector.
- Still keeps full truth about all leaves in metadata.

[lan17]

Following up on the broader observability note: I aligned server and SDK event emission so composite conditions use a deterministic representative leaf for top-level selector_path / evaluator_name, while preserving the full composite context in metadata (primary_*, leaf_count, ordered/deduped evaluator and selector lists).

[galileo-automation]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[lan17]

corresponding docs update: agentcontrol/docs-agent-control#28

Summary

• replace flat control predicates with recursive condition trees across the shared models, engine, server, SDKs, and UI contracts
• normalize legacy flat stored controls during Alembic upgrade and add safe condition_trace metadata for composite evaluation
• regenerate the TypeScript SDK/API types for the new contract and keep rollout-time legacy read compatibility on the server/models

Scope

• User-facing/API changes:
  • ControlDefinition now uses a top-level condition tree instead of top-level selector / evaluator
  • controls now support nested and / or / not composition with a hard API depth limit of 6
  • /api/v1 route structure stays the same, but the canonical contract is a breaking change for SDK consumers that construct control payloads directly
  • the TypeScript SDK release should be marked breaking so npm publishes a new major for the condition-tree input contract
• Internal changes:
  • recursive engine evaluation with short-circuiting and metadata.condition_trace
  • clearer composite error traces (matched: null on error) and preserved raw diagnostics for internal observability while API responses stay sanitized
  • recursive server-side validation with nested field paths
  • Python SDK recursive leaf checks plus non-blocking server-version mismatch warnings
  • UI keeps the existing single-condition editor behavior for leaf conditions; composite trees are shown but preserved on save rather than fully edited in this PR
• Rollout compatibility notes:
  • server/models still canonicalize legacy flat control payloads (selector + evaluator) into condition during rollout
  • legacy flat rows in the database are normalized by Alembic revision 9f2f5a4e6c1b_normalize_legacy_control_conditions
  • the standalone migration script/Make target was removed; Alembic is the one authoritative migration path
• Out of scope:
  • full condition-tree editing in the current UI modal
  • runtime strict rejection of legacy flat control payloads
  • drag-and-drop tree editing

Risk and Rollout

• Risk level: high
• Rollback plan:
  • take a database backup before running alembic upgrade head
  • if rollout fails before the Alembic data migration runs, revert to the previous server/SDK major
  • if rollout fails after the Alembic data migration runs, restore the pre-migration database snapshot before rolling back the server major
• Migration behavior:
  • the Alembic normalization is SQL-only and runs once during upgrade
  • it fails hard if stored control rows are ambiguous/corrupted (mixed canonical+legacy fields, partial legacy fields, non-object JSON, etc.)
  • the migration is intentionally irreversible

Testing

• Added or updated automated tests
• Ran make check
• Manually verified behavior

make check passed, which covered:

• make models-test
• make server-test
• make engine-test
• make sdk-test
• make evaluators-test
• repo linting
• repo typechecking

Additional focused coverage added in this PR includes:

• direct model tests for recursive condition trees and legacy canonicalization
• engine tests for composite traversal, short-circuiting, traces, and composite error handling
• server validation/error-path tests for nested field paths and sanitized evaluator failures
• compatibility tests for legacy flat stored control payloads on read
• dedicated Alembic migration tests covering no-op, rewrite, invalid-row failure, atomic rollback, offline rejection, API post-migration shape, and multi-row rewrite
• UI tests for the current composite-editing limitation and JSON editor behavior

Notes:

• the full check run emitted a few existing third-party warnings (sqlglot[rs] deprecation, Strands resource/deprecation warnings), but the targets passed cleanly

Checklist

• Linked issue/spec: sc-57582, sc-58429
• Updated docs/examples for user-facing changes
• Included any required follow-up tasks

[codecov]

Codecov Report

❌ Patch coverage is 94.10569% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
models/src/agent_control_models/controls.py	91.85%	11 Missing ⚠️
engine/src/agent_control_engine/core.py	93.27%	8 Missing ⚠️
...ver/src/agent_control_server/endpoints/controls.py	91.66%	5 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py	92.00%	4 Missing ⚠️
...ent_control_server/services/control_definitions.py	96.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

flowchart TD
C["condition (root)"] --> A["and"]
C --> O["or"]
C --> N["not"]
A --> L1["leaf: selector + evaluator"]
A --> L2["leaf: selector + evaluator"]
O --> L3["leaf: selector + evaluator"]
O --> A2["and"]
A2 --> L4["leaf: selector + evaluator"]
A2 --> L5["leaf: selector + evaluator"]
N --> L6["leaf: selector + evaluator"]

Loading

[namrataghadi-galileo]

One suggestion from Observability perspective:

Current issue:
- primary_leaf() returns None for composite conditions, so evaluator_name and selector_path become null in observability events.
Suggested change:
- Don’t use primary_leaf() for observability identity.
- Derive a deterministic representative from all leaves (first leaf in traversal order).
- Keep full composite context in metadata.
Proposed behavior:
- evaluator_name = first leaf evaluator
- selector_path = first leaf selector path
- add metadata:
leaf_count
all_evaluators (ordered, deduped)
all_selector_paths (ordered, deduped)
optionally representative_* naming to avoid semantic confusion
Why:
- Prevents null observability dimensions for composite controls.
- Preserves backward compatibility for dashboards filtering by evaluator/selector.
- Still keeps full truth about all leaves in metadata.

[lan17]

Following up on the broader observability note: I aligned server and SDK event emission so composite conditions use a deterministic representative leaf for top-level selector_path / evaluator_name, while preserving the full composite context in metadata (primary_*, leaf_count, ordered/deduped evaluator and selector lists).

[galileo-automation]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀

[lan17]

corresponding docs update: agentcontrol/docs-agent-control#28

Summary

• replace flat control predicates with recursive condition trees across the shared models, engine, server, SDKs, and UI contracts
• normalize legacy flat stored controls during Alembic upgrade and add safe condition_trace metadata for composite evaluation
• regenerate the TypeScript SDK/API types for the new contract and keep rollout-time legacy read compatibility on the server/models

Scope

• User-facing/API changes:
  • ControlDefinition now uses a top-level condition tree instead of top-level selector / evaluator
  • controls now support nested and / or / not composition with a hard API depth limit of 6
  • /api/v1 route structure stays the same, but the canonical contract is a breaking change for SDK consumers that construct control payloads directly
  • the TypeScript SDK release should be marked breaking so npm publishes a new major for the condition-tree input contract
• Internal changes:
  • recursive engine evaluation with short-circuiting and metadata.condition_trace
  • clearer composite error traces (matched: null on error) and preserved raw diagnostics for internal observability while API responses stay sanitized
  • recursive server-side validation with nested field paths
  • Python SDK recursive leaf checks plus non-blocking server-version mismatch warnings
  • UI keeps the existing single-condition editor behavior for leaf conditions; composite trees are shown but preserved on save rather than fully edited in this PR
• Rollout compatibility notes:
  • server/models still canonicalize legacy flat control payloads (selector + evaluator) into condition during rollout
  • legacy flat rows in the database are normalized by Alembic revision 9f2f5a4e6c1b_normalize_legacy_control_conditions
  • the standalone migration script/Make target was removed; Alembic is the one authoritative migration path
• Out of scope:
  • full condition-tree editing in the current UI modal
  • runtime strict rejection of legacy flat control payloads
  • drag-and-drop tree editing

Risk and Rollout

• Risk level: high
• Rollback plan:
  • take a database backup before running alembic upgrade head
  • if rollout fails before the Alembic data migration runs, revert to the previous server/SDK major
  • if rollout fails after the Alembic data migration runs, restore the pre-migration database snapshot before rolling back the server major
• Migration behavior:
  • the Alembic normalization is SQL-only and runs once during upgrade
  • it fails hard if stored control rows are ambiguous/corrupted (mixed canonical+legacy fields, partial legacy fields, non-object JSON, etc.)
  • the migration is intentionally irreversible

Testing

• Added or updated automated tests
• Ran make check
• Manually verified behavior

make check passed, which covered:

• make models-test
• make server-test
• make engine-test
• make sdk-test
• make evaluators-test
• repo linting
• repo typechecking

Additional focused coverage added in this PR includes:

• direct model tests for recursive condition trees and legacy canonicalization
• engine tests for composite traversal, short-circuiting, traces, and composite error handling
• server validation/error-path tests for nested field paths and sanitized evaluator failures
• compatibility tests for legacy flat stored control payloads on read
• dedicated Alembic migration tests covering no-op, rewrite, invalid-row failure, atomic rollback, offline rejection, API post-migration shape, and multi-row rewrite
• UI tests for the current composite-editing limitation and JSON editor behavior

Notes:

• the full check run emitted a few existing third-party warnings (sqlglot[rs] deprecation, Strands resource/deprecation warnings), but the targets passed cleanly

Checklist

• Linked issue/spec: sc-57582, sc-58429
• Updated docs/examples for user-facing changes
• Included any required follow-up tasks

[codecov]

Codecov Report

❌ Patch coverage is 94.10569% with 29 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
models/src/agent_control_models/controls.py	91.85%	11 Missing ⚠️
engine/src/agent_control_engine/core.py	93.27%	8 Missing ⚠️
...ver/src/agent_control_server/endpoints/controls.py	91.66%	5 Missing ⚠️
...erver/src/agent_control_server/endpoints/agents.py	92.00%	4 Missing ⚠️
...ent_control_server/services/control_definitions.py	96.00%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[namrataghadi-galileo]

flowchart TD
C["condition (root)"] --> A["and"]
C --> O["or"]
C --> N["not"]
A --> L1["leaf: selector + evaluator"]
A --> L2["leaf: selector + evaluator"]
O --> L3["leaf: selector + evaluator"]
O --> A2["and"]
A2 --> L4["leaf: selector + evaluator"]
A2 --> L5["leaf: selector + evaluator"]
N --> L6["leaf: selector + evaluator"]

Loading

[namrataghadi-galileo]

One suggestion from Observability perspective:

Current issue:
- primary_leaf() returns None for composite conditions, so evaluator_name and selector_path become null in observability events.
Suggested change:
- Don’t use primary_leaf() for observability identity.
- Derive a deterministic representative from all leaves (first leaf in traversal order).
- Keep full composite context in metadata.
Proposed behavior:
- evaluator_name = first leaf evaluator
- selector_path = first leaf selector path
- add metadata:
leaf_count
all_evaluators (ordered, deduped)
all_selector_paths (ordered, deduped)
optionally representative_* naming to avoid semantic confusion
Why:
- Prevents null observability dimensions for composite controls.
- Preserves backward compatibility for dashboards filtering by evaluator/selector.
- Still keeps full truth about all leaves in metadata.

[lan17]

Following up on the broader observability note: I aligned server and SDK event emission so composite conditions use a deterministic representative leaf for top-level selector_path / evaluator_name, while preserving the full composite context in metadata (primary_*, leaf_count, ordered/deduped evaluator and selector lists).

[galileo-automation]

🎉 This PR is included in version 2.0.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀