sessionyard 0.7.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (62) hide show
  1. agent_chat/001_core.sql +172 -0
  2. agent_chat/002_coordination.sql +63 -0
  3. agent_chat/003_harness_admission.sql +10 -0
  4. agent_chat/004_session_titles.sql +3 -0
  5. agent_chat/005_viewer.sql +9 -0
  6. agent_chat/006_quotas.sql +6 -0
  7. agent_chat/007_sender_receipts.sql +20 -0
  8. agent_chat/008_direct_threads.sql +49 -0
  9. agent_chat/009_pm_mark.sql +23 -0
  10. agent_chat/010_quota_backfill.sql +12 -0
  11. agent_chat/011_roles_and_work.sql +31 -0
  12. agent_chat/__init__.py +1 -0
  13. agent_chat/adapter.py +414 -0
  14. agent_chat/admin.py +524 -0
  15. agent_chat/api.py +641 -0
  16. agent_chat/auth.py +226 -0
  17. agent_chat/browser.py +118 -0
  18. agent_chat/browser_verify.py +487 -0
  19. agent_chat/browser_verify_artifacts.py +280 -0
  20. agent_chat/browser_verify_checks.py +236 -0
  21. agent_chat/browser_verify_run.py +523 -0
  22. agent_chat/cli.py +532 -0
  23. agent_chat/client.py +272 -0
  24. agent_chat/deliveries.py +555 -0
  25. agent_chat/events.py +48 -0
  26. agent_chat/feed.py +193 -0
  27. agent_chat/http_boundary.py +154 -0
  28. agent_chat/instance_client.py +349 -0
  29. agent_chat/instance_file.py +207 -0
  30. agent_chat/instance_worker.py +326 -0
  31. agent_chat/mcp/__init__.py +5 -0
  32. agent_chat/mcp/__main__.py +39 -0
  33. agent_chat/mcp/app.py +183 -0
  34. agent_chat/mcp/auth.py +67 -0
  35. agent_chat/mcp/config.py +55 -0
  36. agent_chat/mcp/tools.py +295 -0
  37. agent_chat/metrics.py +60 -0
  38. agent_chat/models.py +430 -0
  39. agent_chat/openapi.py +322 -0
  40. agent_chat/producer.py +208 -0
  41. agent_chat/protocol.py +71 -0
  42. agent_chat/publication.py +252 -0
  43. agent_chat/receipts.py +225 -0
  44. agent_chat/retention.py +154 -0
  45. agent_chat/roles.py +153 -0
  46. agent_chat/rooms.py +179 -0
  47. agent_chat/sessions.py +340 -0
  48. agent_chat/skills/agent-chat/SKILL.md +64 -0
  49. agent_chat/state.py +144 -0
  50. agent_chat/storage.py +110 -0
  51. agent_chat/threads.py +50 -0
  52. agent_chat/web/Manrope-OFL.txt +93 -0
  53. agent_chat/web/Manrope-Variable.ttf +0 -0
  54. agent_chat/web/chat.css +936 -0
  55. agent_chat/web/chat.js +1922 -0
  56. agent_chat/web/i18n.js +340 -0
  57. agent_chat/web/index.html +264 -0
  58. sessionyard-0.7.0.dist-info/METADATA +314 -0
  59. sessionyard-0.7.0.dist-info/RECORD +62 -0
  60. sessionyard-0.7.0.dist-info/WHEEL +4 -0
  61. sessionyard-0.7.0.dist-info/entry_points.txt +3 -0
  62. sessionyard-0.7.0.dist-info/licenses/LICENSE +661 -0
@@ -0,0 +1,555 @@
1
+ """Durable chat reservations, not native calls or proof of model processing."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from collections.abc import Iterable
6
+ from typing import Any
7
+ from uuid import UUID, uuid4
8
+
9
+ from psycopg import Connection
10
+
11
+ from . import events, receipts
12
+ from .auth import authorize_message_room, lock_agent, require_live
13
+ from .models import (
14
+ BACKOFF_SECONDS,
15
+ DELIVERY_MAX_AGE_SECONDS,
16
+ DIRECT_REPLY_LIMIT,
17
+ DIRECT_WAKE_LIMIT,
18
+ LEASE_SECONDS,
19
+ LOOP_REPLIES,
20
+ LOOP_WINDOW_SECONDS,
21
+ REPLY_LIMIT,
22
+ WAKE_LIMIT,
23
+ WAKE_WINDOW_SECONDS,
24
+ Actor,
25
+ ChatError,
26
+ DeliveryClaim,
27
+ DeliveryResult,
28
+ )
29
+
30
+ # The one judgement of a thread's consultation limit, for publication, pending and claim. `direct` is the thread's
31
+ # class (008_direct_threads.sql), counting the sessions `joining` would add; a thread that existed before the
32
+ # migration is never direct, because its participants are not known to be complete. `open` holds while its agent
33
+ # replies are below the class's limit and the loop detector has not tripped. Both read the thread row alone, never
34
+ # its messages. Every stamp is a counted reply and the detector needs LOOP_REPLIES of them, more than REPLY_LIMIT,
35
+ # so a thread that is not direct is closed by its counter first and only a direct thread can trip. Joins on `t`.
36
+ _CONSULTATION = """
37
+ CROSS JOIN LATERAL (
38
+ SELECT agent_chat.thread_direct(t.participants_complete, t.participants, %(joining)s::uuid[]) AS direct
39
+ ) thread_class
40
+ CROSS JOIN LATERAL (
41
+ SELECT t.agent_replies < CASE WHEN thread_class.direct THEN %(direct_reply_limit)s ELSE %(reply_limit)s END
42
+ AND NOT agent_chat.thread_loop_tripped(t.loop_stamps, %(loop_replies)s, %(loop_window)s) AS open
43
+ ) consultation
44
+ """
45
+
46
+
47
+ def _consultation_params(joining: Iterable[UUID] = ()) -> dict[str, Any]:
48
+ return {
49
+ "joining": list(joining),
50
+ "reply_limit": REPLY_LIMIT,
51
+ "direct_reply_limit": DIRECT_REPLY_LIMIT,
52
+ "loop_replies": LOOP_REPLIES,
53
+ "loop_window": LOOP_WINDOW_SECONDS,
54
+ }
55
+
56
+
57
+ def consultations(
58
+ db: Connection[dict[str, Any]], threads: Iterable[UUID], joining: Iterable[UUID] = ()
59
+ ) -> dict[UUID, dict[str, Any]]:
60
+ """`direct` and `open` per thread; reads only, so the caller's locks and the event clock keep it current."""
61
+ rows = db.execute(
62
+ "SELECT t.id, thread_class.direct, consultation.open FROM agent_chat.threads t"
63
+ + _CONSULTATION
64
+ + "WHERE t.id = ANY(%(threads)s::uuid[])",
65
+ {**_consultation_params(joining), "threads": list(threads)},
66
+ ).fetchall()
67
+ return {row["id"]: row for row in rows}
68
+
69
+
70
+ def budget(db: Connection[dict[str, Any]], session: UUID) -> dict[str, Any]:
71
+ """Caller holds the event clock; admissions are never refunded.
72
+
73
+ The top level is the allowance of threads that are not direct, unchanged for older readers; `direct` nests the
74
+ separate allowance of direct 1:1 threads in the same shape.
75
+ """
76
+ used = {
77
+ row["allowance"]: row
78
+ for row in db.execute(
79
+ """
80
+ SELECT allowance, count(*) AS used, min(admitted_at) + make_interval(secs => %(window)s) AS next_release_at
81
+ FROM agent_chat.delivery_attempts
82
+ WHERE session_id = %(session)s AND admitted_at > clock_timestamp() - make_interval(secs => %(window)s)
83
+ GROUP BY allowance
84
+ """,
85
+ {"session": session, "window": WAKE_WINDOW_SECONDS},
86
+ ).fetchall()
87
+ }
88
+
89
+ def allowance(name: str, limit: int, reply_limit: int) -> dict[str, Any]:
90
+ row = used.get(name, {"used": 0, "next_release_at": None})
91
+ return {
92
+ "limit": limit,
93
+ "used": row["used"],
94
+ "remaining": max(0, limit - row["used"]),
95
+ "next_release_at": row["next_release_at"],
96
+ "reply_limit": reply_limit,
97
+ }
98
+
99
+ return {
100
+ **allowance("other", WAKE_LIMIT, REPLY_LIMIT),
101
+ "direct": allowance("direct", DIRECT_WAKE_LIMIT, DIRECT_REPLY_LIMIT),
102
+ }
103
+
104
+
105
+ def pending(db: Connection[dict[str, Any]], actor: Actor) -> dict[str, Any]:
106
+ """Read candidates, not a reservation or receipt; never advance a history cursor."""
107
+ with db.transaction():
108
+ events.read_clock(db)
109
+ lock_agent(db, actor)
110
+ assert actor.session_id is not None
111
+ response = {"session_id": actor.session_id, "instance_id": actor.instance_id, "messages": []}
112
+ allowances = budget(db, actor.session_id)
113
+ open_other, open_direct = allowances["remaining"] > 0, allowances["direct"]["remaining"] > 0
114
+ if _blocked(db, actor) or not (open_other or open_direct):
115
+ return response
116
+ # A candidate whose allowance is spent is dropped before the limit, so it never starves the other class.
117
+ # A retry batch is charged as a whole: to `direct` only when every member's thread is direct now.
118
+ rows = db.execute(
119
+ """
120
+ WITH eligible AS MATERIALIZED (
121
+ SELECT r.message_id, r.delivery_batch_id, e.position, octet_length(m.body) AS body_bytes,
122
+ thread_class.direct
123
+ FROM agent_chat.recipients r JOIN agent_chat.messages m ON m.id = r.message_id
124
+ JOIN agent_chat.threads t ON t.id = m.thread_id
125
+ JOIN agent_chat.events e ON e.message_id = m.id AND e.kind = 'message'
126
+ JOIN agent_chat.memberships member ON member.room_id = m.room_id AND member.session_id = r.session_id
127
+ JOIN agent_chat.principal_rooms grant_row ON grant_row.room_id = m.room_id
128
+ AND grant_row.principal_id = %(principal)s
129
+ """
130
+ + _CONSULTATION
131
+ + """
132
+ WHERE r.session_id = %(session)s AND m.kind IN ('question', 'consultation', 'reply')
133
+ AND m.body IS NOT NULL AND m.expires_at > clock_timestamp() AND consultation.open
134
+ AND r.handed_at IS NULL AND r.acknowledged_at IS NULL AND r.replying_message_id IS NULL
135
+ AND r.uncertainty_reason IS NULL
136
+ AND r.stored_at > clock_timestamp() - make_interval(secs => %(max_age)s)
137
+ )
138
+ SELECT eligible.message_id, eligible.body_bytes, eligible.direct, b.message_ids, batch.sizes AS batch_sizes
139
+ FROM eligible
140
+ LEFT JOIN agent_chat.delivery_batches b ON b.id = eligible.delivery_batch_id
141
+ LEFT JOIN LATERAL (
142
+ SELECT jsonb_object_agg(x.message_id::text, x.body_bytes) AS sizes, bool_and(x.direct) AS direct
143
+ FROM eligible x WHERE x.message_id = ANY(b.message_ids)
144
+ ) batch ON true
145
+ LEFT JOIN LATERAL (
146
+ SELECT outcome, ordinal, completed_at FROM agent_chat.delivery_attempts
147
+ WHERE batch_id = b.id ORDER BY ordinal DESC LIMIT 1
148
+ ) last ON true
149
+ WHERE NOT EXISTS (
150
+ SELECT 1 FROM agent_chat.delivery_attempts a JOIN agent_chat.instances i ON i.id = a.instance_id
151
+ WHERE a.session_id = %(session)s AND a.outcome IS NULL AND a.expires_at > clock_timestamp()
152
+ AND i.ended_at IS NULL AND i.heartbeat_at > clock_timestamp() - make_interval(secs => %(lease)s)
153
+ ) AND CASE WHEN COALESCE(batch.direct, eligible.direct) THEN %(open_direct)s ELSE %(open_other)s END
154
+ AND (b.id IS NULL OR (
155
+ last.outcome IN ('failed', 'deferred') AND last.ordinal < 3
156
+ AND last.completed_at + make_interval(
157
+ secs => CASE WHEN last.ordinal = 1 THEN %(first_backoff)s ELSE %(later_backoff)s END
158
+ ) <= clock_timestamp()
159
+ AND NOT EXISTS (SELECT 1 FROM unnest(b.message_ids) AS item(id)
160
+ WHERE NOT EXISTS (SELECT 1 FROM eligible x WHERE x.message_id = item.id))
161
+ )) ORDER BY eligible.position LIMIT 16
162
+ """,
163
+ {
164
+ **_consultation_params(),
165
+ "principal": actor.principal_id,
166
+ "session": actor.session_id,
167
+ "open_direct": open_direct,
168
+ "open_other": open_other,
169
+ "lease": LEASE_SECONDS,
170
+ "first_backoff": BACKOFF_SECONDS[0],
171
+ "later_backoff": BACKOFF_SECONDS[1],
172
+ "max_age": DELIVERY_MAX_AGE_SECONDS,
173
+ },
174
+ ).fetchall()
175
+ ids: list[UUID] = []
176
+ sizes: dict[str, int] = {}
177
+ retry = False
178
+ direct = None
179
+ for row in rows:
180
+ if row["message_ids"] is not None:
181
+ if not ids:
182
+ ids = row["message_ids"]
183
+ retry = True
184
+ # Every member of a retry batch is in `eligible` (the NOT EXISTS above), so it has a size.
185
+ sizes = {str(item): row["batch_sizes"][str(item)] for item in ids}
186
+ break # never mix or split an existing batch
187
+ # A new batch never mixes allowances: the first candidate's class decides it.
188
+ if direct is None:
189
+ direct = row["direct"]
190
+ elif row["direct"] != direct:
191
+ continue
192
+ ids.append(row["message_id"])
193
+ sizes[str(row["message_id"])] = row["body_bytes"]
194
+ if ids:
195
+ # Lock selected grants; the lease, retention and age are rechecked after those waits.
196
+ if any(row["too_old"] for row in _targets(db, actor, tuple(ids))):
197
+ ids = [] # never split a batch; the next poll no longer selects the old item
198
+ response["messages"] = ids
199
+ if ids:
200
+ # Read-only sizing for the adapter's packing; an empty answer carries nothing more.
201
+ response["sizes"] = sizes
202
+ response["retry"] = retry
203
+ return response
204
+
205
+
206
+ def _blocked(db: Connection[dict[str, Any]], actor: Actor) -> bool:
207
+ state = db.execute(
208
+ """SELECT s.muted, i.stopped, i.plan_mode, i.native_state FROM agent_chat.sessions s
209
+ JOIN agent_chat.instances i ON i.session_id = s.id WHERE i.id = %s""",
210
+ (actor.instance_id,),
211
+ ).fetchone()
212
+ assert state is not None
213
+ return bool(state["muted"] or state["stopped"] or state["plan_mode"] or state["native_state"] == "unknown")
214
+
215
+
216
+ def _targets(db: Connection[dict[str, Any]], actor: Actor, ids: tuple[UUID, ...]) -> list[dict[str, Any]]:
217
+ # Resolve ownership before disclosing message existence. The clock excludes
218
+ # publication/pruning; grant locks then protect every selected room.
219
+ rows = db.execute(
220
+ """
221
+ SELECT m.*, r.delivery_batch_id, r.handed_at, r.acknowledged_at, r.replying_message_id,
222
+ r.uncertainty_reason, e.position
223
+ FROM agent_chat.messages m JOIN agent_chat.recipients r ON r.message_id = m.id
224
+ LEFT JOIN agent_chat.events e ON e.message_id = m.id AND e.kind = 'message'
225
+ WHERE m.id = ANY(%s::uuid[]) AND r.session_id = %s ORDER BY e.position, m.id
226
+ """,
227
+ (list(ids), actor.session_id),
228
+ ).fetchall()
229
+ if len(rows) != len(ids):
230
+ raise ChatError("NOT_FOUND")
231
+ # Each authorization rechecks the lease after its grant locks, which can block without changing any row.
232
+ for room in sorted({row["room_id"] for row in rows}):
233
+ authorize_message_room(db, actor, room)
234
+ _require_retained(db, ids)
235
+ return _recipient_state(db, actor, rows)
236
+
237
+
238
+ def _require_retained(db: Connection[dict[str, Any]], ids: tuple[UUID, ...]) -> None:
239
+ expired = db.execute(
240
+ "SELECT 1 FROM agent_chat.messages WHERE id = ANY(%s::uuid[]) "
241
+ "AND (body IS NULL OR expires_at <= clock_timestamp()) LIMIT 1",
242
+ (list(ids),),
243
+ ).fetchone()
244
+ if expired is not None:
245
+ raise ChatError("MESSAGE_EXPIRED")
246
+
247
+
248
+ def _recipient_state(db: Connection[dict[str, Any]], actor: Actor, rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
249
+ # Eligibility and age are read again after lock waits and settlement, so neither decision can be stale.
250
+ fresh = {
251
+ row["message_id"]: row
252
+ for row in db.execute(
253
+ """
254
+ SELECT message_id, delivery_batch_id, handed_at, acknowledged_at, replying_message_id, uncertainty_reason,
255
+ stored_at <= clock_timestamp() - make_interval(secs => %s) AS too_old
256
+ FROM agent_chat.recipients WHERE session_id = %s AND message_id = ANY(%s::uuid[])
257
+ """,
258
+ (DELIVERY_MAX_AGE_SECONDS, actor.session_id, [row["id"] for row in rows]),
259
+ ).fetchall()
260
+ }
261
+ for row in rows:
262
+ row.update({key: value for key, value in fresh[row["id"]].items() if key != "message_id"})
263
+ return rows
264
+
265
+
266
+ def _finish(
267
+ db: Connection[dict[str, Any]], attempt: dict[str, Any], outcome: str, reason: str | None
268
+ ) -> dict[str, Any]:
269
+ updated = db.execute(
270
+ """
271
+ UPDATE agent_chat.delivery_attempts SET outcome = %s, reason = %s, completed_at = clock_timestamp()
272
+ WHERE id = %s AND outcome IS NULL RETURNING *
273
+ """,
274
+ (outcome, reason, attempt["id"]),
275
+ ).fetchone()
276
+ assert updated is not None
277
+ changed = db.execute(
278
+ """
279
+ UPDATE agent_chat.recipients r SET
280
+ handed_at = CASE WHEN %s = 'handed' THEN COALESCE(r.handed_at, %s) ELSE r.handed_at END,
281
+ uncertainty_reason = CASE WHEN %s = 'uncertain' THEN COALESCE(r.uncertainty_reason, %s)
282
+ ELSE r.uncertainty_reason END
283
+ FROM agent_chat.messages m WHERE m.id = r.message_id AND r.delivery_batch_id = %s
284
+ AND m.body IS NOT NULL AND m.expires_at > clock_timestamp()
285
+ RETURNING r.message_id, r.session_id, m.room_id
286
+ """,
287
+ (outcome, updated["completed_at"], outcome, reason, attempt["batch_id"]),
288
+ ).fetchall()
289
+ for row in changed:
290
+ events.append(db, row["room_id"], "receipt", row["message_id"], row["session_id"])
291
+ if outcome == "handed":
292
+ # RETURNING lists every retained member of the batch whatever the outcome; only a handoff is a receipt.
293
+ receipts.record(db, "handed", [(row["message_id"], row["session_id"]) for row in changed])
294
+ return updated
295
+
296
+
297
+ def reconcile(
298
+ db: Connection[dict[str, Any]], limit: int = 100, session: UUID | None = None, instance_id: UUID | None = None
299
+ ) -> int:
300
+ """Caller holds clock first. Expired reservations are terminal, never reclaimed.
301
+
302
+ Return the number settled so a bounded maintenance loop can count this work as progress.
303
+ """
304
+ rows = db.execute(
305
+ """
306
+ SELECT a.* FROM agent_chat.delivery_attempts a JOIN agent_chat.instances i ON i.id = a.instance_id
307
+ WHERE a.outcome IS NULL AND (a.expires_at <= clock_timestamp() OR i.ended_at IS NOT NULL)
308
+ AND (%s::uuid IS NULL OR a.session_id = %s)
309
+ AND (%s::uuid IS NULL OR a.instance_id = %s)
310
+ ORDER BY a.expires_at, a.id LIMIT %s
311
+ """,
312
+ (session, session, instance_id, instance_id, limit),
313
+ ).fetchall()
314
+ for row in rows:
315
+ _finish(db, row, "uncertain", "claim_expired")
316
+ return len(rows)
317
+
318
+
319
+ def expire_undelivered(db: Connection[dict[str, Any]], limit: int = 100, session: UUID | None = None) -> int:
320
+ """Caller holds clock first. Settle items past the age limit that no open attempt still covers."""
321
+ changed = db.execute(
322
+ """
323
+ WITH due AS (
324
+ SELECT r.message_id, r.session_id FROM agent_chat.recipients r
325
+ JOIN agent_chat.messages m ON m.id = r.message_id
326
+ WHERE m.kind IN ('question', 'consultation', 'reply')
327
+ AND m.body IS NOT NULL AND m.expires_at > clock_timestamp()
328
+ AND r.handed_at IS NULL AND r.acknowledged_at IS NULL AND r.replying_message_id IS NULL
329
+ AND r.uncertainty_reason IS NULL
330
+ AND r.stored_at <= clock_timestamp() - make_interval(secs => %(max_age)s)
331
+ AND (%(session)s::uuid IS NULL OR r.session_id = %(session)s)
332
+ AND NOT EXISTS (SELECT 1 FROM agent_chat.delivery_attempts a
333
+ WHERE a.batch_id = r.delivery_batch_id AND a.outcome IS NULL)
334
+ ORDER BY r.stored_at, r.message_id, r.session_id LIMIT %(limit)s FOR UPDATE OF r
335
+ )
336
+ UPDATE agent_chat.recipients r SET uncertainty_reason = 'expired_undelivered'
337
+ FROM due JOIN agent_chat.messages m ON m.id = due.message_id
338
+ WHERE r.message_id = due.message_id AND r.session_id = due.session_id
339
+ RETURNING r.message_id, r.session_id, m.room_id
340
+ """,
341
+ {"max_age": DELIVERY_MAX_AGE_SECONDS, "session": session, "limit": limit},
342
+ ).fetchall()
343
+ for row in changed:
344
+ events.append(db, row["room_id"], "receipt", row["message_id"], row["session_id"])
345
+ return len(changed)
346
+
347
+
348
+ def _view(attempt: dict[str, Any]) -> dict[str, Any]:
349
+ return {
350
+ key: attempt[key]
351
+ for key in (
352
+ "id",
353
+ "batch_id",
354
+ "instance_id",
355
+ "ordinal",
356
+ "admitted_at",
357
+ "expires_at",
358
+ "outcome",
359
+ "reason",
360
+ "completed_at",
361
+ )
362
+ }
363
+
364
+
365
+ def _claim(
366
+ db: Connection[dict[str, Any]], actor: Actor, key: UUID, request: DeliveryClaim, rows: list[dict[str, Any]]
367
+ ) -> dict[str, Any]:
368
+ previous = db.execute(
369
+ """
370
+ SELECT a.*, b.message_ids FROM agent_chat.delivery_attempts a
371
+ JOIN agent_chat.delivery_batches b ON b.id = a.batch_id
372
+ WHERE a.session_id = %s AND a.request_key = %s
373
+ """,
374
+ (actor.session_id, key),
375
+ ).fetchone()
376
+ if previous is not None:
377
+ if tuple(previous["message_ids"]) != request.messages:
378
+ raise ChatError("IDEMPOTENCY_CONFLICT")
379
+ if previous["instance_id"] != actor.instance_id:
380
+ raise ChatError("STALE_INSTANCE")
381
+ return {"dispatch": False, "attempt": _view(previous), "messages": []}
382
+ if _blocked(db, actor):
383
+ raise ChatError("DELIVERY_BLOCKED")
384
+ if (
385
+ db.execute(
386
+ "SELECT 1 FROM agent_chat.delivery_attempts WHERE session_id = %s AND outcome IS NULL", (actor.session_id,)
387
+ ).fetchone()
388
+ is not None
389
+ ):
390
+ raise ChatError("DELIVERY_IN_FLIGHT")
391
+ batches = {row["delivery_batch_id"] for row in rows}
392
+ ordinal = 1
393
+ if batches != {None}:
394
+ if len(batches) != 1:
395
+ raise ChatError("DELIVERY_BATCH_CONFLICT")
396
+ batch_id = next(iter(batches))
397
+ batch = db.execute("SELECT message_ids FROM agent_chat.delivery_batches WHERE id = %s", (batch_id,)).fetchone()
398
+ # A recipient naming a batch that is gone is a stored inconsistency, not a caller error: refuse it
399
+ # with the same code as a mismatched batch instead of letting an AssertionError become INTERNAL_ERROR.
400
+ if batch is None or tuple(batch["message_ids"]) != request.messages:
401
+ raise ChatError("DELIVERY_BATCH_CONFLICT")
402
+ last = db.execute(
403
+ """
404
+ SELECT *, completed_at + make_interval(
405
+ secs => CASE WHEN ordinal = 1 THEN %s ELSE %s END
406
+ ) > clock_timestamp() AS backing_off
407
+ FROM agent_chat.delivery_attempts WHERE batch_id = %s ORDER BY ordinal DESC LIMIT 1
408
+ """,
409
+ (*BACKOFF_SECONDS, batch_id),
410
+ ).fetchone()
411
+ # A batch with no attempt has nothing to continue; retention keeps one alive only while it has attempts,
412
+ # so this is a defence-in-depth refusal rather than an assertion that would surface as INTERNAL_ERROR.
413
+ if last is None:
414
+ raise ChatError("DELIVERY_CLOSED")
415
+ if last["outcome"] not in ("failed", "deferred"):
416
+ raise ChatError("DELIVERY_CLOSED")
417
+ if last["ordinal"] >= 3:
418
+ raise ChatError("DELIVERY_EXHAUSTED")
419
+ if last["backing_off"]:
420
+ raise ChatError("DELIVERY_BACKOFF")
421
+ ordinal = last["ordinal"] + 1
422
+ else:
423
+ batch_id = uuid4()
424
+ if any(
425
+ row["kind"] not in ("question", "consultation", "reply")
426
+ or row["position"] is None
427
+ or row["too_old"]
428
+ or any(
429
+ row[field] is not None
430
+ for field in ("handed_at", "acknowledged_at", "replying_message_id", "uncertainty_reason")
431
+ )
432
+ for row in rows
433
+ ):
434
+ raise ChatError("DELIVERY_INELIGIBLE")
435
+ # The exclusive event clock already orders this read after every publication; it takes no row lock.
436
+ threads = consultations(db, {row["thread_id"] for row in rows})
437
+ if not all(thread["open"] for thread in threads.values()):
438
+ raise ChatError("CONSULTATION_LIMIT")
439
+ # Charged to `direct` only when every message is in a direct thread; a mixed set is charged to `other`.
440
+ allowance = "direct" if all(thread["direct"] for thread in threads.values()) else "other"
441
+ assert actor.session_id is not None
442
+ allowances = budget(db, actor.session_id)
443
+ if (allowances["direct"] if allowance == "direct" else allowances)["remaining"] == 0:
444
+ raise ChatError("WAKE_LIMIT")
445
+ if ordinal == 1:
446
+ db.execute(
447
+ "INSERT INTO agent_chat.delivery_batches VALUES (%s, %s, %s)",
448
+ (batch_id, actor.session_id, list(request.messages)),
449
+ )
450
+ db.execute(
451
+ "UPDATE agent_chat.recipients SET delivery_batch_id = %s WHERE session_id = %s "
452
+ "AND message_id = ANY(%s::uuid[])",
453
+ (batch_id, actor.session_id, list(request.messages)),
454
+ )
455
+ attempt = db.execute(
456
+ """
457
+ WITH instant AS MATERIALIZED (SELECT clock_timestamp() AS now)
458
+ INSERT INTO agent_chat.delivery_attempts(id, batch_id, session_id, instance_id, request_key,
459
+ ordinal, admitted_at, expires_at, allowance)
460
+ SELECT %s, %s, %s, i.id, %s, %s, instant.now,
461
+ LEAST(instant.now + interval '30 seconds', i.heartbeat_at + make_interval(secs => %s)), %s
462
+ FROM agent_chat.instances i CROSS JOIN instant WHERE i.id = %s AND i.ended_at IS NULL
463
+ AND i.heartbeat_at > instant.now - make_interval(secs => %s)
464
+ RETURNING *
465
+ """,
466
+ (
467
+ uuid4(),
468
+ batch_id,
469
+ actor.session_id,
470
+ key,
471
+ ordinal,
472
+ LEASE_SECONDS,
473
+ allowance,
474
+ actor.instance_id,
475
+ LEASE_SECONDS,
476
+ ),
477
+ ).fetchone()
478
+ if attempt is None:
479
+ raise ChatError("STALE_INSTANCE")
480
+ messages = []
481
+ for row in rows:
482
+ content = {key: row[key] for key in ("id", "room_id", "thread_id", "reply_to", "body", "kind", "created_at")}
483
+ content["history_after"] = str(row["position"] - 1)
484
+ content["sender"] = {"principal_id": row["sender_principal_id"], "session_id": row["sender_session_id"]}
485
+ messages.append(content)
486
+ events.append(db, row["room_id"], "receipt", row["id"], actor.session_id)
487
+ return {"dispatch": True, "attempt": _view(attempt), "messages": messages}
488
+
489
+
490
+ def claim(db: Connection[dict[str, Any]], actor: Actor, key: UUID, request: DeliveryClaim) -> dict[str, Any]:
491
+ with db.transaction():
492
+ events.lock(db)
493
+ lock_agent(db, actor)
494
+ try:
495
+ rows = _targets(db, actor, request.messages)
496
+ reconcile(db, session=actor.session_id)
497
+ expire_undelivered(db, session=actor.session_id)
498
+ rows = _recipient_state(db, actor, rows)
499
+ # A refusal rolls back only this admission, not expiry reconciliation.
500
+ with db.transaction():
501
+ return _claim(db, actor, key, request, rows)
502
+ except ChatError as caught:
503
+ reconcile(db, session=actor.session_id)
504
+ expire_undelivered(db, session=actor.session_id)
505
+ error = caught
506
+ raise error
507
+
508
+
509
+ def result(db: Connection[dict[str, Any]], actor: Actor, attempt_id: UUID, request: DeliveryResult) -> dict[str, Any]:
510
+ with db.transaction():
511
+ events.lock(db)
512
+ lock_agent(db, actor)
513
+ try:
514
+ attempt = db.execute(
515
+ """
516
+ SELECT a.*, b.message_ids FROM agent_chat.delivery_attempts a
517
+ JOIN agent_chat.delivery_batches b ON b.id = a.batch_id
518
+ WHERE a.id = %s AND a.session_id = %s AND a.instance_id = %s
519
+ """,
520
+ (attempt_id, actor.session_id, actor.instance_id),
521
+ ).fetchone()
522
+ if attempt is None:
523
+ raise ChatError("NOT_FOUND")
524
+ ids = tuple(attempt["message_ids"])
525
+ _targets(db, actor, ids)
526
+ # Keep expiry committed even if grant waits leave a late result refused.
527
+ reconcile(db, session=actor.session_id)
528
+ expire_undelivered(db, session=actor.session_id)
529
+ current = db.execute("SELECT * FROM agent_chat.delivery_attempts WHERE id = %s", (attempt_id,)).fetchone()
530
+ assert current is not None
531
+ if current["outcome"] is not None:
532
+ if (current["outcome"], current["reason"]) != (request.outcome, request.reason):
533
+ raise ChatError("DELIVERY_CLOSED")
534
+ return _view(current)
535
+ # A refusal rolls back only this settlement, not expiry reconciliation.
536
+ with db.transaction():
537
+ settled = _finish(db, current, request.outcome, request.reason)
538
+ # Its receipt's foreign-key checks can wait on row locks, such as the sender's session row.
539
+ # Recheck lease, retention and reservation after that wait.
540
+ require_live(db, actor)
541
+ _require_retained(db, ids)
542
+ reserved = db.execute(
543
+ "SELECT expires_at > clock_timestamp() AS reserved "
544
+ "FROM agent_chat.delivery_attempts WHERE id = %s",
545
+ (attempt_id,),
546
+ ).fetchone()
547
+ assert reserved is not None
548
+ if not reserved["reserved"]:
549
+ raise ChatError("DELIVERY_CLOSED")
550
+ return _view(settled)
551
+ except ChatError as caught:
552
+ reconcile(db, session=actor.session_id)
553
+ expire_undelivered(db, session=actor.session_id)
554
+ error = caught
555
+ raise error
agent_chat/events.py ADDED
@@ -0,0 +1,48 @@
1
+ """Clock-first mutations share one allocator; no transport or model work occurs here."""
2
+
3
+ from typing import Any, LiteralString
4
+ from uuid import UUID
5
+
6
+ from psycopg import Connection
7
+
8
+ from .models import ChatError
9
+
10
+ _SHARED = "SELECT position, retained_floor FROM agent_chat.event_clock WHERE singleton FOR SHARE"
11
+ _EXCLUSIVE = "SELECT position, retained_floor FROM agent_chat.event_clock WHERE singleton FOR UPDATE"
12
+
13
+
14
+ def _take(db: Connection[dict[str, Any]], query: LiteralString) -> dict[str, Any]:
15
+ row = db.execute(query).fetchone()
16
+ if row is None:
17
+ raise ChatError("SCHEMA_MISMATCH")
18
+ return row
19
+
20
+
21
+ def read_clock(db: Connection[dict[str, Any]]) -> dict[str, Any]:
22
+ """Hold the clock shared: a stable position and floor through this read, with publication and pruning excluded."""
23
+ return _take(db, _SHARED)
24
+
25
+
26
+ def lock(db: Connection[dict[str, Any]]) -> dict[str, Any]:
27
+ """Hold the clock exclusively. Every event-writing mutation takes this before any other row lock."""
28
+ return _take(db, _EXCLUSIVE)
29
+
30
+
31
+ def append(
32
+ db: Connection[dict[str, Any]],
33
+ room: UUID,
34
+ kind: str,
35
+ message: UUID | None = None,
36
+ session: UUID | None = None,
37
+ state_key: str | None = None,
38
+ ) -> None:
39
+ # The caller holds the clock before authorization and all other row locks.
40
+ db.execute(
41
+ """
42
+ WITH next_event AS (
43
+ UPDATE agent_chat.event_clock SET position = position + 1 WHERE singleton RETURNING position
44
+ ) INSERT INTO agent_chat.events(position, room_id, kind, message_id, session_id, state_key)
45
+ SELECT position, %s, %s, %s, %s, %s FROM next_event
46
+ """,
47
+ (room, kind, message, session, state_key),
48
+ )