Agent capabilities

An agent capability is a bounded build step. It has a versioned prompt, a tool allowlist, a validator, and a retry budget. The agent proposes; the validator decides. A failed validator stops the step and keeps the evidence. It does not retry with a new assumption.

The committed registry is brushline.capabilities.v1. The six core capabilities are:

Capability

Prompt

Tools

Validator

select_aoi

brushline.agent.select_aoi.v1

aoi.read, aoi.validate

aoi_outcome

propose_fetch_plan

brushline.agent.propose_fetch_plan.v1

catalogue.read, fetch.plan

fetch_plan_outcome

seed_vegetation_state

brushline.agent.seed_state.v1

instance.seed_state, state.validate

state_outcome

compile_dataset

brushline.agent.compile_dataset.v1

instance.compile_dataset, dataset.validate

dataset_outcome

validate_scenario

brushline.agent.validate_scenario.v1

scenario.read, scenario.validate

scenario_outcome

build_demo

brushline.agent.build_demo.v1

demo.build, demo.validate

demo_outcome

Every capability has a prompt version, a description, a non-empty tool allowlist, a registered validator, and a retry budget from 0 to 2. A capability with no validator is rejected by the registry validator and stops before a provider call.

Tools

The tool registry describes what each allowlisted tool does and whether it mutates. The current tools are read-only metadata, compiler, state, scenario, and demo steps. None reads a private row. A private tool cannot be allowlisted.

A tool call in a provider response must be allowlisted and must end with status ok. An unknown tool, a blocked tool, or an errored tool stops the capability with AGENT-TOOL.

Harness flow

run_capability follows a fixed order:

  1. Build the request with a canonical input hash and the capability prompt.

  2. Reject a private-data marker in the prompt before calling the provider.

  3. Call the provider. A provider exception may retry up to the capability budget.

  4. Reject an unknown, blocked, or errored tool call.

  5. Reject a private-data marker in the outcome.

  6. Reject an agent-authored authoritative, coefficient, geometry, or validation_result field.

  7. Run the capability validator.

  8. Record a sanitized outcome.

A validator failure is final. It does not consume the provider retry budget. A provider exception can retry, but the record contains only the exception type, never the exception message.

Prompt and input

build_agent_request hashes a canonical JSON form of the input. The request carries the prompt id, prompt version, input hash, and tool allowlist. The default prompt tells the provider not to compute or assert an authoritative number, coefficient, geometry, or validation result, and not to include private rows or confidential values.

A caller can supply a prompt override for a test, but the harness still scans it. A private-data marker in the prompt stops the run before the provider is called.

Outcome record

CapabilityOutcome is the sanitized evidence record. It has:

  • capability id and prompt id;

  • input SHA-256 and outcome SHA-256;

  • validator id and the shared validator report;

  • sanitized tool calls;

  • final state (succeeded, stopped, or failed);

  • attempts, retry budget, stop reason, and creation time.

The record does not contain the prompt, a raw private row, or the unhashed outcome. A private marker in a tool summary fails the record validator.

from datetime import UTC, datetime
from brushline.integrations.capabilities import (
    AgentResponse,
    FakeAgentProvider,
    default_capability_registry,
    run_capability,
    validate_capability_outcome,
)

capability = default_capability_registry().capabilities[0]
provider = FakeAgentProvider(
    {
        "select_aoi": [
            AgentResponse(
                outcome={
                    "aoi_path": "aoi.geojson",
                    "feature_count": 1,
                    "source_sha256": "a" * 64,
                }
            )
        ]
    }
)
result = run_capability(
    capability,
    {"aoi": "aoi.geojson"},
    provider,
    created_utc=datetime(2026, 11, 14, tzinfo=UTC),
)
assert result.final_state == "succeeded"
assert validate_capability_outcome(result).is_valid

Validators

The built-in validators are intentionally narrow:

  • aoi_outcome checks the AOI path, a positive feature count, and the source hash.

  • fetch_plan_outcome parses the P2.5 plan and runs validate_fetch_plan.

  • state_outcome parses the P2.3 state contract and runs validate_state_contract.

  • dataset_outcome parses the dataset manifest and requires a dataset path.

  • scenario_outcome checks the scenario and targets schema versions and the target list.

  • demo_outcome parses the demo manifest and runs validate_demo_manifest.

The agent does not produce the authoritative number, coefficient, geometry, or validation result. The validator sees the outcome and decides. A capability cannot silently skip a failing validator.

Named errors

Prefix

Meaning

CAPABILITIES-*

Registry problems: missing capability, prompt, tool, validator, private tool, retry budget, or empty registry.

AGENT-PRIVATE

A private-data marker was found in a prompt, outcome, tool summary, or record.

AGENT-AUTHORITY

An outcome contains a forbidden authoritative field.

AGENT-TOOL

A tool is not allowlisted, has an unknown status, or did not finish ok.

AGENT-PROVIDER

The provider failed after the bounded retry budget.

AGENT-VALIDATOR

The capability has no registered validator, or the outcome validator failed.

AGENT-OUTCOME

The sanitized record has a bad state, hash, attempt count, evidence, or time.

What this page does not promise

  • It does not add a live model-provider integration. The tests use a fake provider.

  • It does not approve a connector, fetch data, or bypass an owner gate.

  • It does not make an agent-produced geometry, coefficient, number, or validation result authoritative.

  • It does not turn a private row into prompt text, a tool summary, or an outcome record.