genichin/gitea-agent
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

[verified] Document broker renew/status response contracts

Browse Source
This commit is contained in:
gitea-spec-agent
2026-10-12 05:20:11 +00:00
parent b270c2ce30
commit 7b4b5e72f3
3 changed files with 112 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
harness/agents/review/skills/gitea-code-review/references/native-review.md
+39
View File
@@ -50,6 +50,45 @@ The request callback is `authenticated_request(relative_api_path, payload=None)
`ApiAdapter.snapshot(target)` collects repository/Issue/PR metadata, identity/spec identity, all changed files, commits, reviews, historical review comments, Issue/PR comments and head statuses. Use this same collector for the baseline and subsequent snapshots. Every collection records contiguous 50-item pages, declared totals and Link headers; duplicates, inconsistent totals and truncated enumeration fail closed. A saved older collector snapshot may be replayed if it provides these complete facts, but differently shaped collectors must not be mixed for live source-drift comparison.
### Broker response preflight before publication
Use the [operation-specific broker response contract](../../../../../operations/repository-cache.md#operation-specific-broker-responses). `renew` supplies only `status`/`deadline`; read `repository_held` and identity from a separate `status` request. Python uses `ttl=`, not the wire/CLI name `ttl_seconds`. Keep the admitted handle and the retained canonical `harness/lib/managed_lock_broker.py` module as `broker`; do not read its token or load another profile's helper.
The following is a bounded caller example, not a new adapter or live publish CLI. `broker_handle`, `ttl_seconds`, `absolute_cache_policy`, `plan` and `native_review` are already-admitted workflow inputs. Renew before expiry, reject errors/missing or mistyped fields before publication, and pass the new deadline to the existing lease checker:
```python
import math
import time
try:
renewed = broker.request_handle(broker_handle, "renew", ttl=ttl_seconds)
except Exception:
raise RuntimeError("broker renew unavailable before publication") from None
if (type(renewed) is not dict or "error" in renewed
or set(renewed) != {"status", "deadline"}
or renewed["status"] not in ("held", "repository-held")
or type(renewed["deadline"]) not in (int, float)
or not math.isfinite(renewed["deadline"])
or time.monotonic() >= renewed["deadline"]):
raise RuntimeError("broker renew response rejected before publication")
try:
status = broker.request_handle(broker_handle, "status")
except Exception:
raise RuntimeError("broker status unavailable before publication") from None
if (type(status) is not dict or "error" in status
or type(status.get("repository_held")) is not bool
or status.get("status") != renewed["status"]
or status.get("deadline") != renewed["deadline"]):
raise RuntimeError("broker status response rejected before publication")
deadline_monotonic = renewed["deadline"]
lease = native_review.BrokerIssueLease(
broker_handle, absolute_cache_policy, deadline_monotonic)
lease.check(plan)
# Continue with the existing source/adoption/publication gates below.
```
`repository_held` is an observation, not an additional publication permission or a requirement to acquire/release the repository lock here. The existing lease checker re-reads authoritative broker status and validates identity/source; the two preliminary responses alone do not authorize a POST. A failure before calling `publish` means this wrapper has not invoked a POST, not that a prior uncertain attempt is absent. Keep the existing journal and publication result, report this phase separately, and do not automatically release/reacquire the lease, retry POST, or repeat completed review/suite work. Canonical cleanup remains unchanged.
## Live integration
After absolute root discovery, role-authenticated transport capability validation, complete review, and Issue lease acquisition, load the module once using `importlib.util.spec_from_file_location` and retain it. These are existing workflow objects, **not** placeholders for an alternative credential source: