askrobots / dbbasic-object-server
Public
Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.
danq9
signup: the person chooses the password and name on the confirm page
83c7aa6
2 weeks, 5 days ago
History
test_agents.py · 14.9 KB · 346 lines
| 1 | """Agents: liveness, capabilities, and the spend an agent has committed. |
| 2 | |
| 3 | This package exists because of an audit, not an idea. Most of an "agent |
| 4 | runtime" was already on the box — an agent is a user, what it did is the |
| 5 | change log, the coordination feed is `feed_posts` with `claim` and |
| 6 | `release` already in its kinds, and race-free claiming is `expected_rev`. |
| 7 | So the collection had to pass a test before it was allowed to exist: |
| 8 | **every field must be something not derivable from what is already kept.** |
| 9 | |
| 10 | Three things passed, and this file is mostly about the first: |
| 11 | |
| 12 | LIVENESS IS NOT A LAST WRITE. An agent reasoning for ten minutes writes |
| 13 | nothing and is alive; a crashed one looks alive until its last write ages |
| 14 | out. No fold over the change log answers "is it still there", which is |
| 15 | the whole justification for a heartbeat column. |
| 16 | |
| 17 | CAPABILITIES ARE OPT-IN. An agent advertising nothing is routed nothing, |
| 18 | because nobody's machine joins a compute pool by accident. |
| 19 | |
| 20 | SPEND IS A FOLD, NEVER A COUNTER. The cap reads holds and debits out of |
| 21 | the ledger — the same argument hook_wallet_entries makes about |
| 22 | wallets.balance_minor. |
| 23 | """ |
| 24 | |
| 25 | import json |
| 26 | import pathlib |
| 27 | |
| 28 | import pytest |
| 29 | from conftest import stage_collection |
| 30 | |
| 31 | import object_agents |
| 32 | import object_execution |
| 33 | import object_records |
| 34 | import python_object_runtime |
| 35 | |
| 36 | REPO_ROOT = pathlib.Path(__file__).resolve().parents[1] |
| 37 | PACKAGES = REPO_ROOT / "packages" |
| 38 | AGENT_OBJECTS = PACKAGES / "app-agents" / "objects" |
| 39 | RUNTIME = python_object_runtime.PythonObjectRuntime() |
| 40 | |
| 41 | NOW = "2026-07-27T12:00:00Z" |
| 42 | |
| 43 | |
| 44 | def agent(**fields): |
| 45 | row = {"agent_id": "server-agent", "label": "Server Agent", |
| 46 | "status": "active", "heartbeat_at": "2026-07-27T11:58:00Z"} |
| 47 | row.update({k: str(v) for k, v in fields.items()}) |
| 48 | return row |
| 49 | |
| 50 | |
| 51 | # --- the pure module ----------------------------------------------------------- |
| 52 | |
| 53 | def test_liveness_has_three_states_because_up_or_down_is_not_the_question(): |
| 54 | """The useful distinction is 'should I be worried yet'. A missed beat |
| 55 | is ordinary, several is a question, a long silence is an answer.""" |
| 56 | assert object_agents.liveness(agent(), now=NOW) == "live" |
| 57 | assert object_agents.liveness( |
| 58 | agent(heartbeat_at="2026-07-27T11:30:00Z"), now=NOW) == "stale" |
| 59 | assert object_agents.liveness( |
| 60 | agent(heartbeat_at="2026-07-27T09:00:00Z"), now=NOW) == "lost" |
| 61 | |
| 62 | |
| 63 | def test_registered_but_never_spoken_is_its_own_answer(): |
| 64 | """'Registered and silent' is usually a misconfiguration; 'was here |
| 65 | and stopped' is an incident. Folding them together loses the |
| 66 | distinction an operator acts on.""" |
| 67 | assert object_agents.liveness(agent(heartbeat_at=""), now=NOW) == "never" |
| 68 | |
| 69 | |
| 70 | def test_a_paused_agent_reports_its_status_rather_than_looking_dead(): |
| 71 | """Rendering an operator's own decision as an alarm is how a board |
| 72 | teaches people to ignore it.""" |
| 73 | for status in ("paused", "suspended", "retired"): |
| 74 | stale = agent(status=status, heartbeat_at="2026-06-01T00:00:00Z") |
| 75 | assert object_agents.liveness(stale, now=NOW) == status |
| 76 | |
| 77 | |
| 78 | def test_capabilities_are_opt_in_and_empty_advertises_nothing(): |
| 79 | """Nobody's machine joins a compute pool by accident. An agent that |
| 80 | advertised nothing is not volunteering for general duty either.""" |
| 81 | assert object_agents.capabilities(agent(capabilities="")) == [] |
| 82 | assert object_agents.can_serve(agent(capabilities=""), "") is False |
| 83 | assert object_agents.can_serve(agent(capabilities=""), "gpu") is False |
| 84 | |
| 85 | worker = agent(capabilities="GPU, triposr , gpu") |
| 86 | assert object_agents.capabilities(worker) == ["gpu", "triposr"] |
| 87 | assert object_agents.can_serve(worker, "gpu") is True |
| 88 | assert object_agents.can_serve(worker, "gpu,triposr") is True |
| 89 | assert object_agents.can_serve(worker, "whisper") is False |
| 90 | # A blank requirement is ordinary work: anyone who opted in may take it. |
| 91 | assert object_agents.can_serve(worker, "") is True |
| 92 | |
| 93 | |
| 94 | def test_committed_spend_is_a_fold_over_holds_and_debits(): |
| 95 | """Holds count, because a cap that ignored them would let an agent |
| 96 | queue a hundred runs and only notice at settlement -- exactly the |
| 97 | failure the hold model exists to prevent.""" |
| 98 | entries = [ |
| 99 | {"owner_id": "server-agent", "kind": "hold", "amount_minor": "-500"}, |
| 100 | {"owner_id": "server-agent", "kind": "debit", "amount_minor": "-250"}, |
| 101 | {"owner_id": "server-agent", "kind": "release", "amount_minor": "500"}, |
| 102 | {"owner_id": "server-agent", "kind": "topup", "amount_minor": "10000"}, |
| 103 | {"owner_id": "someone-else", "kind": "debit", "amount_minor": "-9999"}, |
| 104 | ] |
| 105 | assert object_agents.committed_minor("server-agent", entries) == 750 |
| 106 | |
| 107 | |
| 108 | def test_a_zero_cap_means_no_cap_not_no_spending(): |
| 109 | """The opposite reading would silently suspend every agent the moment |
| 110 | the field shipped -- the worst possible default for a column added to |
| 111 | existing rows. Matches billing.wallet.overdraft_minor's convention.""" |
| 112 | assert object_agents.over_cap(agent(spend_cap_minor="0"), []) is None |
| 113 | |
| 114 | entries = [{"owner_id": "server-agent", "kind": "hold", |
| 115 | "amount_minor": "-900"}] |
| 116 | capped = object_agents.over_cap(agent(spend_cap_minor="500"), entries) |
| 117 | assert capped["over"] is True |
| 118 | assert capped["committed_minor"] == 900 |
| 119 | assert capped["remaining_minor"] == 0 |
| 120 | |
| 121 | |
| 122 | def test_the_board_puts_the_silent_ones_first(): |
| 123 | fold = object_agents.board( |
| 124 | [agent(agent_id="a", label="Alive"), |
| 125 | agent(agent_id="b", label="Gone", heartbeat_at="2026-07-01T00:00:00Z")], |
| 126 | [], now=NOW) |
| 127 | assert [row["label"] for row in fold["agents"]] == ["Gone", "Alive"] |
| 128 | assert fold["live"] == 1 and fold["total"] == 2 |
| 129 | |
| 130 | |
| 131 | # --- through the objects -------------------------------------------------------- |
| 132 | |
| 133 | @pytest.fixture |
| 134 | def data_dir(tmp_path, monkeypatch): |
| 135 | base = tmp_path / "data" |
| 136 | stage_collection(base, "app-agents", "agent_registry") |
| 137 | stage_collection(base, "app-collab", "feed_posts") |
| 138 | stage_collection(base, "app-billing", "wallet_entries") |
| 139 | stage_collection(base, "app-settings", "app_settings") |
| 140 | monkeypatch.setenv("DBBASIC_DATA_DIR", str(base)) |
| 141 | return base |
| 142 | |
| 143 | |
| 144 | def run(object_id, payload=None, *, method="POST"): |
| 145 | return object_execution.execute_object( |
| 146 | RUNTIME, |
| 147 | object_execution.ObjectExecutionRequest(object_id, method=method, |
| 148 | payload=payload or {}), |
| 149 | roots=[AGENT_OBJECTS]).result |
| 150 | |
| 151 | |
| 152 | def beat(**payload): |
| 153 | payload.setdefault("_identity", {"user_id": "server-agent"}) |
| 154 | return run("action_agent_heartbeat", payload) |
| 155 | |
| 156 | |
| 157 | def registry(data_dir): |
| 158 | return object_records.read_collection_records("agent_registry", |
| 159 | base_dir=data_dir) |
| 160 | |
| 161 | |
| 162 | def test_the_first_heartbeat_registers_and_later_ones_only_beat(data_dir): |
| 163 | """One verb, not two: a separate register call is a step somebody |
| 164 | forgets and then debugs, and there is nothing a registration knows |
| 165 | that the first heartbeat does not.""" |
| 166 | first = beat(label="Server Agent", capabilities="gpu, triposr") |
| 167 | assert first["registered"] is True |
| 168 | assert first["capabilities"] == ["gpu", "triposr"] |
| 169 | |
| 170 | again = beat() |
| 171 | assert again["registered"] is False |
| 172 | assert len(registry(data_dir)) == 1 |
| 173 | assert again["heartbeat_at"] >= first["heartbeat_at"] |
| 174 | |
| 175 | |
| 176 | def test_a_bare_keepalive_does_not_wipe_capabilities(data_dir): |
| 177 | """Absent leaves alone; present-but-empty withdraws. Without that |
| 178 | distinction a heartbeat on a timer would silently de-register the |
| 179 | agent from every capability it advertised.""" |
| 180 | beat(label="Worker", capabilities="gpu,whisper") |
| 181 | assert beat()["capabilities"] == ["gpu", "whisper"] |
| 182 | |
| 183 | withdrawn = beat(capabilities="") |
| 184 | assert withdrawn["capabilities"] == [] |
| 185 | |
| 186 | |
| 187 | def test_an_agent_cannot_beat_on_behalf_of_another(data_dir): |
| 188 | """A heartbeat is the evidence something is alive, and evidence one |
| 189 | party can manufacture about another is not evidence.""" |
| 190 | beat(agent_id="somebody-else", label="Impostor") |
| 191 | rows = registry(data_dir) |
| 192 | assert len(rows) == 1 |
| 193 | assert rows[0]["agent_id"] == "server-agent" # from identity, not body |
| 194 | |
| 195 | |
| 196 | def test_an_anonymous_heartbeat_is_refused(data_dir): |
| 197 | refused = run("action_agent_heartbeat", {"label": "nobody"}) |
| 198 | assert refused["status"] == 401 |
| 199 | assert not registry(data_dir) |
| 200 | |
| 201 | |
| 202 | def test_the_board_states_liveness_with_the_heartbeat_it_came_from(data_dir): |
| 203 | """'lost' without 'last seen four hours ago' is a claim. Same reason |
| 204 | site_ledger_integrity states its method beside its verdict.""" |
| 205 | beat(label="Server Agent", capabilities="gpu") |
| 206 | body = " ".join(run("site_agents", {}, method="GET")["body"].split()) |
| 207 | assert "Server Agent" in body |
| 208 | assert "live" in body |
| 209 | assert "last beat" in body |
| 210 | assert "gpu" in body |
| 211 | |
| 212 | |
| 213 | def test_the_board_says_so_when_nothing_has_registered(data_dir): |
| 214 | body = " ".join(run("site_agents", {}, method="GET")["body"].split()) |
| 215 | assert "No agents are registered" in body |
| 216 | assert "action_agent_heartbeat" in body |
| 217 | |
| 218 | |
| 219 | def test_the_page_and_the_json_are_the_same_fold(data_dir): |
| 220 | beat(label="Server Agent", capabilities="gpu") |
| 221 | fold = json.loads(run("site_agents", {"_path": "/agents.json"}, |
| 222 | method="GET")["body"]) |
| 223 | assert fold["total"] == 1 |
| 224 | assert fold["capabilities"] == ["gpu"] |
| 225 | assert fold["agents"][0]["liveness"] == "live" |
| 226 | |
| 227 | |
| 228 | def test_the_board_renders_the_existing_feed_rather_than_a_new_one(data_dir): |
| 229 | """feed_posts (app-collab) has carried `claim` and `release` in its |
| 230 | kinds since before this package existed. A second coordination |
| 231 | channel would have been the mistake this whole package was audited to |
| 232 | avoid.""" |
| 233 | object_records.create_collection_record( |
| 234 | "feed_posts", {"kind": "claim", "body": "taking the shipping bug", |
| 235 | "owner_id": "server-agent"}, base_dir=data_dir) |
| 236 | body = " ".join(run("site_agents", {}, method="GET")["body"].split()) |
| 237 | assert "taking the shipping bug" in body |
| 238 | assert "claim" in body |
| 239 | |
| 240 | |
| 241 | def test_this_package_declares_no_feed_or_task_collection_of_its_own(): |
| 242 | """The audit's conclusion, pinned: the coordination feed and the work |
| 243 | queue already existed. A package that quietly added its own would |
| 244 | reintroduce exactly the drift this one was written to avoid.""" |
| 245 | manifest = json.loads( |
| 246 | (PACKAGES / "app-agents" / "dbbasic-package.json").read_text()) |
| 247 | collections = {entry["collection"] for entry in manifest["schemas"]} |
| 248 | assert collections == {"agent_registry"} |
| 249 | assert "app-collab" in manifest["dependencies"] |
| 250 | |
| 251 | |
| 252 | def test_the_registry_has_no_field_that_duplicates_the_change_log(): |
| 253 | """Every column had to be something not derivable from what the box |
| 254 | already keeps. A count of work done, or a last-action stamp, would be |
| 255 | a fold pretending to be a fact.""" |
| 256 | schema = json.loads((PACKAGES / "app-agents" / "schemas" |
| 257 | / "agent_registry.json").read_text()) |
| 258 | names = {field["name"] for field in schema["fields"]} |
| 259 | assert not names & {"last_action", "last_action_at", "tasks_completed", |
| 260 | "runs_completed", "actions", "activity", "spend_minor", |
| 261 | "committed_minor"} |
| 262 | assert "heartbeat_at" in names # the one thing that is NOT derivable |
| 263 | |
| 264 | |
| 265 | # --- relative time -------------------------------------------------------------- |
| 266 | # |
| 267 | # Added after comparing against the dashboard this page replaces, whose |
| 268 | # feed reads "2 weeks, 4 days ago" while an earlier draft of ours printed |
| 269 | # a raw ISO stamp. A liveness verdict is supposed to be stated WITH its |
| 270 | # evidence, and an operator asked "is it still there" should not have to |
| 271 | # subtract two datetimes in their head. |
| 272 | |
| 273 | def test_relative_time_is_coarse_on_purpose(): |
| 274 | """Nobody needs '3 hours, 14 minutes, 9 seconds'. They need to know |
| 275 | whether it is minutes or days.""" |
| 276 | now = "2026-07-27T12:00:00Z" |
| 277 | cases = { |
| 278 | "2026-07-27T11:59:58Z": "2 seconds ago", |
| 279 | "2026-07-27T11:59:00Z": "1 minute ago", |
| 280 | "2026-07-27T11:30:00Z": "30 minutes ago", |
| 281 | "2026-07-27T08:00:00Z": "4 hours ago", |
| 282 | "2026-07-25T12:00:00Z": "2 days ago", |
| 283 | "2026-07-06T12:00:00Z": "3 weeks ago", |
| 284 | "2026-03-27T12:00:00Z": "4 months ago", |
| 285 | } |
| 286 | for stamp, expected in cases.items(): |
| 287 | assert object_agents.relative_time(stamp, now) == expected, stamp |
| 288 | |
| 289 | assert object_agents.relative_time("", now) == "never" |
| 290 | |
| 291 | |
| 292 | def test_a_clock_skewed_future_stamp_reads_as_now_not_as_negative(): |
| 293 | """Two machines whose clocks disagree by a second must not produce |
| 294 | 'in 3 hours', which reads as a bug in the page rather than in NTP.""" |
| 295 | assert object_agents.relative_time( |
| 296 | "2026-07-27T12:00:05Z", "2026-07-27T12:00:00Z") == "just now" |
| 297 | |
| 298 | |
| 299 | def test_the_board_renders_the_phrase_and_keeps_the_stamp(data_dir): |
| 300 | """Both forms: the phrase on the line, the exact stamp in the tooltip |
| 301 | and in the JSON, so a monitor can compute what a human only reads.""" |
| 302 | beat(label="Server Agent", capabilities="gpu") |
| 303 | object_records.create_collection_record( |
| 304 | "feed_posts", {"kind": "claim", "body": "taking the shipping bug", |
| 305 | "owner_id": "server-agent"}, base_dir=data_dir) |
| 306 | |
| 307 | # A beat seconds old renders as "just now" -- which IS the relative |
| 308 | # phrasing, and is the case an operator sees most often. |
| 309 | body = " ".join(run("site_agents", {}, method="GET")["body"].split()) |
| 310 | assert "last beat just now" in body |
| 311 | assert "2026-" not in body.split("last beat")[1][:40] # no raw stamp inline |
| 312 | |
| 313 | fold = json.loads(run("site_agents", {"_path": "/agents.json"}, |
| 314 | method="GET")["body"]) |
| 315 | agent_row = fold["agents"][0] |
| 316 | assert agent_row["heartbeat_ago"] # the phrase |
| 317 | assert agent_row["heartbeat_at"].endswith("Z") # and the stamp |
| 318 | assert fold["feed"][0]["ago"] |
| 319 | assert fold["feed"][0]["created_at"] |
| 320 | |
| 321 | |
| 322 | def test_a_feed_post_written_before_v2_renders_without_a_time(data_dir): |
| 323 | """feed_posts gained created_at in v2, found when this page tried to |
| 324 | render the feed and discovered it had no time at all. Rows written |
| 325 | before that have none, and a post that predates the column is not a |
| 326 | post that never happened -- so it renders with no time rather than as |
| 327 | 'never'.""" |
| 328 | # created_at is read-only, so a legacy row can only be made the way a |
| 329 | # legacy row actually exists: written to the file before the column |
| 330 | # did. Appending raw is the honest simulation. |
| 331 | path = data_dir / "collections" / "feed_posts" / "records.tsv" |
| 332 | header = path.read_text().splitlines()[0].split("\t") |
| 333 | row = {"id": "legacy-1", "kind": "status", |
| 334 | "body": "from before the column", "owner_id": "old-agent"} |
| 335 | with path.open("a") as handle: |
| 336 | handle.write("\t".join(row.get(name, "") for name in header) + "\n") |
| 337 | |
| 338 | fold = json.loads(run("site_agents", {"_path": "/agents.json"}, |
| 339 | method="GET")["body"]) |
| 340 | post = fold["feed"][0] |
| 341 | assert post["body"] == "from before the column" |
| 342 | assert post["ago"] == "" |
| 343 | |
| 344 | body = " ".join(run("site_agents", {}, method="GET")["body"].split()) |
| 345 | assert "from before the column" in body |
| 346 | assert "never" not in body.split("from before the column")[1][:60] |