Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
30 changes: 30 additions & 0 deletions .github/workflows/test.yml
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
name: test

on:
pull_request:
push:
branches: [main]

permissions:
contents: read

concurrency:
group: test-${{ github.workflow }}-${{ github.ref }}
cancel-in-progress: true

jobs:
pytest:
runs-on: ubuntu-latest
timeout-minutes: 10
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: "3.11"
cache: pip
- name: Install development dependencies
run: python -m pip install --upgrade pip && python -m pip install -e '.[dev]'
- name: Compile Python sources
run: python -m py_compile bridge_core/*.py scripts/*.py
- name: Run tests
run: python -m pytest -q
23 changes: 19 additions & 4 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,10 +7,10 @@ It gives you a bounded place to create, receive, track, and close agent-to-agent
## What it does

- creates explicit handoff records between agents
- stores sender and recipient copies on disk for auditability
- stores an authoritative canonical record plus recoverable sender and recipient queue views
- enforces route policy and status transitions
- exposes a local HTTP API for wrappers and automation
- supports immediate lifecycle notifications (`create`, `close`, `block`)
- supports durable at-least-once lifecycle events plus immediate compatibility notifications
- supports read-only event consumers for surfacing lifecycle events into chat/UI adapters
- includes patrol tooling for reminders and unresolved-handoff detection

Expand All @@ -28,7 +28,7 @@ Route policy is optional:

You do **not** need to edit `bridge_core/models.py` or `bridge_core/policy.py` to adopt your own ecosystem.

For deeper docs, start with `docs/README.md`.
For deeper docs, start with `docs/README.md` and `docs/bridge-v2-reliability.md`.

## Repository layout

Expand Down Expand Up @@ -76,7 +76,8 @@ python3 scripts/bridge_cli.py create \
--issue-type task \
--subject "Demo handoff" \
--requested-action "Inspect the repo and report back" \
--minimal-context "Started from the README quickstart"
--minimal-context "Started from the README quickstart" \
--idempotency-key "demo-create-1"
```

You should get JSON like:
Expand Down Expand Up @@ -187,9 +188,23 @@ python3 scripts/bridge_agent.py --agent agent-b close HND-... --outcome "Verifie
- `POST /v1/handoffs/{handoff_id}/ack`
- `POST /v1/handoffs/{handoff_id}/block`
- `POST /v1/handoffs/{handoff_id}/close`
- `POST /v1/handoffs/{handoff_id}/cancel`
- `POST /v1/handoffs/{handoff_id}/status`
- `POST /v1/handoffs/{handoff_id}/archive`

Create accepts `Idempotency-Key` or `idempotency_key`. Lifecycle writes accept `expected_revision` or an `If-Match` header and return HTTP 409 for stale revisions.

Durable outbox and reconciliation commands:

```bash
python3 scripts/bridge_cli.py outbox-list --state pending
python3 scripts/bridge_cli.py outbox-deliver --limit 100
python3 scripts/bridge_cli.py outbox-replay EVT-...
python3 scripts/bridge_cli.py outbox-recover
python3 scripts/bridge_cli.py outbox-resolve-transaction EVT-... --action enqueue --reason "verified missing delivery"
python3 scripts/bridge_cli.py reconcile --check-only
```

## Lifecycle notifications

Bridge supports two layers of notification behavior:
Expand Down
75 changes: 75 additions & 0 deletions bridge_core/events.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,75 @@
from __future__ import annotations

from dataclasses import asdict, dataclass, field
from datetime import datetime, timezone
from typing import Any
from uuid import uuid4

from .models import CURRENT_SCHEMA_VERSION, HandoffRecord, now_iso

DELIVERY_STATES = {"pending", "retrying", "delivered", "dead_letter"}


@dataclass(slots=True)
class LifecycleEvent:
event_id: str
handoff_id: str
event_type: str
revision: int
occurred_at: str
target_agent: str
sender: str
recipient: str
actor: str
status: str
subject: str
resolution_summary: str
correlation_id: str | None = None
causation_id: str | None = None
schema_version: int = CURRENT_SCHEMA_VERSION
attempts: int = 0
next_attempt_at: str = field(default_factory=now_iso)
last_error: str = ""
delivery_state: str = "pending"
external_correlation: dict[str, str] = field(default_factory=dict)

@classmethod
def from_handoff(
cls,
handoff: HandoffRecord,
*,
event_type: str,
actor: str,
target_agent: str,
event_id: str | None = None,
) -> "LifecycleEvent":
return cls(
event_id=event_id or f"EVT-{uuid4().hex}",
handoff_id=handoff.handoff_id,
event_type=event_type,
revision=handoff.revision,
occurred_at=now_iso(),
target_agent=target_agent,
sender=handoff.sender,
recipient=handoff.recipient,
actor=actor,
status=handoff.status,
subject=handoff.subject,
resolution_summary=handoff.resolution_summary,
correlation_id=handoff.correlation_id,
causation_id=handoff.causation_id,
)

@classmethod
def from_mapping(cls, mapping: dict[str, Any]) -> "LifecycleEvent":
allowed = {field_name for field_name in cls.__dataclass_fields__}
values = {key: value for key, value in mapping.items() if key in allowed}
return cls(**values)

def to_dict(self) -> dict[str, Any]:
return asdict(self)

def due(self, now: datetime | None = None) -> bool:
current = now or datetime.now(timezone.utc)
due_at = datetime.fromisoformat(self.next_attempt_at.replace("Z", "+00:00"))
return self.delivery_state in {"pending", "retrying"} and due_at <= current
Loading
Loading