freemo
0265b8c712
CI / benchmark-publish (pull_request) Has been skipped
CI / build (pull_request) Successful in 18s
CI / lint (pull_request) Successful in 21s
CI / quality (pull_request) Successful in 33s
CI / security (pull_request) Successful in 38s
CI / typecheck (pull_request) Successful in 38s
CI / coverage (pull_request) Has been cancelled
CI / unit_tests (pull_request) Has been cancelled
CI / integration_tests (pull_request) Has been cancelled
CI / benchmark-regression (pull_request) Has been cancelled
CI / docker (pull_request) Has been cancelled
133 lines
3.6 KiB
Markdown
133 lines
3.6 KiB
Markdown
# Tool Resource Bindings
|
|
|
|
Tools in CleverAgents declare **resource slots** that describe which
|
|
resources they operate on. At activation time the binding resolution
|
|
service maps each slot to a concrete resource from the registry.
|
|
|
|
## Binding Modes
|
|
|
|
### Contextual Binding (default)
|
|
|
|
The slot declares only a `resource_type` requirement. The system
|
|
searches the plan's project for linked resources that match at
|
|
activation time.
|
|
|
|
**Resolution rules:**
|
|
|
|
1. Collect all linked resources whose type matches the slot's
|
|
`resource_type` (including sub-types via `parent_types`).
|
|
2. If exactly **one** resource matches, it is automatically bound.
|
|
3. If **multiple** resources match, the slot `name` is used as a
|
|
hint: the resource whose alias (or short name) equals the slot
|
|
name is selected. If no alias matches, a `ValidationError` is
|
|
raised.
|
|
4. If **no** resource matches and the slot is `required`, a
|
|
`ValidationError` is raised.
|
|
|
|
```yaml
|
|
resource_slots:
|
|
- name: repo
|
|
resource_type: git-checkout
|
|
access: read_write
|
|
binding: contextual # default -- can be omitted
|
|
```
|
|
|
|
### Static Binding
|
|
|
|
The slot is hardcoded to a specific registered resource by name via
|
|
the `static_resource` field. Validated at registration time.
|
|
|
|
```yaml
|
|
resource_slots:
|
|
- name: config_dir
|
|
resource_type: fs-directory
|
|
access: read_only
|
|
binding: static
|
|
static_resource: local/shared-config
|
|
```
|
|
|
|
### Parameter Binding
|
|
|
|
The resource reference is passed as a tool argument at invocation
|
|
time. Resolution is deferred until the tool is actually called.
|
|
|
|
```yaml
|
|
resource_slots:
|
|
- name: target
|
|
resource_type: fs-directory
|
|
access: read_write
|
|
binding: parameter
|
|
```
|
|
|
|
At invocation the caller supplies `target=<resource-name-or-id>`.
|
|
|
|
## Resolution Order
|
|
|
|
For each resource slot on the tool:
|
|
|
|
1. Determine the binding mode (`static`, `parameter`, or
|
|
`contextual`).
|
|
2. **Static** -- look up the named resource in the registry;
|
|
verify type compatibility.
|
|
3. **Parameter** -- if invocation params include the slot name,
|
|
resolve eagerly; otherwise mark as *deferred*.
|
|
4. **Contextual** -- search the project's linked resources for
|
|
type-compatible matches and apply disambiguation rules.
|
|
|
|
## Type Compatibility
|
|
|
|
A resource is *type-compatible* with a slot when:
|
|
|
|
- The resource's type **exactly matches** the slot's
|
|
`resource_type`, **or**
|
|
- The resource's type declares the slot's `resource_type` in its
|
|
`parent_types` list (sub-type relationship).
|
|
|
|
For example, `fs-directory` lists `git-checkout` in its
|
|
`parent_types`, so an `fs-directory` resource satisfies a slot
|
|
requiring `git-checkout`.
|
|
|
|
## Examples
|
|
|
|
### Single Contextual Resource
|
|
|
|
```python
|
|
from cleveragents.application.services.binding_resolution_service import (
|
|
BindingResolutionService,
|
|
)
|
|
|
|
service = BindingResolutionService(resource_registry)
|
|
results = service.resolve(tool, project)
|
|
# results[0].binding_mode == "contextual"
|
|
# results[0].resource_id == "01HGZ..."
|
|
```
|
|
|
|
### Mixed Bindings
|
|
|
|
A tool may combine all three modes:
|
|
|
|
```yaml
|
|
resource_slots:
|
|
- name: repo
|
|
resource_type: git-checkout
|
|
access: read_write
|
|
binding: contextual
|
|
- name: config
|
|
resource_type: fs-directory
|
|
access: read_only
|
|
binding: static
|
|
static_resource: local/shared-config
|
|
- name: output
|
|
resource_type: fs-directory
|
|
access: write_only
|
|
binding: parameter
|
|
```
|
|
|
|
## API Reference
|
|
|
|
See:
|
|
|
|
- [`BindingResolutionService`](cleveragents/application/services/binding_resolution_service.md)
|
|
- [`BindingResult`](cleveragents/domain/models/core/resource_slot.md)
|
|
- [`ResourceSlot`](cleveragents/domain/models/core/tool.md)
|