feat(types): add Fiduciary Circuit Breaker risk extension

[ravyg]

Summary

Adds structured risk signal types for AP2 Section 7.4 (Risk Signals), introducing a Fiduciary Circuit Breaker (FCB) pattern for runtime governance of autonomous agent transactions.

FCB enables standardized trip conditions, state-based controls, and human escalation to mitigate risky or anomalous behavior beyond mandate-based authorization.

---

Changes

• Add Python types: src/ap2/types/risk.py
• Add Go types: samples/go/pkg/ap2/types/risk.go
• Add docs: docs/topics/fiduciary-circuit-breaker.md
• Export types in src/ap2/types/__init__.py
• Update navigation in mkdocs.yml

---

Features

• Trip conditions: value, cumulative, velocity, anomaly, extensible
• Governance state machine: CLOSED → OPEN → HALF_OPEN → TERMINATED
• Structured risk signals for issuer/network visibility
• Human escalation support

---

Tests

• Go: 11 tests (constants, helpers, JSON, integration scenario)
• Python: 22 tests (enums, models, round-trip, scenario)
• Minor formatting fix in risk.go
• Locally tested with MCP integration
  • Tested local MCP calling create_quotes with values ($450, $8000, $11250) - Confirmed FCB correctly passed low-value quotes, triggered warning at 80% threshold, and blocked quotes exceeding $10,000 with escalation ID generated.

---

Compatibility

Additive only — no breaking changes.

Fixes #163

[gemini-code-assist]

Summary of Changes

Hello @ravyg, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request significantly enhances the Agent Payments Protocol (AP2) by integrating a Fiduciary Circuit Breaker (FCB) extension. This new capability provides a crucial layer of runtime governance, allowing for real-time monitoring of autonomous agent behavior beyond static mandate checks. By defining clear risk signals, a state-based control mechanism, and human escalation protocols, the FCB aims to proactively mitigate anomalous or high-risk transactions, thereby increasing trust and security within the agentic commerce ecosystem.

Highlights

• Fiduciary Circuit Breaker (FCB) Introduction: Introduces the Fiduciary Circuit Breaker (FCB) pattern for real-time governance of autonomous agent transactions, complementing existing mandate-based authorization.
• Structured Risk Signal Types: Adds structured risk signal types for AP2 Section 7.4, enabling standardized trip conditions, state-based controls, and human escalation to mitigate risky or anomalous behavior.
• FCB State Machine and Trip Conditions: Defines a state machine for FCB (CLOSED, OPEN, HALF_OPEN, TERMINATED) and various trip conditions (e.g., VALUE_THRESHOLD, CUMULATIVE_THRESHOLD, VELOCITY, ANOMALY) to manage agent autonomy based on risk evaluation.
• Multi-language Type Definitions: Implements comprehensive Python and Go type definitions for all FCB components, ensuring consistent data structures across different language environments.
• Comprehensive Documentation and Testing: Provides detailed documentation for the FCB extension, including conceptual models and usage examples, alongside extensive unit and integration tests for both Go and Python implementations.

🧠 New Feature in Public Preview: You can now enable Memory to help Gemini Code Assist learn from your team's feedback. This makes future code reviews more consistent and personalized to your project's style. Click here to enable Memory in your admin console.

Changelog

• .cspell/custom-words.txt
  • Added new terms "Nygard", "sess", and "txns" to the custom spell-check dictionary.
• .gitleaks.toml
  • Introduced a new Gitleaks configuration file to allowlist specific AP2 data key patterns and file paths, preventing false positives during secret scanning.
• docs/topics/fiduciary-circuit-breaker.md
  • Added new documentation detailing the Fiduciary Circuit Breaker (FCB) extension, covering its purpose, conceptual model, states, trip conditions, and usage examples in AP2 messages.
• mkdocs.yml
  • Updated the documentation navigation structure to include the new "Fiduciary Circuit Breaker" topic.
• samples/go/pkg/ap2/types/risk.go
  • Implemented new Go types for the FCB risk extension, including enums for trip conditions, states, and decisions, along with structs for TripConditionResult, HumanEscalation, FCBEvaluation, and RiskPayload.
• samples/go/pkg/ap2/types/risk_test.go
  • Added comprehensive unit tests for the Go FCB risk types, covering enum values, struct initialization, JSON serialization, and a full evaluation scenario.
• src/ap2/types/init.py
  • Updated the init.py file to export all newly defined Python FCB risk types, making them accessible from the ap2.types package.
• src/ap2/types/risk.py
  • Implemented new Python Pydantic models for the FCB risk extension, defining data structures for TripConditionType, TripConditionStatus, FCBState, AgentModality, EscalationDecision, TripConditionResult, HumanEscalation, FCBEvaluation, and RiskPayload.
• tests/test_risk.py
  • Added extensive unit and integration tests for the Python FCB risk types, verifying enum definitions, model validation (including risk score bounds), JSON serialization, and a detailed B2B quote scenario.

Activity

• Initial commit introducing the Fiduciary Circuit Breaker (FCB) extension.
• Comprehensive Go and Python type definitions and associated tests were added.
• Detailed documentation for the FCB pattern was created and integrated into the project's documentation.
• Local testing was performed with MCP integration, confirming correct FCB behavior for various quote values (passing low values, warning at 80% threshold, blocking exceeding $10,000).

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request introduces a Fiduciary Circuit Breaker (FCB) risk extension, a significant feature for runtime governance of agent transactions. The changes are comprehensive, including new types for both Python and Go, extensive documentation, and thorough test suites for both languages. The implementation quality is very high across the board. The code is clean, well-structured, and idiomatic. The documentation is clear and detailed, and the tests cover a wide range of cases including unit, serialization, and complete end-to-end scenarios. My review includes a few minor suggestions for the Go implementation to add comments to exported struct fields, enhancing clarity and aligning them with the well-documented Python models. Overall, this is an excellent contribution.

[ravyg]

@holtskinner @joshlund-goog please review, thanks!