Runs live, versioned Python application objects on one VM, with a suite of apps: projects, notes, tasks, files and more.

0 downloads

dbbasic-object-server/tests/test_agents.py
Download zip
Clone
Clone with git
git clone https://gitstable.com/git/askrobots/dbbasic-object-server.git
HTTPS
https://gitstable.com/git/askrobots/dbbasic-object-server.git
SSH
ssh://git@gitstable.com:2222/askrobots/dbbasic-object-server.git

Cloning needs no sign-in. Pushing over HTTPS asks for your username and an access token. SSH needs your key under SSH keys.

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
3This package exists because of an audit, not an idea. Most of an "agent
4runtime" was already on the box — an agent is a user, what it did is the
5change log, the coordination feed is `feed_posts` with `claim` and
6`release` already in its kinds, and race-free claiming is `expected_rev`.
7So 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
10Three things passed, and this file is mostly about the first:
11
12LIVENESS IS NOT A LAST WRITE. An agent reasoning for ten minutes writes
13nothing and is alive; a crashed one looks alive until its last write ages
14out. No fold over the change log answers "is it still there", which is
15the whole justification for a heartbeat column.
16
17CAPABILITIES ARE OPT-IN. An agent advertising nothing is routed nothing,
18because nobody's machine joins a compute pool by accident.
19
20SPEND IS A FOLD, NEVER A COUNTER. The cap reads holds and debits out of
21the ledger — the same argument hook_wallet_entries makes about
22wallets.balance_minor.
23"""
24
25import json
26import pathlib
27
28import pytest
29from conftest import stage_collection
30
31import object_agents
32import object_execution
33import object_records
34import python_object_runtime
35
36REPO_ROOT = pathlib.Path(__file__).resolve().parents[1]
37PACKAGES = REPO_ROOT / "packages"
38AGENT_OBJECTS = PACKAGES / "app-agents" / "objects"
39RUNTIME = python_object_runtime.PythonObjectRuntime()
40
41NOW = "2026-07-27T12:00:00Z"
42
43
44def 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
53def 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
63def 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
70def 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
78def 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
94def 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
108def 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
122def 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
134def 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
144def 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
152def beat(**payload):
153 payload.setdefault("_identity", {"user_id": "server-agent"})
154 return run("action_agent_heartbeat", payload)
155
156
157def registry(data_dir):
158 return object_records.read_collection_records("agent_registry",
159 base_dir=data_dir)
160
161
162def 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
176def 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
187def 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
196def 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
202def 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
213def 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
219def 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
228def 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
241def 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
252def 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
273def 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
292def 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
299def 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
322def 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]