crp.agent¶
Auto-generated reference for the crp.agent subpackage.
agent¶
crp.agent ¶
CRP multi-agent safety (CRP-SPEC-012).
Session-scoped Safety Budget + circuit breaker, cross-agent header propagation and delegation limits, cross-agent provenance linking, and the human-oversight token flow.
PRIVATE REFERENCE IMPLEMENTATION - SPEC-012 internals are NOT published. This package is part of the closed-source crp reference engine only.
Public API
AgentSafetyBudget / BudgetDecision / classify_budget - budget + circuit breaker DelegationLimits / check_delegation - chain-bounding guards build_downstream_headers / filter_upstream_headers - header propagation link_sub_agent_hmac / fan_in_hmac / SubAgentResult - cross-agent provenance issue_oversight_token / verify_oversight_token - oversight token flow
AutonomyAction ¶
Bases: str, Enum
Canonical actions an agent may attempt, from low to high risk.
AutonomyDecision dataclass ¶
Outcome of a tier assignment and action authorization.
to_dict() ¶
Serialize to a dict.
AutonomyGovernor ¶
Assign autonomy tiers from measured reliability and enforce action policy.
Usage::
gov = AutonomyGovernor()
metrics = AutonomyMetrics(asr=0.0, pass_k=0.92, verification_rate=0.91, n_samples=40)
tier = gov.assign_tier(metrics)
decision = gov.authorize(tier, AutonomyAction.HIGH_RISK)
assign_tier(metrics) ¶
Return the autonomy tier implied by metrics.
Rules (most restrictive wins): 1. ASR > 0.05 or < 10 samples → T0 supervised. 2. ASR > 0 or pass@k < 0.90 or verification < 0.70 → T1 constrained. 3. pass@k >= 0.90 and verification >= 0.90 and n >= 30 → T3 autonomous. 4. Otherwise (pass@k >= 0.90, verification >= 0.70) → T2 conditional.
authorize(tier, action) ¶
Return whether action is permitted at tier.
Policy matrix
T0: only READ allowed (everything else → checkpoint). T1: READ + TOOL with grounding. T2: READ + TOOL + WRITE; HIGH_RISK simulated/gated. T3: all actions allowed, including DELEGATE.
enforce(metrics, action, *, kill_switch=None) ¶
Assign tier and authorize action in one call.
If kill_switch is provided and the metrics show a severe trust collapse (ASR > 0.10), the kill-switch is fired.
AutonomyMetrics dataclass ¶
Measured evidence used to assign an autonomy tier.
AutonomyTier ¶
Bases: str, Enum
Autonomy tiers ordered from least to most autonomous.
AgentSafetyBudget dataclass ¶
Session-scoped safety budget (CRP-SPEC-012 §2).
The authoritative budget value lives in the signed session token; this object is the gateway-side accountant. Decrements are computed server-side only (anti-inflation, §10.1) and the budget never recovers within a session (§2.4).
Attributes:
| Name | Type | Description |
|---|---|---|
budget | float | Current remaining safety budget, initialised to |
decrements | dict[RiskLevel, float] | Mapping from |
health property ¶
Return the current BudgetHealth band.
circuit_state property ¶
Return the current CircuitState.
peek() ¶
Return the current decision without applying any decrement.
Returns:
| Type | Description |
|---|---|
BudgetDecision | A |
account(risk_level, *, is_redispatch=False) ¶
Decrement the budget for a delivered response's risk level (§2.2).
Re-dispatches do not decrement (§2.5) - only the final delivered response counts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
risk_level | RiskLevel | None | DPE risk level of the delivered response, or None if the response carries no risk classification. | required |
is_redispatch | bool | When True, the event is a re-dispatch and must not decrement the budget. | False |
Returns:
| Type | Description |
|---|---|
BudgetDecision | The resulting |
merge_downstream(sub_agent_budget) ¶
Fan-in merge: orchestrator budget = min of self and sub-agent (§5.3).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sub_agent_budget | float | Remaining safety budget reported by a sub-agent. | required |
Returns:
| Type | Description |
|---|---|
BudgetDecision | The resulting |
BudgetDecision dataclass ¶
Outcome of accounting a risk event against the budget.
Attributes:
| Name | Type | Description |
|---|---|---|
budget | float | Remaining safety budget after the event. |
health | BudgetHealth | Human-readable health band for the remaining budget. |
circuit_state | CircuitState | Current circuit-breaker state. |
http_status | int | None | HTTP status to return when the session is halted, or None. |
force_oversight | bool | Whether the gateway should force human review. |
warning | str | None | Short warning label for CRP-Safety-Budget-Warning header. |
retry_after | str | None | Retry guidance for halted sessions, or None. |
halted property ¶
Return True if the session has been halted (HTTP 451).
headers property ¶
CRP headers describing the current budget state.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Mapping of CRP header names to header values, including the |
dict[str, str] | remaining budget and any warning/oversight/retry directives. |
BudgetHealth ¶
Bases: str, Enum
Budget health band (CRP-SPEC-012 §2.3).
Attributes:
| Name | Type | Description |
|---|---|---|
HEALTHY | Budget above 0.50. | |
CAUTION | Budget between 0.25 and 0.50 inclusive. | |
LOW | Budget between 0.10 and 0.24. | |
DEPLETED | Budget at or below 0.10 but still positive. | |
EXHAUSTED | Budget at or below 0.00. |
CircuitState ¶
Bases: str, Enum
Circuit-breaker state (CRP-SPEC-012 §5.1).
Attributes:
| Name | Type | Description |
|---|---|---|
CLOSED | Normal operation; budget is above the half-open threshold. | |
HALF_OPEN | Cautious operation; human review may be required. | |
OPEN | Session halted; the gateway responds with HTTP 451. |
FanInQualityResult dataclass ¶
Aggregate coherence/completeness over fan-in sub-agent responses (§8.3).
When an orchestrator merges several sub-agent results it must check that the combined answer is internally consistent (no cross-agent contradictions) and that, together, the sub-agents covered the parent query. This reuses RQA Stage 6 (cross-window coherence) and Stage 8 (completeness).
Attributes:
| Name | Type | Description |
|---|---|---|
coherence | object | None | Result of cross-agent coherence checking, or None if not run. |
completeness | object | None | Completeness result versus the parent query, or None. |
contradiction_count | int | Total number of contradictions detected across all pairwise comparisons. |
is_coherent property ¶
Return True when no contradictions were detected.
has_critical property ¶
Return True if the coherence result reports a critical contradiction.
headers property ¶
Collect CRP headers from nested coherence/completeness results.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Merged header dictionary produced by nested result objects, if any. |
SubAgentResult dataclass ¶
A SUB_AGENT_RESULT audit event linking a sub-agent's chain (§8.1).
Attributes:
| Name | Type | Description |
|---|---|---|
sub_agent_session_id | str | Session identifier of the sub-agent that produced the result. |
sub_agent_chain_tip | str | Independently-verified HMAC chain tip of the sub-agent session. |
timestamp | str | ISO-8601 UTC timestamp when the linkage event was created. |
event_type | str | Audit event type, always |
to_dict() ¶
Serialize the event to a JSON-friendly dictionary.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Dictionary with event type, sub-agent session id, chain tip, and |
dict[str, str] | timestamp. |
OversightApproval dataclass ¶
A human reviewer's approval of an oversighted response (§6.2).
Attributes:
| Name | Type | Description |
|---|---|---|
session_id | str | Session that produced the halted response. |
window_id | str | Window identifier of the halted response. |
reviewer_id | str | Identifier of the human reviewer granting approval. |
approval_timestamp | str | ISO-8601 UTC timestamp of the approval. |
signing_payload() ¶
Build the HMAC signing payload bound to this approval.
The payload binds the token to session_id + window_id so a token issued for one window cannot release another.
Returns:
| Type | Description |
|---|---|
bytes | UTF-8 encoded string of the joined approval fields. |
DelegationCheck dataclass ¶
DelegationLimits dataclass ¶
Per-agent delegation controls (CRP-SPEC-012 §7.2).
GovernedAction ¶
One-shot governed action executor.
Usage::
ga = GovernedAction(
session_id="s-1",
kill_switch=KillSwitch(),
trust_monitor=TrustMonitor("s-1"),
memory=MemoryAuthorityLattice(),
temporal_ckf=TemporalCKF(),
world_model=WorldModel([]),
governor=AutonomyGovernor(),
)
result = ga.execute(
state={"goal": "deploy"},
action="deploy",
risk="HIGH",
execute_fn=lambda s, a, p: {"status": "deployed"},
checkpoint_fn=lambda r, p, s: {"status": "checkpoint"},
entropy_samples=["sample A", "sample B"],
)
execute(state, action, risk, execute_fn, checkpoint_fn, *, action_kind=AutonomyAction.HIGH_RISK, entropy_samples=None, btf_subject=None, btf_predicate=None, memory_key=None, memory_value=None) ¶
GovernedActionResult dataclass ¶
Result of a governed action execution.
to_dict() ¶
Serialize result to a dict.
RuntimeGovernorConfig dataclass ¶
Configuration for the runtime governance bridge.
classify_budget(budget) ¶
Map a budget value to its health band and circuit state (§2.3, §5.1).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
budget | float | Remaining safety budget, typically in the range [0.0, 1.0]. | required |
Returns:
| Type | Description |
|---|---|
BudgetHealth | A tuple of ( |
CircuitState | threshold rules defined in CRP-SPEC-012. |
aggregate_sub_agent_quality(parent_query, sub_agent_responses, *, embedder=None, nli=None) ¶
Run cross-agent coherence + completeness over fan-in responses (§8.3).
Detects contradictions between sub-agent responses (each response is checked against the ones merged before it) and verifies that the union of responses answers parent_query. Imported lazily so :mod:crp.agent stays independent of the provenance package at import time.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parent_query | str | Original query the sub-agents were asked to address. | required |
sub_agent_responses | list[str] | Individual response strings from each sub-agent. | required |
embedder | Callable[[str], Sequence[float]] | None | Optional embedding function for completeness verification. | None |
nli | Callable[[str, str], float] | None | Optional natural-language inference helper for contradiction detection. | None |
Returns:
| Type | Description |
|---|---|
FanInQualityResult | A |
FanInQualityResult | contradiction counts. |
fan_in_hmac(parent_hmacs, key) ¶
Merge multiple parent window HMACs into one fan-in HMAC (sorted, §3 / SPEC-004).
Sorting makes the merge order-independent so the same set of parents always produces the same fan-in tip.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parent_hmacs | list[str] | List of parent window HMACs to merge. | required |
key | bytes | HMAC signing key. | required |
Returns:
| Type | Description |
|---|---|
str | Hexadecimal HMAC-SHA256 digest of the sorted parent tips. |
link_sub_agent_hmac(*, orchestrator_session_id, window_number, response_hash, prev_window_hmac, sub_agent_chain_tip, key) ¶
Compute the orchestrator window HMAC incorporating a sub-agent tip (§8.1).
HMAC-SHA256(session_id ‖ window ‖ response_hash ‖ prev_hmac ‖ sub_tip, key) creates a cryptographic link between the two chains without merging them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
orchestrator_session_id | str | Identifier of the orchestrator session. | required |
window_number | int | Window index being sealed. | required |
response_hash | str | Hash of the response content for this window. | required |
prev_window_hmac | str | HMAC of the previous orchestrator window. | required |
sub_agent_chain_tip | str | HMAC chain tip from the sub-agent session. | required |
key | bytes | HMAC signing key. | required |
Returns:
| Type | Description |
|---|---|
str | Hexadecimal HMAC-SHA256 digest linking the orchestrator window to the |
str | sub-agent chain. |
verify_sub_agent_link(event, verified_chain_tip) ¶
Confirm a sub-agent's independently-verified tip matches the record (§8.2).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event | SubAgentResult | Audit event containing the recorded sub-agent chain tip. | required |
verified_chain_tip | str | Tip obtained by independently verifying the sub-agent's chain. | required |
Returns:
| Type | Description |
|---|---|
bool | True when the recorded tip equals the verified tip in constant time. |
issue_oversight_token(approval, secret) ¶
Issue a CRP-Oversight-Token value for an approved response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
approval | OversightApproval | Approval record identifying the session, window, reviewer, and timestamp. | required |
secret | bytes | HMAC secret shared by the oversight issuer and verifier. | required |
Returns:
| Type | Description |
|---|---|
str | The full token string, including the |
now_iso() ¶
Current UTC timestamp in ISO-8601 (helper for building approvals).
Returns:
| Type | Description |
|---|---|
str | ISO-8601 formatted UTC timestamp string. |
verify_oversight_token(token, approval, secret) ¶
Constant-time validation that token approves approval (§6.2).
The token's scope is bound to session_id + window_id via the signing payload, so a token issued for one window cannot release another.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
token | str | Token presented by the client in | required |
approval | OversightApproval | Expected approval record against which to validate. | required |
secret | bytes | HMAC secret used to issue the token. | required |
Returns:
| Type | Description |
|---|---|
bool | True if the token is well-formed and its signature matches the expected |
bool | value in constant time. |
build_downstream_headers(parent_headers, *, parent_session_id, loop_depth) ¶
Construct the header set an orchestrator forwards to a sub-agent (§3.1).
Copies the propagating headers from the parent context, sets CRP-Agent-Session-Parent to the orchestrator session, and increments CRP-Agent-Loop-Depth.
check_delegation(limits, *, loop_depth, delegations_made, dag_nodes, strategy=None) ¶
Validate a delegation against loop-depth / fan-out / DAG / strategy limits.
filter_upstream_headers(sub_agent_headers) ¶
Select the headers a sub-agent surfaces back to the orchestrator (§3.2).
agent.autonomy¶
crp.agent.autonomy ¶
Autonomy-by-measurement - measured reliability → enforced autonomy tier (SPEC-026).
CRP assigns an agent an autonomy tier from measured evidence, not from a config flag. The inputs are:
asr(attack success rate): any consequential successful attack is a hard ceiling on autonomy.pass_hat_k: unbiased pass@k from verification / benchmark samples.verification_rate: fraction of produced claims that were verified.n: number of samples behind the pass@k estimate.
Tiers
T0 - supervised: every action gated by human/ checkpoint. T1 - constrained: deterministic tools only, grounding required. T2 - conditional: tool use allowed, HIGH-risk actions simulated. T3 - autonomous: routine operation without human-in-the-loop.
The governor is a small, deterministic function so it can be invoked in the hot path of every agent dispatch without ML inference.
AutonomyTier ¶
Bases: str, Enum
Autonomy tiers ordered from least to most autonomous.
AutonomyAction ¶
Bases: str, Enum
Canonical actions an agent may attempt, from low to high risk.
AutonomyMetrics dataclass ¶
Measured evidence used to assign an autonomy tier.
AutonomyDecision dataclass ¶
Outcome of a tier assignment and action authorization.
to_dict() ¶
Serialize to a dict.
AutonomyGovernor ¶
Assign autonomy tiers from measured reliability and enforce action policy.
Usage::
gov = AutonomyGovernor()
metrics = AutonomyMetrics(asr=0.0, pass_k=0.92, verification_rate=0.91, n_samples=40)
tier = gov.assign_tier(metrics)
decision = gov.authorize(tier, AutonomyAction.HIGH_RISK)
assign_tier(metrics) ¶
Return the autonomy tier implied by metrics.
Rules (most restrictive wins): 1. ASR > 0.05 or < 10 samples → T0 supervised. 2. ASR > 0 or pass@k < 0.90 or verification < 0.70 → T1 constrained. 3. pass@k >= 0.90 and verification >= 0.90 and n >= 30 → T3 autonomous. 4. Otherwise (pass@k >= 0.90, verification >= 0.70) → T2 conditional.
authorize(tier, action) ¶
Return whether action is permitted at tier.
Policy matrix
T0: only READ allowed (everything else → checkpoint). T1: READ + TOOL with grounding. T2: READ + TOOL + WRITE; HIGH_RISK simulated/gated. T3: all actions allowed, including DELEGATE.
enforce(metrics, action, *, kill_switch=None) ¶
Assign tier and authorize action in one call.
If kill_switch is provided and the metrics show a severe trust collapse (ASR > 0.10), the kill-switch is fired.
agent.budget¶
crp.agent.budget ¶
Safety Budget + circuit breaker (CRP-SPEC-012 §2, §5; CRP-SPEC-015).
The Safety Budget is a session-scoped, header-observable risk-accumulation signal. Every session starts at 1.0; each delivered response decrements it by an amount keyed to the DPE risk level. When the budget crosses thresholds, the gateway escalates oversight and ultimately halts the session - the AI equivalent of a distributed-systems circuit breaker.
Relevant specifications
- CRP-SPEC-012: Multi-Agent Safety
- CRP-SPEC-015: Security & Privacy
PRIVATE REFERENCE IMPLEMENTATION - SPEC-012 internals are not published. This module lives in the closed-source crp package only.
CircuitState ¶
Bases: str, Enum
Circuit-breaker state (CRP-SPEC-012 §5.1).
Attributes:
| Name | Type | Description |
|---|---|---|
CLOSED | Normal operation; budget is above the half-open threshold. | |
HALF_OPEN | Cautious operation; human review may be required. | |
OPEN | Session halted; the gateway responds with HTTP 451. |
BudgetHealth ¶
Bases: str, Enum
Budget health band (CRP-SPEC-012 §2.3).
Attributes:
| Name | Type | Description |
|---|---|---|
HEALTHY | Budget above 0.50. | |
CAUTION | Budget between 0.25 and 0.50 inclusive. | |
LOW | Budget between 0.10 and 0.24. | |
DEPLETED | Budget at or below 0.10 but still positive. | |
EXHAUSTED | Budget at or below 0.00. |
BudgetDecision dataclass ¶
Outcome of accounting a risk event against the budget.
Attributes:
| Name | Type | Description |
|---|---|---|
budget | float | Remaining safety budget after the event. |
health | BudgetHealth | Human-readable health band for the remaining budget. |
circuit_state | CircuitState | Current circuit-breaker state. |
http_status | int | None | HTTP status to return when the session is halted, or None. |
force_oversight | bool | Whether the gateway should force human review. |
warning | str | None | Short warning label for CRP-Safety-Budget-Warning header. |
retry_after | str | None | Retry guidance for halted sessions, or None. |
halted property ¶
Return True if the session has been halted (HTTP 451).
headers property ¶
CRP headers describing the current budget state.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Mapping of CRP header names to header values, including the |
dict[str, str] | remaining budget and any warning/oversight/retry directives. |
AgentSafetyBudget dataclass ¶
Session-scoped safety budget (CRP-SPEC-012 §2).
The authoritative budget value lives in the signed session token; this object is the gateway-side accountant. Decrements are computed server-side only (anti-inflation, §10.1) and the budget never recovers within a session (§2.4).
Attributes:
| Name | Type | Description |
|---|---|---|
budget | float | Current remaining safety budget, initialised to |
decrements | dict[RiskLevel, float] | Mapping from |
health property ¶
Return the current BudgetHealth band.
circuit_state property ¶
Return the current CircuitState.
peek() ¶
Return the current decision without applying any decrement.
Returns:
| Type | Description |
|---|---|
BudgetDecision | A |
account(risk_level, *, is_redispatch=False) ¶
Decrement the budget for a delivered response's risk level (§2.2).
Re-dispatches do not decrement (§2.5) - only the final delivered response counts.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
risk_level | RiskLevel | None | DPE risk level of the delivered response, or None if the response carries no risk classification. | required |
is_redispatch | bool | When True, the event is a re-dispatch and must not decrement the budget. | False |
Returns:
| Type | Description |
|---|---|
BudgetDecision | The resulting |
merge_downstream(sub_agent_budget) ¶
Fan-in merge: orchestrator budget = min of self and sub-agent (§5.3).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
sub_agent_budget | float | Remaining safety budget reported by a sub-agent. | required |
Returns:
| Type | Description |
|---|---|
BudgetDecision | The resulting |
classify_budget(budget) ¶
Map a budget value to its health band and circuit state (§2.3, §5.1).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
budget | float | Remaining safety budget, typically in the range [0.0, 1.0]. | required |
Returns:
| Type | Description |
|---|---|
BudgetHealth | A tuple of ( |
CircuitState | threshold rules defined in CRP-SPEC-012. |
agent.chain¶
crp.agent.chain ¶
Cross-agent provenance linking (CRP-SPEC-012 §8; CRP-SPEC-011).
Links two sessions' HMAC provenance chains without merging them: when a sub-agent result is consumed, its chain tip is folded into the orchestrator's next window HMAC, and a SUB_AGENT_RESULT event records the linkage for auditor traversal.
Relevant specifications
- CRP-SPEC-011: Audit Trail
- CRP-SPEC-012: Multi-Agent Safety
PRIVATE REFERENCE IMPLEMENTATION - SPEC-012 internals are not published.
SubAgentResult dataclass ¶
A SUB_AGENT_RESULT audit event linking a sub-agent's chain (§8.1).
Attributes:
| Name | Type | Description |
|---|---|---|
sub_agent_session_id | str | Session identifier of the sub-agent that produced the result. |
sub_agent_chain_tip | str | Independently-verified HMAC chain tip of the sub-agent session. |
timestamp | str | ISO-8601 UTC timestamp when the linkage event was created. |
event_type | str | Audit event type, always |
to_dict() ¶
Serialize the event to a JSON-friendly dictionary.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Dictionary with event type, sub-agent session id, chain tip, and |
dict[str, str] | timestamp. |
FanInQualityResult dataclass ¶
Aggregate coherence/completeness over fan-in sub-agent responses (§8.3).
When an orchestrator merges several sub-agent results it must check that the combined answer is internally consistent (no cross-agent contradictions) and that, together, the sub-agents covered the parent query. This reuses RQA Stage 6 (cross-window coherence) and Stage 8 (completeness).
Attributes:
| Name | Type | Description |
|---|---|---|
coherence | object | None | Result of cross-agent coherence checking, or None if not run. |
completeness | object | None | Completeness result versus the parent query, or None. |
contradiction_count | int | Total number of contradictions detected across all pairwise comparisons. |
is_coherent property ¶
Return True when no contradictions were detected.
has_critical property ¶
Return True if the coherence result reports a critical contradiction.
headers property ¶
Collect CRP headers from nested coherence/completeness results.
Returns:
| Type | Description |
|---|---|
dict[str, str] | Merged header dictionary produced by nested result objects, if any. |
link_sub_agent_hmac(*, orchestrator_session_id, window_number, response_hash, prev_window_hmac, sub_agent_chain_tip, key) ¶
Compute the orchestrator window HMAC incorporating a sub-agent tip (§8.1).
HMAC-SHA256(session_id ‖ window ‖ response_hash ‖ prev_hmac ‖ sub_tip, key) creates a cryptographic link between the two chains without merging them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
orchestrator_session_id | str | Identifier of the orchestrator session. | required |
window_number | int | Window index being sealed. | required |
response_hash | str | Hash of the response content for this window. | required |
prev_window_hmac | str | HMAC of the previous orchestrator window. | required |
sub_agent_chain_tip | str | HMAC chain tip from the sub-agent session. | required |
key | bytes | HMAC signing key. | required |
Returns:
| Type | Description |
|---|---|
str | Hexadecimal HMAC-SHA256 digest linking the orchestrator window to the |
str | sub-agent chain. |
verify_sub_agent_link(event, verified_chain_tip) ¶
Confirm a sub-agent's independently-verified tip matches the record (§8.2).
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
event | SubAgentResult | Audit event containing the recorded sub-agent chain tip. | required |
verified_chain_tip | str | Tip obtained by independently verifying the sub-agent's chain. | required |
Returns:
| Type | Description |
|---|---|
bool | True when the recorded tip equals the verified tip in constant time. |
fan_in_hmac(parent_hmacs, key) ¶
Merge multiple parent window HMACs into one fan-in HMAC (sorted, §3 / SPEC-004).
Sorting makes the merge order-independent so the same set of parents always produces the same fan-in tip.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parent_hmacs | list[str] | List of parent window HMACs to merge. | required |
key | bytes | HMAC signing key. | required |
Returns:
| Type | Description |
|---|---|
str | Hexadecimal HMAC-SHA256 digest of the sorted parent tips. |
aggregate_sub_agent_quality(parent_query, sub_agent_responses, *, embedder=None, nli=None) ¶
Run cross-agent coherence + completeness over fan-in responses (§8.3).
Detects contradictions between sub-agent responses (each response is checked against the ones merged before it) and verifies that the union of responses answers parent_query. Imported lazily so :mod:crp.agent stays independent of the provenance package at import time.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
parent_query | str | Original query the sub-agents were asked to address. | required |
sub_agent_responses | list[str] | Individual response strings from each sub-agent. | required |
embedder | Callable[[str], Sequence[float]] | None | Optional embedding function for completeness verification. | None |
nli | Callable[[str, str], float] | None | Optional natural-language inference helper for contradiction detection. | None |
Returns:
| Type | Description |
|---|---|
FanInQualityResult | A |
FanInQualityResult | contradiction counts. |
agent.oversight¶
crp.agent.oversight ¶
Human-oversight token flow (CRP-SPEC-012 §6.2; CRP-SPEC-011).
When a response is halted (HTTP 451) and a human reviewer approves it, an oversight token is issued. The client retries with CRP-Oversight-Token: approved:sha256:<sig>; the gateway validates it and releases the halted response. The safety budget is NOT replenished - the human has merely accepted the logged risk.
Relevant specifications
- CRP-SPEC-011: Audit Trail
- CRP-SPEC-012: Multi-Agent Safety
PRIVATE REFERENCE IMPLEMENTATION - SPEC-012 internals are not published.
OversightApproval dataclass ¶
A human reviewer's approval of an oversighted response (§6.2).
Attributes:
| Name | Type | Description |
|---|---|---|
session_id | str | Session that produced the halted response. |
window_id | str | Window identifier of the halted response. |
reviewer_id | str | Identifier of the human reviewer granting approval. |
approval_timestamp | str | ISO-8601 UTC timestamp of the approval. |
signing_payload() ¶
Build the HMAC signing payload bound to this approval.
The payload binds the token to session_id + window_id so a token issued for one window cannot release another.
Returns:
| Type | Description |
|---|---|
bytes | UTF-8 encoded string of the joined approval fields. |
issue_oversight_token(approval, secret) ¶
Issue a CRP-Oversight-Token value for an approved response.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
approval | OversightApproval | Approval record identifying the session, window, reviewer, and timestamp. | required |
secret | bytes | HMAC secret shared by the oversight issuer and verifier. | required |
Returns:
| Type | Description |
|---|---|
str | The full token string, including the |
verify_oversight_token(token, approval, secret) ¶
Constant-time validation that token approves approval (§6.2).
The token's scope is bound to session_id + window_id via the signing payload, so a token issued for one window cannot release another.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
token | str | Token presented by the client in | required |
approval | OversightApproval | Expected approval record against which to validate. | required |
secret | bytes | HMAC secret used to issue the token. | required |
Returns:
| Type | Description |
|---|---|
bool | True if the token is well-formed and its signature matches the expected |
bool | value in constant time. |
now_iso() ¶
Current UTC timestamp in ISO-8601 (helper for building approvals).
Returns:
| Type | Description |
|---|---|
str | ISO-8601 formatted UTC timestamp string. |
agent.propagation¶
crp.agent.propagation ¶
Multi-agent header propagation + delegation limits (CRP-SPEC-012 §3, §10.3).
Defines which CRP headers flow downstream (orchestrator → sub-agent) and upstream (sub-agent → orchestrator), the fan-in budget merge, and the loop-depth / delegation / DAG-node guards that prevent unbounded chains.
PRIVATE REFERENCE IMPLEMENTATION - SPEC-012 internals are not published.
DelegationLimits dataclass ¶
Per-agent delegation controls (CRP-SPEC-012 §7.2).
DelegationCheck dataclass ¶
build_downstream_headers(parent_headers, *, parent_session_id, loop_depth) ¶
Construct the header set an orchestrator forwards to a sub-agent (§3.1).
Copies the propagating headers from the parent context, sets CRP-Agent-Session-Parent to the orchestrator session, and increments CRP-Agent-Loop-Depth.
filter_upstream_headers(sub_agent_headers) ¶
Select the headers a sub-agent surfaces back to the orchestrator (§3.2).
check_delegation(limits, *, loop_depth, delegations_made, dag_nodes, strategy=None) ¶
Validate a delegation against loop-depth / fan-out / DAG / strategy limits.
agent.runtime_governance¶
crp.agent.runtime_governance ¶
Runtime governance bridge - wires Wave 2 modules into a single action path.
This module activates the previously inert SPEC-051/055/057 code at runtime by exposing one GovernedAction helper. A call to execute() runs:
- Autonomy tier check (ASR/pass^k → allowed action).
- Trust-monitor observation of the proposed action.
- Predictive-positioning simulation for HIGH-risk actions (SPEC-051).
- Epistemic adjustment from semantic entropy of sample outputs (SPEC-055).
- Bi-temporal CKF grounding lookup (SPEC-057).
- Memory write with authority-lattice enforcement (SPEC-045).
The bridge is opt-in: existing orchestrator paths keep working unchanged; callers (such as the Agent SDK or Gateway) instantiate it when they want the full Wave-2 governance stack.
GovernedActionResult dataclass ¶
Result of a governed action execution.
to_dict() ¶
Serialize result to a dict.
RuntimeGovernorConfig dataclass ¶
Configuration for the runtime governance bridge.
GovernedAction ¶
One-shot governed action executor.
Usage::
ga = GovernedAction(
session_id="s-1",
kill_switch=KillSwitch(),
trust_monitor=TrustMonitor("s-1"),
memory=MemoryAuthorityLattice(),
temporal_ckf=TemporalCKF(),
world_model=WorldModel([]),
governor=AutonomyGovernor(),
)
result = ga.execute(
state={"goal": "deploy"},
action="deploy",
risk="HIGH",
execute_fn=lambda s, a, p: {"status": "deployed"},
checkpoint_fn=lambda r, p, s: {"status": "checkpoint"},
entropy_samples=["sample A", "sample B"],
)