feat(server): add control clone-and-bind endpoint

[abhinav-galileo]

Summary

• Add controls.cloned_from_control_id plus cloned=true|false filtering on GET /api/v1/controls.
• Add POST /api/v1/controls/{control_id}/clone-and-bind to clone an active control and create a target binding in one transaction.
• Add optional attachment expansion on GET /api/v1/controls for direct agents, policies, and target bindings, including each control's action.
• Apply attachment_target_type / attachment_target_id filters before list pagination, so callers can list controls attached to a specific target.
• Add PATCH /api/v1/control-bindings/by-key so target-scoped callers can enable or disable an existing binding without knowing the binding ID.
• Distinguish unexpected authorization-upstream 4xx responses as AUTH_UPSTREAM_REJECTED instead of reporting them as local auth misconfiguration.
• Update Python and generated TypeScript SDK surfaces with server and SDK tests.

Usage

Clone a control and bind the clone to a target:

POST /api/v1/controls/{control_id}/clone-and-bind

{
  "name": "optional-clone-name",
  "target_binding": {
    "target_type": "environment",
    "target_id": "prod",
    "enabled": true
  }
}

{
  "id": 42,
  "name": "optional-clone-name",
  "cloned_from_control_id": 7,
  "binding_id": 99
}

List root controls or cloned controls:

GET /api/v1/controls?cloned=false
GET /api/v1/controls?cloned=true

List controls with page-scoped attachment details:

GET /api/v1/controls?include_attachments=true

List controls attached to a specific target:

GET /api/v1/controls?include_attachments=true&attachment_target_type=environment&attachment_target_id=prod

When target filters are provided, the control list is filtered before pagination, and each returned control's attachments.targets is filtered to the same target.

Each expanded control includes the normal control details, action, and optional attachments:

{
  "id": 42,
  "name": "example-control",
  "description": "Example control",
  "action": {
    "decision": "deny",
    "steering_context": null
  },
  "attachments": {
    "agents": [{ "agent_name": "example-agent" }],
    "policies": [{ "policy_id": 42 }],
    "targets": [
      {
        "binding_id": 123,
        "target_type": "environment",
        "target_id": "prod",
        "enabled": true
      }
    ]
  }
}

Enable or disable an existing target binding by natural key:

PATCH /api/v1/control-bindings/by-key

{
  "target_type": "environment",
  "target_id": "prod",
  "control_id": 42,
  "enabled": false
}

{
  "success": true,
  "enabled": false
}

This PATCH route updates only existing bindings. It returns CONTROL_BINDING_NOT_FOUND instead of creating a missing binding.

For full target-binding pagination/filtering, callers can continue using GET /api/v1/control-bindings.

Validation

• make models-test
• make server-test
• make sdk-test
• uv run --package agent-control-models ruff check --config pyproject.toml models/src
• uv run --package agent-control-server ruff check --config pyproject.toml server/src
• uv run --package agent-control ruff check --config pyproject.toml sdks/python/src
• uv run --package agent-control-models mypy --config-file pyproject.toml models/src
• uv run --package agent-control-server mypy --config-file pyproject.toml server/src
• uv run --package agent-control mypy --config-file pyproject.toml sdks/python/src
• make sdk-ts-typecheck
• make sdk-ts-name-check
• make sdk-ts-generate-check

[codecov]

Codecov Report

❌ Patch coverage is 94.44444% with 15 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...ver/src/agent_control_server/endpoints/controls.py	88.42%	14 Missing ⚠️
...rver/src/agent_control_server/services/controls.py	98.36%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!

[lan17]

Add POST /api/v1/controls/{control_id}/clone-and-bind to clone an active control and create a target binding in one transaction.

Jw, why does it need to be inside transaction? We could do this via several API calls without making new ones right?

[abhinav-galileo]

Add POST /api/v1/controls/{control_id}/clone-and-bind to clone an active control and create a target binding in one transaction.

Jw, why does it need to be inside transaction? We could do this via several API calls without making new ones right?

Yes, this could be done with individual APIs, but that path would need a small refactor to preserve clone lineage consistently.

This endpoint is mainly a transactional convenience API for the UI: clone + bind is one user action, and keeping it server-side avoids partial state and client-side cleanup logic if the bind step fails.

[galileo-automation]

🎉 This PR is included in version 2.6.0 🎉

The release is available on:

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

Your semantic-release bot 📦🚀