brawny 0.1.13__py3-none-any.whl → 0.1.22__py3-none-any.whl

brawny/cli/commands/signer.py

@@ -40,20 +40,39 @@ def signer() -> None:
 
 @signer.command("force-reset")
 @click.argument("address_or_alias")
+@click.option("--target-nonce", "-n", type=int, default=None,
+              help="Explicit target nonce to reset to")
+@click.option("--use-rpc-pending", is_flag=True,
+              help="Use RPC pending nonce as target (required if --target-nonce not set)")
+@click.option("--reason", "-r", default=None,
+              help="Reason for reset (required for audit trail)")
 @click.option("--yes", "-y", is_flag=True, help="Skip confirmation prompt")
 @click.option("--config", "config_path", default=None, help="Path to config.yaml")
-def force_reset(address_or_alias: str, yes: bool, config_path: str | None) -> None:
+def force_reset(
+    address_or_alias: str,
+    target_nonce: int | None,
+    use_rpc_pending: bool,
+    reason: str | None,
+    yes: bool,
+    config_path: str | None,
+) -> None:
     """Force reset nonce state for a signer. USE WITH CAUTION.
 
     ADDRESS_OR_ALIAS can be:
       - Full address: 0x1234567890abcdef1234567890abcdef12345678
       - Signer alias: hot-wallet-1
 
+    You must specify either --target-nonce or --use-rpc-pending:
+
+    \b
+      brawny signer force-reset 0x... --target-nonce 42 --reason "stuck tx"
+      brawny signer force-reset 0x... --use-rpc-pending --reason "gap recovery"
+
     This will:
-    - Query current chain pending nonce
-    - Reset local next_nonce to match chain
-    - Release all reservations with nonce >= chain_pending_nonce
+    - Reset local next_nonce to the specified target
+    - Release all reservations with nonce >= target
     - Clear gap tracking
+    - Log an audit trail with source and reason
 
     WARNING: If any prior transactions later mine, you may have duplicate
     transactions or nonce conflicts.
@@ -62,10 +81,37 @@ def force_reset(address_or_alias: str, yes: bool, config_path: str | None) -> No
 
     from brawny.config import Config, get_config
     from brawny.db import create_database
-    from brawny._rpc import RPCManager
+    from brawny._rpc.clients import ReadClient
     from brawny.tx.nonce import NonceManager
     from brawny.model.enums import NonceStatus
 
+    # Validate: must specify either --target-nonce or --use-rpc-pending
+    if target_nonce is None and not use_rpc_pending:
+        click.echo(click.style(
+            "Error: Must specify either --target-nonce or --use-rpc-pending",
+            fg="red", bold=True
+        ))
+        click.echo("\nExamples:")
+        click.echo("  brawny signer force-reset 0x... --target-nonce 42 --reason 'stuck tx'")
+        click.echo("  brawny signer force-reset 0x... --use-rpc-pending --reason 'gap recovery'")
+        raise SystemExit(1)
+
+    if target_nonce is not None and use_rpc_pending:
+        click.echo(click.style(
+            "Error: Cannot specify both --target-nonce and --use-rpc-pending",
+            fg="red", bold=True
+        ))
+        raise SystemExit(1)
+
+    # Prompt for reason in interactive mode if not provided
+    if reason is None and not yes:
+        reason = click.prompt("Reason for reset (for audit trail)", default="")
+        if not reason:
+            click.echo(click.style(
+                "Warning: No reason provided. Continuing without audit reason.",
+                fg="yellow"
+            ))
+
     # Load config
     if config_path:
         config = Config.from_yaml(config_path)
@@ -74,14 +120,11 @@ def force_reset(address_or_alias: str, yes: bool, config_path: str | None) -> No
         config = get_config()
 
     # Connect to database
-    db = create_database(
-        config.database_url,
-        pool_size=config.database_pool_size,
-        pool_max_overflow=config.database_pool_max_overflow,
-        pool_timeout=config.database_pool_timeout_seconds,
-        circuit_breaker_failures=config.db_circuit_breaker_failures,
-        circuit_breaker_seconds=config.db_circuit_breaker_seconds,
-    )
+        db = create_database(
+            config.database_url,
+            circuit_breaker_failures=config.db_circuit_breaker_failures,
+            circuit_breaker_seconds=config.db_circuit_breaker_seconds,
+        )
     db.connect()
 
     try:
@@ -89,7 +132,7 @@ def force_reset(address_or_alias: str, yes: bool, config_path: str | None) -> No
         address = resolve_signer_address(db, config.chain_id, address_or_alias)
 
         # Setup RPC and nonce manager
-        rpc = RPCManager.from_config(config)
+        rpc = ReadClient.from_config(config)
         nonce_manager = NonceManager(db, rpc, config.chain_id)
 
         # Get current state
@@ -99,10 +142,13 @@ def force_reset(address_or_alias: str, yes: bool, config_path: str | None) -> No
         signer_state = db.get_signer_state(config.chain_id, address)
         reservations = db.get_reservations_for_signer(config.chain_id, address)
 
+        # Determine effective target nonce
+        effective_target = target_nonce if target_nonce is not None else chain_pending
+
         # Calculate affected reservations
         affected = [
             r for r in reservations
-            if r.nonce >= chain_pending and r.status in (NonceStatus.RESERVED, NonceStatus.IN_FLIGHT)
+            if r.nonce >= effective_target and r.status in (NonceStatus.RESERVED, NonceStatus.IN_FLIGHT)
         ]
 
         # Display current state
@@ -111,6 +157,7 @@ def force_reset(address_or_alias: str, yes: bool, config_path: str | None) -> No
             click.echo(f"Alias: {address_or_alias}")
         click.echo(f"Current chain pending nonce: {chain_pending}")
         click.echo(f"Current local next_nonce: {signer_state.next_nonce if signer_state else 'N/A'}")
+        click.echo(f"Target nonce: {effective_target}" + (" (from RPC)" if use_rpc_pending else " (explicit)"))
         click.echo(f"Reservations to release: {len(affected)}")
 
         if affected:
@@ -130,7 +177,12 @@ def force_reset(address_or_alias: str, yes: bool, config_path: str | None) -> No
                 return
 
         # Execute force reset
-        new_nonce = nonce_manager.force_reset(address)
+        new_nonce = nonce_manager.force_reset(
+            address,
+            source="cli",
+            reason=reason or "no reason provided",
+            target_nonce=effective_target,
+        )
         click.echo(click.style(
             f"\n✓ Reset complete. next_nonce now {new_nonce}",
             fg="green", bold=True
@@ -154,7 +206,7 @@ def status(address_or_alias: str, config_path: str | None) -> None:
 
     from brawny.config import Config, get_config
     from brawny.db import create_database
-    from brawny._rpc import RPCManager
+    from brawny._rpc.clients import ReadClient
     from brawny.model.enums import NonceStatus
 
     # Load config
@@ -165,14 +217,11 @@ def status(address_or_alias: str, config_path: str | None) -> None:
         config = get_config()
 
     # Connect to database
-    db = create_database(
-        config.database_url,
-        pool_size=config.database_pool_size,
-        pool_max_overflow=config.database_pool_max_overflow,
-        pool_timeout=config.database_pool_timeout_seconds,
-        circuit_breaker_failures=config.db_circuit_breaker_failures,
-        circuit_breaker_seconds=config.db_circuit_breaker_seconds,
-    )
+        db = create_database(
+            config.database_url,
+            circuit_breaker_failures=config.db_circuit_breaker_failures,
+            circuit_breaker_seconds=config.db_circuit_breaker_seconds,
+        )
     db.connect()
 
     try:
@@ -180,7 +229,7 @@ def status(address_or_alias: str, config_path: str | None) -> None:
         address = resolve_signer_address(db, config.chain_id, address_or_alias)
 
         # Setup RPC
-        rpc = RPCManager.from_config(config)
+        rpc = ReadClient.from_config(config)
 
         # Get current state
         chain_pending = rpc.get_transaction_count(
@@ -205,6 +254,22 @@ def status(address_or_alias: str, config_path: str | None) -> None:
             click.echo(f"\nLocal State:")
             click.echo(f"  next_nonce: {signer_state.next_nonce}")
             click.echo(f"  last_synced_chain_nonce: {signer_state.last_synced_chain_nonce}")
+            if signer_state.quarantined_at:
+                click.echo(
+                    click.style(
+                        f"  quarantined_at: {signer_state.quarantined_at}",
+                        fg="red",
+                    )
+                )
+                if signer_state.quarantine_reason:
+                    click.echo(
+                        click.style(
+                            f"  quarantine_reason: {signer_state.quarantine_reason}",
+                            fg="red",
+                        )
+                    )
+            if signer_state.replacements_paused:
+                click.echo(click.style("  replacements_paused: true", fg="yellow"))
             if signer_state.gap_started_at:
                 click.echo(click.style(
                     f"  gap_started_at: {signer_state.gap_started_at} (BLOCKED)",
@@ -243,6 +308,58 @@ def status(address_or_alias: str, config_path: str | None) -> None:
         db.close()
 
 
+@signer.command("quarantine")
+@click.argument("address_or_alias")
+@click.option("--reason", "-r", default=None, help="Reason for quarantine")
+@click.option("--config", "config_path", default=None, help="Path to config.yaml")
+def quarantine(address_or_alias: str, reason: str | None, config_path: str | None) -> None:
+    """Quarantine a signer (blocks nonce reservations and broadcasts)."""
+    from brawny.cli.helpers import get_config, get_db
+
+    config = get_config(config_path)
+    db = get_db(config_path)
+    try:
+        address = resolve_signer_address(db, config.chain_id, address_or_alias)
+        updated = db.set_signer_quarantined(
+            config.chain_id,
+            address,
+            reason=reason,
+            actor="cli",
+            source="cli",
+        )
+        if updated:
+            click.echo(f"Signer '{address}' quarantined.")
+        else:
+            click.echo(f"Signer '{address}' not found.", err=True)
+    finally:
+        db.close()
+
+
+@signer.command("unquarantine")
+@click.argument("address_or_alias")
+@click.option("--config", "config_path", default=None, help="Path to config.yaml")
+def unquarantine(address_or_alias: str, config_path: str | None) -> None:
+    """Clear signer quarantine."""
+    from brawny.cli.helpers import get_config, get_db
+
+    config = get_config(config_path)
+    db = get_db(config_path)
+    try:
+        address = resolve_signer_address(db, config.chain_id, address_or_alias)
+        updated = db.clear_signer_quarantined(
+            config.chain_id,
+            address,
+            actor="cli",
+            source="cli",
+        )
+        if updated:
+            click.echo(f"Signer '{address}' unquarantined.")
+        else:
+            click.echo(f"Signer '{address}' not found.", err=True)
+    finally:
+        db.close()
+
+
 def register(main) -> None:
     """Register signer commands with the main CLI."""
     main.add_command(signer)

brawny/cli/helpers.py

@@ -64,9 +64,6 @@ def get_db(config_path: str | None = None):
 
     db = create_database(
         config.database_url,
-        pool_size=config.database_pool_size,
-        pool_max_overflow=config.database_pool_max_overflow,
-        pool_timeout=config.database_pool_timeout_seconds,
         circuit_breaker_failures=config.db_circuit_breaker_failures,
         circuit_breaker_seconds=config.db_circuit_breaker_seconds,
     )

brawny/cli_templates.py

@@ -1,5 +1,7 @@
 """Templates for brawny init command."""
 
+import importlib.resources as resources
+
 PYPROJECT_TEMPLATE = """\
 [build-system]
 requires = ["setuptools>=68.0", "wheel"]
@@ -35,7 +37,7 @@ chain_id: 1
 keystore_type: file
 keystore_path: ~/.brawny/keys
 
-# SQLite requires worker_count: 1. Use PostgreSQL for multi-worker setups.
+# SQLite requires worker_count: 1 (single runner only).
 worker_count: 1
 
 # Prometheus metrics port (default: 9091)
@@ -48,6 +50,21 @@ worker_count: 1
 #     ops: "-1001234567890"
 #   default: ["ops"]
 #   parse_mode: "Markdown"
+#   health_chat: "ops"
+#   health_cooldown_seconds: 1800
+
+# HTTP (optional, for job code)
+# http:
+#   allowed_domains:
+#     - "api.coingecko.com"
+#     - "*.githubusercontent.com"
+#   connect_timeout_seconds: 5
+#   read_timeout_seconds: 10
+#   max_retries: 2
+
+# Debug-only settings (optional, default false)
+# debug:
+#   allow_console: false
 
 # Advanced settings (optional)
 # advanced:
@@ -118,343 +135,7 @@ Thumbs.db
 
 INIT_JOBS_TEMPLATE = '"""Job definitions - auto-discovered from ./jobs."""\n'
 
-AGENTS_TEMPLATE = """
-# Agent Guide: Build a Compliant brawny Job
-
-This file is meant for user agents that generate new job files. It is a fast, practical spec.
-
-## Golden Rules
-- Avoid over-engineering.
-- Aim for simplicity and elegance.
-
-## Job File Checklist (Minimal)
-- Location: `jobs/<job_name>.py`
-- Import `Job` and `job`.
-- Add `@job` decorator (omit it to hide a WIP job from discovery/validation).
-- Implement `check()` (sync or async).
-- If it sends a transaction, implement `build_intent()` (sync).
-
-## Required vs Optional Hooks
-
-### Required
-- `check(self) -> Trigger | None` OR `check(self, ctx) -> Trigger | None`
-  - Must return `trigger(...)` or `None`.
-  - **Implicit style** `def check(self):` - use API helpers (`block`, `kv`, `Contract`, `ctx()`)
-  - **Explicit style** `def check(self, ctx):` - ctx passed directly (param MUST be named 'ctx')
-  - Can be async: `async def check(self)` or `async def check(self, ctx)`
-
-### Required only for tx jobs
-- `build_intent(self, trigger) -> TxIntentSpec`
-  - Build calldata and return `intent(...)`.
-  - Only called if `trigger.tx_required` is True.
-
-### Optional simulation hook
-- `validate_simulation(self, output) -> bool`
-  - Return False to fail the intent after a successful simulation.
-
-### Optional alert hooks
-- `alert_triggered(self, ctx)` - Called when job triggers
-- `alert_confirmed(self, ctx)` - Called after TX confirms (ctx.receipt available)
-- `alert_failed(self, ctx)` - Called on failure (ctx.tx can be None for pre-broadcast failures)
-  - Return `str`, `(str, parse_mode)`, or `None`.
-
-### Optional lifecycle hooks
-- `on_success(self, ctx, receipt, intent, attempt)`
-- `on_failure(self, ctx, error, intent, attempt)`  # attempt can be None pre-broadcast
-
-## Job Class Attributes
-
-### Required (auto-derived if not set and @job is used)
-- `job_id: str` - Stable identifier (must not change)
-- `name: str` - Human-readable name for logs/alerts
-
-### Optional scheduling
-- `check_interval_blocks: int = 1` - Min blocks between check() calls
-- `check_timeout_seconds: int = 30` - Timeout for check()
-- `build_timeout_seconds: int = 10` - Timeout for build_intent()
-- `max_in_flight_intents: int | None = None` - Cap on active intents
-
-### Optional gas overrides (all values in wei)
-- `max_fee: int | None = None` - Max fee cap for gating/txs (None = no gating)
-- `priority_fee: int | None = None` - Tip override for this job
-
-### Optional simulation
-- `disable_simulation: bool = False` - Skip pre-broadcast simulation
-- `rpc: str | None = None` - Override RPC for simulation
-
-### Broadcast routing (via @job decorator)
-Configure broadcast routing using the `@job` decorator:
-```python
-@job(job_id="arb_exec", rpc_group="flashbots", signer="hot1")
-class ArbitrageExecutor(Job):
-    ...
-```
-- `job_id` - Optional override (defaults to snake_case of class name)
-- `rpc_group` - Name of RPC group for reads and broadcasts
-- `broadcast_group` - Name of RPC group for broadcasts (default: uses rpc_default_group)
-- `read_group` - Name of RPC group for read operations (default: uses rpc_default_group)
-- `signer` - Name of signer alias (required for tx jobs)
-
-Define RPC groups in config:
-```yaml
-rpc_groups:
-  primary:
-    endpoints:
-      - https://eth.llamarpc.com
-  private:
-    endpoints:
-      - https://rpc.flashbots.net
-      - https://relay.flashbots.net
-rpc_default_group: primary
-```
-
-### Alert routing
-- `@job(alert_to="ops")` - Route alerts to named chat defined in config
-- `@job(alert_to=["ops", "dev"])` - Route to multiple chats
-- Names must be defined in `telegram.chats` config section
-- If not specified, uses `telegram.default` from config
-
-## Core API (What to Use)
-
-### Contract access (brownie-style)
-```python
-from brawny import Contract
-vault = Contract(self.vault_address)  # By address
-decimals = vault.decimals()            # View call
-data = vault.harvest.encode_input()    # Get calldata
-```
-
-
-### JSON interfaces (brownie-style)
-Place ABI JSON files in `./interfaces`, then:
-```python
-from brawny import interface
-token = interface.IERC20("0x1234...")
-balance = token.balanceOf("0xabc...")
-```
-
-### Job hook helpers (implicit context)
-```python
-from brawny import trigger, intent, block, gas_ok
-return trigger(reason="...", data={...}, idempotency_parts=[block.number])
-return intent(signer_address="worker", to_address=addr, data=calldata)
-```
-
-### Event access in alert hooks (brownie-compatible)
-```python
-def alert_confirmed(self, ctx):
-    deposit = ctx.events["Deposit"][0]  # First Deposit event
-    amount = deposit["amount"]          # Field access
-    if "Deposit" in ctx.events:         # Check if event exists
-        ...
-```
-
-### Other context access
-- `ctx()` - Get full CheckContext/BuildContext when using implicit style
-- `block.number`, `block.timestamp` - Current block info
-- `rpc.*` - RPC manager proxy (e.g., `rpc.get_gas_price()`)
-- `gas_ok()` - Check if current gas is below job's max_fee (async)
-- `gas_quote()` - Get current base_fee (async)
-- `kv.get(key, default=None)`, `kv.set(key, value)` - Persistent KV store (import from brawny)
-
-### Accounts
-- Use `intent(signer_address=...)` with a signer alias or address.
-- If you set `@job(signer="alias")`, use `self.signer` (alias) or `self.signer_address` (resolved address).
-- The signer alias must exist in the accounts directory (`~/.brawny/accounts`).
-
-## Example: Transaction Job
-
-```python
-from brawny import Job, job, Contract, trigger, intent, block
-
-@job(signer="worker")
-class MyKeeperJob(Job):
-    job_id = "my_keeper"
-    name = "My Keeper"
-    check_interval_blocks = 1
-    keeper_address = "0x..."
-
-    def check(self, ctx):
-        keeper = Contract(self.keeper_address)
-        if keeper.canWork():
-            return trigger(
-                reason="Keeper can work",
-                idempotency_parts=[block.number],
-            )
-        return None
-
-    def build_intent(self, trig):
-        keeper = Contract(self.keeper_address)
-        return intent(
-            signer_address=self.signer,
-            to_address=self.keeper_address,
-            data=keeper.work.encode_input(),
-        )
-```
-
-## Example: Job with Custom Broadcast and Alerts
-
-```python
-from brawny import Job, Contract, trigger, intent, explorer_link
-from brawny.jobs.registry import job
-
-@job(rpc_group="flashbots", signer="treasury-signer", alert_to="private_ops")
-class TreasuryJob(Job):
-    \"\"\"Critical treasury operations with dedicated RPC and private alerts.\"\"\"
-
-    name = "Treasury Operations"
-    check_interval_blocks = 1
-    treasury_address = "0x..."
-
-    def check(self, ctx):
-        treasury = Contract(self.treasury_address)
-        if treasury.needsRebalance():
-            return trigger(reason="Treasury needs rebalancing")
-        return None
-
-    def build_intent(self, trig):
-        treasury = Contract(self.treasury_address)
-        return intent(
-            signer_address=self.signer,
-            to_address=self.treasury_address,
-            data=treasury.rebalance.encode_input(),
-        )
-
-    def alert_confirmed(self, ctx):
-        if not ctx.tx:
-            return None
-        return f"Treasury rebalanced: {explorer_link(ctx.tx.hash)}"
-```
-
-## Example: Monitor-Only Job (Implicit Context Style)
-
-```python
-from brawny import Job, job, Contract, trigger, kv
-
-@job
-class MonitorJob(Job):
-    job_id = "monitor"
-    name = "Monitor"
-
-    def check(self):  # No ctx param - uses implicit context
-        value = Contract("0x...").value()
-        last = kv.get("last", 0)
-        if value > last:
-            kv.set("last", value)
-            return trigger(
-                reason="Value increased",
-                data={"value": value},
-                tx_required=False,
-            )
-        return None
-```
-
-## Natural-Language -> Job Translation Guide
-
-When a user says:
-- **"Check X every block"** -> `check_interval_blocks = 1`
-- **"Only run if gas below Y"** -> set `max_fee` (wei) and use `await gas_ok()` in async check()
-- **"Use signer Z"** -> `@job(signer="Z")` and use `self.signer` in `intent(...)`
-- **"Alert on success/failure"** -> implement `alert_confirmed` / `alert_failed`
-- **"Remember last value"** -> use `kv.get/set` (import from brawny)
-- **"Use Flashbots"** -> `@job(rpc_group="flashbots")` with flashbots group in config
-- **"Send alerts to private channel"** -> `@job(alert_to="private_ops")` with chat in config
-
-## Failure Modes
-
-The `alert_failed` hook provides rich context about what failed and when.
-
-### Failure Classification
-
-**FailureType** (what failed):
-- `SIMULATION_REVERTED` - TX would revert on-chain (permanent)
-- `SIMULATION_NETWORK_ERROR` - RPC error during simulation (transient)
-- `DEADLINE_EXPIRED` - Intent took too long (permanent)
-- `SIGNER_FAILED` - Keystore/signer issue
-- `NONCE_FAILED` - Couldn't reserve nonce
-- `SIGN_FAILED` - Signing error
-- `BROADCAST_FAILED` - RPC rejected transaction (transient)
-- `TX_REVERTED` - On-chain revert (permanent)
-- `NONCE_CONSUMED` - Nonce used by another transaction
-- `CHECK_EXCEPTION` - job.check() raised an exception
-- `BUILD_TX_EXCEPTION` - job.build_tx() raised an exception
-- `UNKNOWN` - Fallback for unexpected failures
-
-**FailureStage** (when it failed):
-- `PRE_BROADCAST` - Failed before reaching the chain
-- `BROADCAST` - Failed during broadcast
-- `POST_BROADCAST` - Failed after broadcast (on-chain)
-
-### AlertContext in alert_failed
-
-```python
-# AlertContext fields (all hooks)
-ctx.job                  # JobMetadata (id, name)
-ctx.trigger              # Trigger that initiated this flow
-ctx.chain_id             # Chain ID
-ctx.hook                 # HookType enum (TRIGGERED, CONFIRMED, FAILED)
-ctx.tx                   # TxInfo | None (hash, nonce, gas params)
-ctx.receipt              # TxReceipt | None (only in alert_confirmed)
-ctx.block                # BlockInfo | None
-ctx.error_info           # ErrorInfo | None (structured, JSON-safe)
-ctx.failure_type         # FailureType | None
-ctx.failure_stage        # FailureStage | None
-ctx.events               # EventDict (only in alert_confirmed)
-
-# AlertContext properties
-ctx.is_permanent_failure # True if retrying won't help
-ctx.is_transient_failure # True if failure might resolve on retry
-ctx.error_message        # Convenience: error_info.message or "unknown"
-
-# AlertContext methods
-ctx.explorer_link(hash)  # "[🔗 View](url)" markdown link
-ctx.shorten(hex_str)     # "0x1234...abcd"
-ctx.has_receipt()        # True if receipt available
-ctx.has_error()          # True if error_info available
-```
-
-### Example: Handling Failures
-
-```python
-from brawny import Job, job
-from brawny.model.errors import FailureType
-
-@job
-class RobustJob(Job):
-    job_id = "robust_job"
-    name = "Robust Job"
-
-    def alert_failed(self, ctx):
-        # Suppress alerts for transient failures
-        if ctx.is_transient_failure:
-            return None  # No alert
-
-        # Detailed message for permanent failures
-        if ctx.failure_type == FailureType.SIMULATION_REVERTED:
-            return f"TX would revert: {ctx.error_message}"
-        elif ctx.failure_type == FailureType.TX_REVERTED:
-            if not ctx.tx:
-                return f"TX reverted on-chain: {ctx.error_message}"
-            return f"TX reverted on-chain: {ctx.explorer_link(ctx.tx.hash)}"
-        elif ctx.failure_type == FailureType.NONCE_CONSUMED:
-            return "Nonce conflict! Check signer activity."
-        elif ctx.failure_type == FailureType.CHECK_EXCEPTION:
-            return f"check() crashed: {ctx.error_message}"
-        elif ctx.failure_type == FailureType.BUILD_TX_EXCEPTION:
-            return f"build_intent() crashed: {ctx.error_message}"
-        else:
-            return f"Failed ({ctx.failure_type.value}): {ctx.error_message}"
-```
-
-## Required Output from Agent
-When generating a new job file, the agent must provide:
-- File path
-- Job class name
-- `job_id` and `name`
-- `check()` implementation
-- `build_intent()` if tx required
-- Any alert hooks requested
-"""
+AGENTS_TEMPLATE = resources.files("brawny").joinpath("assets/AGENTS.md").read_text(encoding="utf-8")
 
 EXAMPLES_TEMPLATE = '''\
 """Example job patterns - NOT registered.
@@ -481,7 +162,7 @@ class MonitorOnlyJob(Job):
 
     Outcome:
     - Creates: Trigger only (no intent, no transaction)
-    - Alerts: alert_triggered only
+    - Alerts: on_trigger only
     """
 
     job_id = "monitor_example"
@@ -519,17 +200,12 @@ class MonitorOnlyJob(Job):
         kv.set("last_price", price)
         return None
 
-    def alert_triggered(self, ctx):
-        """Format alert message.
-
-        Returns:
-            Tuple of (message, parse_mode) or string
-        """
-        data = {}
-        return (
+    def on_trigger(self, ctx):
+        """Send alert when monitor triggers."""
+        data = ctx.trigger.data
+        ctx.alert(
             f"Price alert: {data['old_price']:.2f} -> {data['new_price']:.2f}\\n"
-            f"Change: {data['change_percent']:.2f}%",
-            "Markdown",
+            f"Change: {data['change_percent']:.2f}%"
         )
 '''