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
agents.py · 15.8 KB · 406 lines
| 1 | """site_agents -- the board a human watches while the agents work. |
| 2 | |
| 3 | GET /agents who is here, what they can do, what they are saying |
| 4 | GET /agents.json the same fold, for a monitor |
| 5 | |
| 6 | ## Why a board rather than a list |
| 7 | |
| 8 | The generative list renderer already gives `agent_registry` a perfectly |
| 9 | good table, and it is the wrong shape for the one question this page |
| 10 | exists to answer: **is everything that should be working, working?** A |
| 11 | table sorts by whatever column you clicked. A board leads with the |
| 12 | answer, puts the dead things first, and shows the conversation next to |
| 13 | the participants. |
| 14 | |
| 15 | The model is WOLD's own asset gallery, which earns its keep the same way: |
| 16 | score, method, verdict and provenance on every card, so an operator can |
| 17 | scan a hundred of them and see exactly which ones need attention without |
| 18 | opening anything. |
| 19 | |
| 20 | ## Liveness is stated with its evidence |
| 21 | |
| 22 | Every agent shows its state AND the heartbeat it was computed from, for |
| 23 | the reason the ledger-integrity page states its method beside its |
| 24 | verdict: "lost" without "last seen 4 hours ago" is a claim, and the |
| 25 | operator's next question is always the timestamp. Three states rather |
| 26 | than a boolean, because the useful distinction is not up-or-down but |
| 27 | "should I be worried yet". |
| 28 | |
| 29 | ## The feed is the other half, and it lives somewhere else |
| 30 | |
| 31 | `feed_posts` (app-collab) has been the coordination feed since before this |
| 32 | package existed -- with `claim` and `release` already in its `kind` enum. |
| 33 | This page renders it rather than duplicating it, and app-collab keeps |
| 34 | owning it. That is why this package declares no feed collection of its |
| 35 | own: the channel was already here, it just had no face. |
| 36 | """ |
| 37 | |
| 38 | import html |
| 39 | import json |
| 40 | import os |
| 41 | from datetime import datetime, timezone |
| 42 | |
| 43 | import object_agents |
| 44 | import object_state |
| 45 | import object_records |
| 46 | |
| 47 | REGISTRY = "agent_registry" |
| 48 | SCHEDULER_RUNS = "scheduler_runs" |
| 49 | FEED = "feed_posts" |
| 50 | SETTINGS_COLLECTION = "app_settings" |
| 51 | STALE_KEY = "agents.stale_seconds" |
| 52 | LOST_KEY = "agents.lost_seconds" |
| 53 | |
| 54 | FEED_LIMIT = 25 |
| 55 | |
| 56 | _STYLE = """ |
| 57 | .ag { max-width: 54rem; } |
| 58 | .ag h2 { font-size: 1rem; margin: 1.6rem 0 .5rem; } |
| 59 | .ag .banner { border: 1px solid var(--line, #38384a); border-radius: 8px; |
| 60 | padding: .85rem 1.05rem; margin: 1rem 0 1.4rem; } |
| 61 | .ag .banner.warn { border-color: var(--accent, #b5713a); } |
| 62 | .ag .cols { display: grid; gap: 1.2rem; grid-template-columns: 1fr 1fr; |
| 63 | align-items: start; } |
| 64 | @media (max-width: 46rem) { .ag .cols { grid-template-columns: 1fr; } } |
| 65 | .ag .cards { display: grid; gap: .7rem; } |
| 66 | .ag .card { border: 1px solid var(--line, #38384a); border-radius: 8px; |
| 67 | padding: .7rem .85rem; } |
| 68 | .ag .card.live { border-left: 3px solid var(--accent, #b5713a); } |
| 69 | .ag .card.lost, .ag .card.never { border-left: 3px solid #d05a5a; } |
| 70 | .ag .card.stale { border-left: 3px solid #c9a227; } |
| 71 | .ag .card h3 { font-size: .95rem; margin: 0 0 .15rem; } |
| 72 | .ag .state { font-size: .75rem; text-transform: uppercase; letter-spacing: .05em; } |
| 73 | .ag .state.live { color: var(--accent, #b5713a); } |
| 74 | .ag .state.lost, .ag .state.never { color: #d05a5a; } |
| 75 | .ag .state.stale { color: #c9a227; } |
| 76 | .ag .tag { display: inline-block; border: 1px solid var(--line, #55556a); |
| 77 | border-radius: 10px; padding: 0 .45rem; font-size: .72rem; |
| 78 | margin: .15rem .15rem 0 0; } |
| 79 | .ag .muted { opacity: .7; font-size: .82rem; } |
| 80 | .ag .feed { margin: .4rem 0 0; padding: 0; list-style: none; } |
| 81 | .ag .feed li { border-bottom: 1px solid var(--line, #38384a); padding: .4rem 0; |
| 82 | font-size: .88rem; } |
| 83 | .ag .kind { font-size: .7rem; text-transform: uppercase; letter-spacing: .05em; |
| 84 | border: 1px solid var(--line, #55556a); border-radius: 10px; |
| 85 | padding: 0 .4rem; margin-right: .4rem; } |
| 86 | .ag .note { border-left: 3px solid var(--line, #55556a); padding: .1rem 0 .1rem .7rem; |
| 87 | margin: .7rem 0 1.1rem; font-size: .86rem; opacity: .85; } |
| 88 | .ag table.workers { width: 100%; border-collapse: collapse; font-size: .86rem; } |
| 89 | .ag table.workers th, .ag table.workers td { |
| 90 | text-align: left; padding: .35rem .5rem; |
| 91 | border-bottom: 1px solid var(--line, #38384a); vertical-align: top; } |
| 92 | .ag table.workers th { font-weight: 600; opacity: .8; } |
| 93 | .ag .pill { font-size: .7rem; text-transform: uppercase; letter-spacing: .05em; |
| 94 | border: 1px solid var(--line, #55556a); border-radius: 10px; |
| 95 | padding: 0 .45rem; } |
| 96 | .ag .pill.live { color: var(--accent, #b5713a); border-color: var(--accent, #b5713a); } |
| 97 | .ag .pill.stale { color: #c9a227; border-color: #c9a227; } |
| 98 | .ag .pill.lost, .ag .pill.never { color: #d05a5a; border-color: #d05a5a; } |
| 99 | .ag .workererr { color: #d05a5a; font-size: .78rem; margin-top: .2rem; } |
| 100 | """ |
| 101 | |
| 102 | |
| 103 | def _esc(value): |
| 104 | return html.escape(str(value if value is not None else ""), quote=True) |
| 105 | |
| 106 | |
| 107 | def _base_dir(): |
| 108 | return os.environ.get("DBBASIC_DATA_DIR", "data") |
| 109 | |
| 110 | |
| 111 | def _text(value): |
| 112 | return str(value if value is not None else "").strip() |
| 113 | |
| 114 | |
| 115 | def _now(): |
| 116 | return datetime.now(timezone.utc).isoformat().replace("+00:00", "Z") |
| 117 | |
| 118 | |
| 119 | def _rows(collection, base): |
| 120 | try: |
| 121 | return object_records.read_collection_records(collection, base_dir=base) |
| 122 | except Exception: |
| 123 | return [] |
| 124 | |
| 125 | |
| 126 | def _setting(base, key, default): |
| 127 | for row in _rows(SETTINGS_COLLECTION, base): |
| 128 | if _text(row.get("key")) == key and _text(row.get("value")): |
| 129 | try: |
| 130 | return int(_text(row.get("value"))) |
| 131 | except ValueError: |
| 132 | return default |
| 133 | return default |
| 134 | |
| 135 | |
| 136 | def _scheduled_tasks(base): |
| 137 | """The scheduler's declared tasks, read from its object state. |
| 138 | |
| 139 | Degrades to [] when the scheduler has never been written -- a box |
| 140 | with no scheduled work is not a broken box, and the workers panel |
| 141 | simply has nothing to show. |
| 142 | """ |
| 143 | try: |
| 144 | state = object_state.get_object_state("scheduler", base) |
| 145 | except Exception: |
| 146 | return [] |
| 147 | tasks = [] |
| 148 | for key, value in (state or {}).items(): |
| 149 | if not str(key).startswith("task_"): |
| 150 | continue |
| 151 | try: |
| 152 | task = json.loads(value) if isinstance(value, str) else value |
| 153 | except (ValueError, TypeError): |
| 154 | continue |
| 155 | if isinstance(task, dict): |
| 156 | tasks.append(task) |
| 157 | return tasks |
| 158 | |
| 159 | |
| 160 | def report(*, base=None, now=None): |
| 161 | """One fold, two surfaces.""" |
| 162 | base = _base_dir() if base is None else base |
| 163 | now = now or _now() |
| 164 | |
| 165 | fold = object_agents.board( |
| 166 | _rows(REGISTRY, base), _rows("wallet_entries", base), now=now, |
| 167 | stale_seconds=_setting(base, STALE_KEY, |
| 168 | object_agents.DEFAULT_STALE_SECONDS), |
| 169 | lost_seconds=_setting(base, LOST_KEY, |
| 170 | object_agents.DEFAULT_LOST_SECONDS)) |
| 171 | |
| 172 | # The box's own scheduled work, folded from the run log rather than |
| 173 | # from a heartbeat somebody would have to remember to send. Every |
| 174 | # scheduled execution already writes a scheduler_runs row, so the |
| 175 | # evidence exists; nothing was applying a liveness verdict to it. |
| 176 | # |
| 177 | # The declared tasks come from the scheduler's own state, and they |
| 178 | # matter for exactly one case the run log cannot report: a task that |
| 179 | # has NEVER run has no rows at all, and an absence is invisible to a |
| 180 | # fold over presences. That is the pass silently doing nothing since |
| 181 | # the day it was added -- the failure most worth catching here. |
| 182 | fold["workers"] = object_agents.worker_liveness( |
| 183 | _rows(SCHEDULER_RUNS, base), tasks=_scheduled_tasks(base), now=now, |
| 184 | stale_seconds=_setting(base, STALE_KEY, |
| 185 | object_agents.DEFAULT_STALE_SECONDS), |
| 186 | lost_seconds=_setting(base, LOST_KEY, |
| 187 | object_agents.DEFAULT_LOST_SECONDS)) |
| 188 | |
| 189 | posts = sorted(_rows(FEED, base), |
| 190 | key=lambda row: _text(row.get("created_at")), reverse=True) |
| 191 | fold["feed"] = [{ |
| 192 | "kind": _text(post.get("kind")) or "status", |
| 193 | "body": _text(post.get("body")), |
| 194 | "owner_id": _text(post.get("owner_id")), |
| 195 | "created_at": _text(post.get("created_at")), |
| 196 | # Blank for rows written before feed_posts gained created_at (v2). |
| 197 | # Those render WITHOUT a time rather than as "never", because a |
| 198 | # post that predates the column is not a post that never happened. |
| 199 | "ago": (object_agents.relative_time(post.get("created_at"), now) |
| 200 | if _text(post.get("created_at")) else ""), |
| 201 | } for post in posts[:FEED_LIMIT]] |
| 202 | fold["feed_installed"] = bool(posts) or _rows(FEED, base) != [] |
| 203 | return fold |
| 204 | |
| 205 | |
| 206 | # --- rendering --------------------------------------------------------------- |
| 207 | |
| 208 | def _banner(fold): |
| 209 | if not fold["agents"]: |
| 210 | return """ |
| 211 | <div class="banner warn"> |
| 212 | <h2>No agents are registered</h2> |
| 213 | <p>Nothing has introduced itself. An agent registers by sending its first |
| 214 | heartbeat to <code>action_agent_heartbeat</code> — there is no separate |
| 215 | registration step, because there is nothing a registration knows that the |
| 216 | first heartbeat does not.</p> |
| 217 | </div>""" |
| 218 | |
| 219 | missing = [row for row in fold["agents"] |
| 220 | if row["liveness"] in ("lost", "never")] |
| 221 | if missing: |
| 222 | names = ", ".join(_esc(row["label"]) for row in missing[:4]) |
| 223 | return f""" |
| 224 | <div class="banner warn"> |
| 225 | <h2>{len(missing)} of {fold['total']} are not answering</h2> |
| 226 | <p>{names} last checked in longer ago than this server's patience allows. |
| 227 | An agent goes quiet for two reasons — it crashed, or it is doing something |
| 228 | long and is not beating while it works. The heartbeat beside each card is |
| 229 | what tells them apart.</p> |
| 230 | </div>""" |
| 231 | |
| 232 | over = fold["over_cap"] |
| 233 | if over: |
| 234 | return f""" |
| 235 | <div class="banner warn"> |
| 236 | <h2>{len(over)} over the spend cap</h2> |
| 237 | <p>{_esc(', '.join(over))} has committed more than its cap allows. The cap is |
| 238 | a fold over holds and debits in the ledger, not a stored counter, so this |
| 239 | is the ledger's own arithmetic rather than a number somebody maintained.</p> |
| 240 | </div>""" |
| 241 | |
| 242 | return f""" |
| 243 | <div class="banner"> |
| 244 | <h2>All {fold['total']} answering</h2> |
| 245 | <p>Every registered agent has beaten within the window.</p> |
| 246 | </div>""" |
| 247 | |
| 248 | |
| 249 | def _card(row): |
| 250 | spend = "" |
| 251 | if row["spend"]: |
| 252 | spend = (f'<p class="muted">spend {row["spend"]["committed_minor"]} / ' |
| 253 | f'{row["spend"]["cap_minor"]}' |
| 254 | f'{" — OVER" if row["spend"]["over"] else ""}</p>') |
| 255 | tags = "".join(f'<span class="tag">{_esc(tag)}</span>' |
| 256 | for tag in row["capabilities"]) |
| 257 | if not tags: |
| 258 | tags = '<span class="muted">no capabilities advertised</span>' |
| 259 | # The phrase, not the stamp: an operator asked "is it still there" |
| 260 | # should not have to subtract two datetimes in their head. |
| 261 | beat = _esc(row["heartbeat_ago"]) if row["heartbeat_at"] else "never checked in" |
| 262 | return f""" |
| 263 | <div class="card {_esc(row['liveness'])}"> |
| 264 | <h3>{_esc(row['label'])}</h3> |
| 265 | <p class="state {_esc(row['liveness'])}">{_esc(row['liveness'])}</p> |
| 266 | <p class="muted">{_esc(row['agent_id'])}</p> |
| 267 | {f'<p class="muted">{_esc(row["purpose"])}</p>' if row['purpose'] else ''} |
| 268 | <p>{tags}</p> |
| 269 | <p class="muted" title="{_esc(row['heartbeat_at'])}">last beat {beat}</p> |
| 270 | {spend} |
| 271 | </div>""" |
| 272 | |
| 273 | |
| 274 | def _feed_html(fold): |
| 275 | if not fold["feed"]: |
| 276 | return ('<p class="muted">Nothing on the feed yet. It is the ' |
| 277 | '<code>feed_posts</code> collection (app-collab), which has ' |
| 278 | 'carried <code>claim</code> and <code>release</code> in its ' |
| 279 | 'kinds since before this page existed.</p>') |
| 280 | # Relative time on the line, the exact stamp in the tooltip. A feed is |
| 281 | # read for "how long ago", never for "at what instant" -- and the one |
| 282 | # time somebody does want the instant, hovering gives it without |
| 283 | # spending a line on it. |
| 284 | items = "".join( |
| 285 | f'<li><span class="kind">{_esc(post["kind"])}</span>' |
| 286 | f'{_esc(post["body"])}' |
| 287 | f'<br><span class="muted" title="{_esc(post["created_at"])}">' |
| 288 | f'{_esc(post["owner_id"])}' |
| 289 | f'{" · " + _esc(post["ago"]) if post["ago"] else ""}</span></li>' |
| 290 | for post in fold["feed"]) |
| 291 | return f'<ul class="feed">{items}</ul>' |
| 292 | |
| 293 | |
| 294 | def _worker_rows(fold): |
| 295 | workers = fold.get("workers", {}).get("workers", []) |
| 296 | if not workers: |
| 297 | return ('<p class="muted">Nothing is scheduled on this server yet.</p>') |
| 298 | out = [] |
| 299 | for row in workers: |
| 300 | state = _esc(row["liveness"]) |
| 301 | when = _esc(row["last_run_ago"]) or "never" |
| 302 | schedule = _esc(row["schedule"]) or "—" |
| 303 | # "live, and failing" is a worse state than "lost" and the one a |
| 304 | # liveness badge alone would render as healthy, so the error gets |
| 305 | # its own line rather than a colour. |
| 306 | error = (f'<div class="workererr">last run failed: ' |
| 307 | f'{_esc(row["last_error"][:160])}</div>' |
| 308 | if row["failing"] else "") |
| 309 | out.append( |
| 310 | f'<tr class="w-{state}">' |
| 311 | f'<td><code>{_esc(row["object_id"])}</code>{error}</td>' |
| 312 | f'<td><code>{schedule}</code></td>' |
| 313 | f'<td><span class="pill {state}">{state}</span></td>' |
| 314 | f'<td>{when}</td>' |
| 315 | f'</tr>') |
| 316 | return ('<table class="workers"><thead><tr><th>Scheduled object</th>' |
| 317 | '<th>Schedule</th><th>State</th><th>Last run</th></tr></thead>' |
| 318 | f'<tbody>{"".join(out)}</tbody></table>') |
| 319 | |
| 320 | |
| 321 | def _page(fold): |
| 322 | cards = "".join(_card(row) for row in fold["agents"]) |
| 323 | caps = (", ".join(_esc(tag) for tag in fold["capabilities"]) |
| 324 | or "none advertised") |
| 325 | return f""" |
| 326 | <div class="breadcrumb"><a href="/">Home</a> / Agents</div> |
| 327 | <h1>Agents</h1> |
| 328 | <p>Who is operating this server, what they will accept work for, and |
| 329 | whether they are still answering.</p> |
| 330 | {_banner(fold)} |
| 331 | <div class="cols"> |
| 332 | <div> |
| 333 | <h2>Agents</h2> |
| 334 | <div class="cards">{cards}</div> |
| 335 | </div> |
| 336 | <div> |
| 337 | <h2>Coordination feed</h2> |
| 338 | {_feed_html(fold)} |
| 339 | </div> |
| 340 | </div> |
| 341 | <p class="note">Liveness is a <strong>heartbeat</strong>, not a last write. |
| 342 | An agent reasoning for ten minutes writes nothing and is perfectly alive, |
| 343 | so "when did it last change a record" cannot answer "is it still there" — |
| 344 | which is the only reason this collection exists. Everything else about an |
| 345 | agent is already recorded: what it did is the |
| 346 | <a href="/activity">change log</a>, who it is, is its user.</p> |
| 347 | |
| 348 | <h2>This server's own work</h2> |
| 349 | <p>The scheduled passes this box runs for itself, and whether they are |
| 350 | still running. This is <strong>folded from the run log, not from a |
| 351 | heartbeat</strong>: every scheduled execution already writes a |
| 352 | <code>scheduler_runs</code> row, and a row saying the work ran is better |
| 353 | evidence than a process saying it is alive.</p> |
| 354 | {_worker_rows(fold)} |
| 355 | <p class="muted">A task that has <em>never</em> run is shown from the |
| 356 | scheduler's declared tasks rather than the log, because an object with no |
| 357 | rows is invisible to a fold over rows — and a pass that has quietly done |
| 358 | nothing since the day it was added is exactly the failure worth |
| 359 | catching.</p> |
| 360 | |
| 361 | <h2>Capabilities on this server</h2> |
| 362 | <p>{caps}</p> |
| 363 | <p class="muted">Capabilities are opt-in and empty by default. An agent |
| 364 | advertising nothing is routed nothing — nobody's machine joins a compute |
| 365 | pool by accident.</p> |
| 366 | |
| 367 | <p class="note"><a href="/agents.json">This page as JSON</a> · |
| 368 | <a href="/agent-registry">the registry as a table</a></p> |
| 369 | """ |
| 370 | |
| 371 | |
| 372 | def GET(request): |
| 373 | request = request or {} |
| 374 | path = _text((request or {}).get("_path") or "/agents").lower() |
| 375 | fold = report() |
| 376 | |
| 377 | if path.endswith(".json"): |
| 378 | return {"status": 200, |
| 379 | "content_type": "application/json; charset=utf-8", |
| 380 | "body": json.dumps(fold, indent=2, sort_keys=True, default=str)} |
| 381 | |
| 382 | return { |
| 383 | "status": 200, |
| 384 | "content_type": "text/html; charset=utf-8", |
| 385 | "body": f"""<!doctype html> |
| 386 | <html lang="en"> |
| 387 | <head> |
| 388 | <meta charset="utf-8"> |
| 389 | <meta name="viewport" content="width=device-width, initial-scale=1"> |
| 390 | <title>Agents</title> |
| 391 | <link rel="stylesheet" href="/style"> |
| 392 | <style>{_STYLE}</style> |
| 393 | </head> |
| 394 | <body> |
| 395 | <div class="wrap ag"> |
| 396 | <header class="app"><h1><a href="/">DBBASIC</a></h1></header> |
| 397 | {_page(fold)} |
| 398 | </div> |
| 399 | <script src="/nav"></script> |
| 400 | </body> |
| 401 | </html>""", |
| 402 | } |
| 403 | |
| 404 | |
| 405 | def POST(request): |
| 406 | return GET(request) |