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,252 @@
1
+ """One transaction owns publication and idempotency.
2
+
3
+ Actor is an internal authentication result. This module does not authenticate
4
+ bearer tokens and must not be exposed directly as an HTTP request schema.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ import json
10
+ from hashlib import sha256
11
+ from typing import Any
12
+ from uuid import UUID, uuid4
13
+
14
+ from psycopg import Connection
15
+
16
+ from . import deliveries, events, receipts, roles
17
+ from .auth import authorize_room, member, require_current
18
+ from .models import (
19
+ MAX_MESSAGES_PER_SESSION_HOUR,
20
+ QUOTA_WINDOW_SECONDS,
21
+ UNCOUNTED_KINDS,
22
+ Actor,
23
+ ChatError,
24
+ Publication,
25
+ )
26
+
27
+
28
+ def _recipients(db: Connection[dict[str, Any]], room: UUID, sessions: tuple[UUID, ...]) -> None:
29
+ for session in sessions:
30
+ if not member(db, room, session):
31
+ raise ChatError("INVALID_RECIPIENT")
32
+
33
+
34
+ def _conversation(
35
+ db: Connection[dict[str, Any]],
36
+ room: UUID,
37
+ request: Publication,
38
+ message_id: UUID,
39
+ ) -> tuple[UUID, UUID | None, bool]:
40
+ """Resolve the thread; also return the parent's sender, the default recipient of a reply, and whether the
41
+ thread already existed. An existing thread's row stays locked for `_count_reply`."""
42
+ thread_id = request.thread_id
43
+ default_recipient = None
44
+ if request.reply_to is not None:
45
+ parent = db.execute(
46
+ """
47
+ SELECT thread_id, sender_session_id, expires_at > clock_timestamp() AS retained
48
+ FROM agent_chat.messages WHERE id = %s AND room_id = %s FOR SHARE
49
+ """,
50
+ (request.reply_to, room),
51
+ ).fetchone()
52
+ if parent is None:
53
+ raise ChatError("NOT_FOUND")
54
+ if not parent["retained"]:
55
+ raise ChatError("MESSAGE_EXPIRED")
56
+ if thread_id is not None and thread_id != parent["thread_id"]:
57
+ raise ChatError("INVALID_REQUEST")
58
+ thread_id = parent["thread_id"]
59
+ if not request.recipients:
60
+ default_recipient = parent["sender_session_id"]
61
+ if request.ref_key is not None:
62
+ # Create-or-get is serialized by the event clock every publication holds exclusively. A key that
63
+ # pruning freed finds nothing here and starts a new thread.
64
+ keyed = db.execute(
65
+ "SELECT id FROM agent_chat.threads WHERE room_id = %s AND ref_key = %s", (room, request.ref_key)
66
+ ).fetchone()
67
+ thread_id = keyed["id"] if keyed is not None else None
68
+ if thread_id is None:
69
+ thread_id = uuid4()
70
+ db.execute(
71
+ "INSERT INTO agent_chat.threads(id, room_id, root_message_id, ref_key) VALUES (%s, %s, %s, %s)",
72
+ (thread_id, room, message_id, request.ref_key),
73
+ )
74
+ return thread_id, default_recipient, False
75
+ thread = db.execute(
76
+ """
77
+ SELECT 1 FROM agent_chat.threads WHERE id = %s AND room_id = %s FOR UPDATE
78
+ """,
79
+ (thread_id, room),
80
+ ).fetchone()
81
+ if thread is None:
82
+ raise ChatError("NOT_FOUND")
83
+ return thread_id, default_recipient, True
84
+
85
+
86
+ def _count_reply(
87
+ db: Connection[dict[str, Any]], thread_id: UUID, actor: Actor, operator: bool, recipients: tuple[UUID, ...]
88
+ ) -> None:
89
+ """Reset or count the reply against its thread's limit, judged on the participants this message leaves."""
90
+ if operator:
91
+ # The reset is the publication itself, not a timestamp: the count and its stamps clear together.
92
+ db.execute("UPDATE agent_chat.threads SET agent_replies = 0, loop_stamps = '{}' WHERE id = %s", (thread_id,))
93
+ return
94
+ assert actor.session_id is not None
95
+ # The thread row is locked (`_conversation`) and the event clock excludes every other publication.
96
+ if not deliveries.consultations(db, (thread_id,), (actor.session_id, *recipients))[thread_id]["open"]:
97
+ raise ChatError("CONSULTATION_LIMIT")
98
+ db.execute(
99
+ "UPDATE agent_chat.threads SET agent_replies = agent_replies + 1, "
100
+ "loop_stamps = loop_stamps || clock_timestamp() WHERE id = %s",
101
+ (thread_id,),
102
+ )
103
+
104
+
105
+ def _join(db: Connection[dict[str, Any]], thread_id: UUID, actor: Actor, recipients: tuple[UUID, ...]) -> None:
106
+ """Record the sessions this message adds to its thread: its sender, if a session, and its recipients."""
107
+ sessions = [session for session in (actor.session_id, *recipients) if session is not None]
108
+ # The thread row is locked (`_conversation`) or new in this transaction. Nothing is written when none is new.
109
+ db.execute(
110
+ """
111
+ UPDATE agent_chat.threads
112
+ SET participants = participants || ARRAY(
113
+ SELECT DISTINCT member FROM unnest(%(sessions)s::uuid[]) AS member WHERE member <> ALL(participants)
114
+ )
115
+ WHERE id = %(thread)s AND NOT participants @> %(sessions)s::uuid[]
116
+ """,
117
+ {"sessions": sessions, "thread": thread_id},
118
+ )
119
+
120
+
121
+ def _message(db: Connection[dict[str, Any]], message_id: UUID) -> dict[str, Any]:
122
+ row = db.execute(
123
+ """
124
+ SELECT m.id, m.room_id, m.thread_id, m.reply_to, m.body, m.kind, m.sender_principal_id,
125
+ m.sender_session_id, m.sender_role, m.created_at, t.ref_key AS thread_ref_key,
126
+ t.resolved_at AS thread_resolved_at
127
+ FROM agent_chat.messages m JOIN agent_chat.threads t ON t.id = m.thread_id
128
+ WHERE m.id = %s AND m.expires_at > clock_timestamp() AND m.body IS NOT NULL
129
+ """,
130
+ (message_id,),
131
+ ).fetchone()
132
+ if row is None:
133
+ raise ChatError("MESSAGE_EXPIRED")
134
+ row["recipients"] = [
135
+ item["session_id"]
136
+ for item in db.execute(
137
+ "SELECT session_id FROM agent_chat.recipients WHERE message_id = %s ORDER BY session_id",
138
+ (message_id,),
139
+ ).fetchall()
140
+ ]
141
+ return row
142
+
143
+
144
+ def request_digest(room: UUID, request: Publication) -> str:
145
+ canonical = request.model_dump(mode="json")
146
+ # Requests stored before migration 002 were hashed without ref_key; an unkeyed request keeps that form so a
147
+ # replay across the upgrade still matches. Other null fields stay, as the stored digests include them.
148
+ if canonical["ref_key"] is None:
149
+ del canonical["ref_key"]
150
+ # Likewise a request without the receipts opt-in (migration 007) keeps its earlier digest.
151
+ if not canonical["receipts"]:
152
+ del canonical["receipts"]
153
+ return sha256(
154
+ json.dumps(
155
+ {"room_id": str(room), "request": canonical},
156
+ sort_keys=True,
157
+ ensure_ascii=False,
158
+ separators=(",", ":"),
159
+ ).encode("utf-8")
160
+ ).hexdigest()
161
+
162
+
163
+ def publish(
164
+ db: Connection[dict[str, Any]],
165
+ actor: Actor,
166
+ room: UUID,
167
+ key: UUID,
168
+ request: Publication,
169
+ ) -> dict[str, Any]:
170
+ digest = request_digest(room, request)
171
+ scope = actor.session_id or actor.principal_id
172
+ with db.transaction():
173
+ # All event-writing mutations must acquire this lock before any other row locks.
174
+ events.lock(db)
175
+ access = authorize_room(db, actor, room)
176
+ operator = access == "operator"
177
+ previous = db.execute(
178
+ """
179
+ SELECT digest, message_id FROM agent_chat.requests
180
+ WHERE principal_id = %s AND scope_id = %s AND key = %s
181
+ """,
182
+ (actor.principal_id, scope, key),
183
+ ).fetchone()
184
+ if previous is not None:
185
+ if previous["digest"] != digest:
186
+ raise ChatError("IDEMPOTENCY_CONFLICT")
187
+ return _message(db, previous["message_id"])
188
+ if actor.session_id is not None:
189
+ # The exclusive event clock already serializes every publication, so this count is exact.
190
+ sent = db.execute(
191
+ """
192
+ SELECT count(*) AS n FROM agent_chat.messages
193
+ WHERE sender_session_id = %s AND created_at > clock_timestamp() - make_interval(secs => %s)
194
+ """,
195
+ (actor.session_id, QUOTA_WINDOW_SECONDS),
196
+ ).fetchone()
197
+ assert sent is not None
198
+ if sent["n"] >= MAX_MESSAGES_PER_SESSION_HOUR:
199
+ raise ChatError("PUBLICATION_LIMIT")
200
+ message_id = uuid4()
201
+ thread_id, default_recipient, existing = _conversation(db, room, request, message_id)
202
+ recipients = request.recipients
203
+ # The parent's sender may have left the room since. That drops the default, not the reply.
204
+ if default_recipient is not None and member(db, room, default_recipient):
205
+ recipients = (default_recipient,)
206
+ _recipients(db, room, recipients)
207
+ # A root is never counted. Status and coordination kinds are exempt: nothing delivers them, so none drives
208
+ # a session to answer. The final recipients decide whether the thread is direct after this message.
209
+ if existing and request.kind not in UNCOUNTED_KINDS:
210
+ _count_reply(db, thread_id, actor, operator, recipients)
211
+ # Every check that can refuse for the request's own sake has run. The stamp and the mark's extension are one
212
+ # statement; the late lease check below still rolls both back with the message.
213
+ role = roles.stamp(db, room, actor)
214
+ db.execute(
215
+ """
216
+ INSERT INTO agent_chat.messages
217
+ (id, room_id, thread_id, reply_to, sender_principal_id, sender_session_id, kind, body,
218
+ receipts_requested, sender_role)
219
+ VALUES (%s, %s, %s, %s, %s, %s, %s, %s, %s, %s)
220
+ """,
221
+ (
222
+ message_id,
223
+ room,
224
+ thread_id,
225
+ request.reply_to,
226
+ actor.principal_id,
227
+ actor.session_id,
228
+ request.kind,
229
+ request.body,
230
+ request.receipts,
231
+ role,
232
+ ),
233
+ )
234
+ for recipient in recipients:
235
+ db.execute(
236
+ "INSERT INTO agent_chat.recipients(message_id, session_id) VALUES (%s, %s)", (message_id, recipient)
237
+ )
238
+ _join(db, thread_id, actor, recipients)
239
+ db.execute(
240
+ """
241
+ INSERT INTO agent_chat.requests(principal_id, scope_id, key, digest, message_id)
242
+ VALUES (%s, %s, %s, %s, %s)
243
+ """,
244
+ (actor.principal_id, scope, key, digest, message_id),
245
+ )
246
+ events.append(db, room, "message", message_id)
247
+ if request.reply_to is not None and actor.session_id is not None:
248
+ receipts.replied(db, actor, room, request.reply_to, message_id)
249
+ # Recipient administration and the reply receipt can wait after room authorization. A late
250
+ # expiry must roll back every publication record, including events and the first-reply receipt.
251
+ require_current(db, actor, access)
252
+ return _message(db, message_id)
agent_chat/receipts.py ADDED
@@ -0,0 +1,225 @@
1
+ """Recipient processing declarations are separate from transport evidence.
2
+
3
+ This module also owns sender receipts: a non-waking ledger that tells the sending session its message reached
4
+ `handed` or `acked` (migration 007). A `replied` receipt is the reply message itself and follows the wake rules.
5
+ """
6
+
7
+ from __future__ import annotations
8
+
9
+ from collections.abc import Iterable
10
+ from typing import Any, Literal
11
+ from uuid import UUID, uuid4
12
+
13
+ from psycopg import Connection
14
+
15
+ from . import events, roles
16
+ from .auth import authorize_message_room, lock_actor, lock_agent, require_live
17
+ from .models import RECEIPT_FEED_LIMIT, Actor, ChatError, ReceiptDelivery
18
+ from .rooms import visible
19
+
20
+ # Kinds that carry sender receipts by default, and kinds that carry them only when the sender opted in.
21
+ # Every other kind (status, models.COORDINATION_KINDS) never does: this is an allowlist, so a new kind starts without.
22
+ RECEIPTS_BY_DEFAULT = ("question", "consultation")
23
+ RECEIPTS_ON_REQUEST = ("message", "reply")
24
+
25
+
26
+ def eligible(kind: str, requested: bool, sender_session: UUID | None) -> bool:
27
+ """The one receipt policy. Callers apply it to an addressed message, so `addressed` is implied.
28
+
29
+ An operator or browser publication has no sending session and nobody to notify.
30
+ """
31
+ if sender_session is None:
32
+ return False
33
+ return kind in RECEIPTS_BY_DEFAULT or (kind in RECEIPTS_ON_REQUEST and requested)
34
+
35
+
36
+ def record(
37
+ db: Connection[dict[str, Any]], state: Literal["handed", "acked"], reached: Iterable[tuple[UUID, UUID]]
38
+ ) -> None:
39
+ """Record one sender receipt per (message, recipient) that just reached `state`, where the policy allows.
40
+
41
+ Called only inside the transaction that made that state change, under the exclusive event clock. A repeat
42
+ creates nothing (`ON CONFLICT DO NOTHING`). It writes no replay event and touches no delivery or wake ledger,
43
+ so it can wake nothing.
44
+ """
45
+ pairs = list(reached)
46
+ if not pairs:
47
+ return
48
+ senders = {
49
+ row["id"]: row["sender_session_id"]
50
+ for row in db.execute(
51
+ "SELECT id, kind, sender_session_id, receipts_requested FROM agent_chat.messages "
52
+ "WHERE id = ANY(%s::uuid[])",
53
+ ([message for message, _recipient in pairs],),
54
+ ).fetchall()
55
+ if eligible(row["kind"], row["receipts_requested"], row["sender_session_id"])
56
+ }
57
+ for message, recipient in pairs:
58
+ if message in senders:
59
+ db.execute(
60
+ """
61
+ INSERT INTO agent_chat.sender_receipts(id, message_id, sender_session_id, state, recipient_session_id)
62
+ VALUES (%s, %s, %s, %s, %s) ON CONFLICT (message_id, recipient_session_id, state) DO NOTHING
63
+ """,
64
+ (uuid4(), message, senders[message], state, recipient),
65
+ )
66
+
67
+
68
+ _UNDELIVERED = """
69
+ SELECT sr.id, sr.message_id, sr.state, sr.recipient_session_id, p.harness AS recipient_harness,
70
+ p.host AS recipient_host, sr.created_at
71
+ FROM agent_chat.sender_receipts sr JOIN agent_chat.messages m ON m.id = sr.message_id
72
+ JOIN agent_chat.sessions s ON s.id = sr.recipient_session_id
73
+ JOIN agent_chat.principals p ON p.id = s.principal_id
74
+ WHERE sr.sender_session_id = %s AND sr.delivered_at IS NULL
75
+ AND m.room_id = ANY(%s::uuid[]) AND m.body IS NOT NULL AND m.expires_at > clock_timestamp()
76
+ ORDER BY sr.created_at, sr.id LIMIT %s
77
+ """
78
+
79
+
80
+ def sender_feed(db: Connection[dict[str, Any]], actor: Actor) -> dict[str, Any]:
81
+ """The live instance's own undelivered receipts, oldest first; reading marks nothing delivered.
82
+
83
+ Only receipts of retained messages in rooms the session may still read are shown.
84
+ """
85
+ with db.transaction():
86
+ events.read_clock(db)
87
+ lock_agent(db, actor)
88
+ rooms = [room["id"] for room in visible(db, actor)]
89
+ rows = db.execute(_UNDELIVERED, (actor.session_id, rooms, RECEIPT_FEED_LIMIT)).fetchall()
90
+ return {"session_id": actor.session_id, "instance_id": actor.instance_id, "receipts": rows}
91
+
92
+
93
+ def mark_delivered(db: Connection[dict[str, Any]], actor: Actor, request: ReceiptDelivery) -> dict[str, Any]:
94
+ """Record that the adapter output these receipts. Idempotent; IDs of another session are ignored, not disclosed.
95
+
96
+ `delivered` lists the requested IDs the session owns, whether this call or an earlier one marked them.
97
+ """
98
+ with db.transaction():
99
+ events.read_clock(db)
100
+ lock_agent(db, actor)
101
+ rows = db.execute(
102
+ """
103
+ UPDATE agent_chat.sender_receipts SET delivered_at = COALESCE(delivered_at, clock_timestamp())
104
+ WHERE id = ANY(%s::uuid[]) AND sender_session_id = %s RETURNING id
105
+ """,
106
+ (list(request.receipts), actor.session_id),
107
+ ).fetchall()
108
+ # The UPDATE can wait on a receipt row lock. Recheck the lease after that wait.
109
+ require_live(db, actor)
110
+ return {
111
+ "session_id": actor.session_id,
112
+ "instance_id": actor.instance_id,
113
+ "delivered": sorted(row["id"] for row in rows),
114
+ }
115
+
116
+
117
+ def snapshots(db: Connection[dict[str, Any]], messages: list[UUID]) -> dict[UUID, list[dict[str, Any]]]:
118
+ # Callers supply only authorized message IDs while holding the read/write clock.
119
+ # An unsettled claim whose reservation expired or whose instance ended is shown as the outcome
120
+ # `deliveries.reconcile` will persist, so a dead adapter never leaves a receipt `claimed`.
121
+ rows = db.execute(
122
+ """
123
+ SELECT r.message_id, r.session_id, r.stored_at, r.handed_at, r.acknowledged_at,
124
+ r.replying_message_id, r.uncertainty_reason, s.title, p.harness, p.host, s.native_session_id,
125
+ CASE WHEN a.id IS NOT NULL THEN jsonb_build_object(
126
+ 'attempt', a.ordinal,
127
+ 'outcome', CASE WHEN a.outcome IS NOT NULL THEN a.outcome
128
+ WHEN a.lapsed THEN 'uncertain' ELSE 'claimed' END,
129
+ 'reason', CASE WHEN a.outcome IS NULL AND a.lapsed THEN 'claim_expired' ELSE a.reason END
130
+ ) END AS delivery
131
+ FROM agent_chat.recipients r JOIN agent_chat.messages m ON m.id = r.message_id
132
+ JOIN agent_chat.sessions s ON s.id = r.session_id
133
+ JOIN agent_chat.principals p ON p.id = s.principal_id
134
+ LEFT JOIN LATERAL (
135
+ SELECT d.id, d.ordinal, d.outcome, d.reason,
136
+ d.expires_at <= clock_timestamp() OR i.ended_at IS NOT NULL AS lapsed
137
+ FROM agent_chat.delivery_attempts d JOIN agent_chat.instances i ON i.id = d.instance_id
138
+ WHERE d.batch_id = r.delivery_batch_id ORDER BY d.ordinal DESC LIMIT 1
139
+ ) a ON true
140
+ WHERE r.message_id = ANY(%s::uuid[]) AND m.expires_at > clock_timestamp() AND m.body IS NOT NULL
141
+ ORDER BY r.message_id, r.session_id
142
+ """,
143
+ (messages,),
144
+ ).fetchall()
145
+ result: dict[UUID, list[dict[str, Any]]] = {}
146
+ for row in rows:
147
+ result.setdefault(row["message_id"], []).append(row)
148
+ return result
149
+
150
+
151
+ def locate(db: Connection[dict[str, Any]], actor: Actor, message: UUID) -> dict[str, Any]:
152
+ """Caller holds the clock. This mutation helper never admits viewer access or discloses hidden IDs."""
153
+ lock_actor(db, actor)
154
+ row = db.execute(
155
+ """
156
+ SELECT id, room_id, thread_id
157
+ FROM agent_chat.messages WHERE id = %s
158
+ """,
159
+ (message,),
160
+ ).fetchone()
161
+ if row is None:
162
+ raise ChatError("NOT_FOUND")
163
+ authorize_message_room(db, actor, row["room_id"])
164
+ return row
165
+
166
+
167
+ def target(db: Connection[dict[str, Any]], actor: Actor, message: UUID) -> dict[str, Any]:
168
+ """`locate` a message that must still be retained."""
169
+ row = locate(db, actor, message)
170
+ # Authorization can wait for grant locks. Evaluate expiry after those waits.
171
+ retained = db.execute(
172
+ "SELECT body IS NOT NULL AND expires_at > clock_timestamp() AS retained "
173
+ "FROM agent_chat.messages WHERE id = %s",
174
+ (message,),
175
+ ).fetchone()
176
+ if retained is None or not retained["retained"]:
177
+ raise ChatError("MESSAGE_EXPIRED")
178
+ return row
179
+
180
+
181
+ def acknowledge(db: Connection[dict[str, Any]], actor: Actor, message: UUID) -> dict[str, Any]:
182
+ with db.transaction():
183
+ events.lock(db)
184
+ lock_agent(db, actor)
185
+ parent = target(db, actor, message)
186
+ changed = db.execute(
187
+ """
188
+ UPDATE agent_chat.recipients SET acknowledged_at = clock_timestamp()
189
+ WHERE message_id = %s AND session_id = %s AND acknowledged_at IS NULL
190
+ """,
191
+ (message, actor.session_id),
192
+ ).rowcount
193
+ if changed:
194
+ assert actor.session_id is not None
195
+ # Its foreign-key checks can wait on row locks, so it precedes the lease recheck below.
196
+ record(db, "acked", [(message, actor.session_id)])
197
+ # A first acknowledgement is the holder's own action in the message's room; a repeat changes nothing.
198
+ roles.touch(db, parent["room_id"], actor.session_id)
199
+ # The UPDATE can wait on the recipient row lock. Recheck lease and retention after that wait.
200
+ require_live(db, actor)
201
+ current = next(
202
+ (row for row in snapshots(db, [message]).get(message, []) if row["session_id"] == actor.session_id), None
203
+ )
204
+ if current is None:
205
+ recipient = db.execute(
206
+ "SELECT 1 FROM agent_chat.recipients WHERE message_id = %s AND session_id = %s",
207
+ (message, actor.session_id),
208
+ ).fetchone()
209
+ raise ChatError("MESSAGE_EXPIRED" if recipient else "SESSION_FORBIDDEN")
210
+ if changed:
211
+ events.append(db, parent["room_id"], "receipt", message, actor.session_id)
212
+ return current
213
+
214
+
215
+ def replied(db: Connection[dict[str, Any]], actor: Actor, room: UUID, parent: UUID, reply: UUID) -> None:
216
+ """Called only inside publication's clock-locked transaction; first reply wins."""
217
+ changed = db.execute(
218
+ """
219
+ UPDATE agent_chat.recipients SET replying_message_id = %s
220
+ WHERE message_id = %s AND session_id = %s AND replying_message_id IS NULL
221
+ """,
222
+ (reply, parent, actor.session_id),
223
+ ).rowcount
224
+ if changed:
225
+ events.append(db, room, "receipt", parent, actor.session_id)
@@ -0,0 +1,154 @@
1
+ """Bounded maintenance transactions; no scheduler or startup side effect."""
2
+
3
+ from typing import Any
4
+
5
+ from psycopg import Connection
6
+
7
+ from . import deliveries, events
8
+ from .models import WAKE_WINDOW_SECONDS, ChatError
9
+
10
+
11
+ def prune(db: Connection[dict[str, Any]], limit: int = 100) -> dict[str, int]:
12
+ if not 1 <= limit <= 1000:
13
+ raise ChatError("INVALID_REQUEST")
14
+ with db.transaction():
15
+ clock = events.lock(db)
16
+ # Age out memberships first so a session whose instance is ended below keeps its membership for this pass:
17
+ # a message addressed to the session stays acceptable for a week after its last heartbeat. The 168 hours
18
+ # (seven days) far exceed the lease; rejoining recreates the row (`INSERT ... ON CONFLICT DO NOTHING`).
19
+ memberships = db.execute(
20
+ """
21
+ DELETE FROM agent_chat.memberships WHERE (room_id, session_id) IN (
22
+ SELECT m.room_id, m.session_id FROM agent_chat.memberships m
23
+ LEFT JOIN LATERAL (
24
+ SELECT max(i.heartbeat_at) AS last_seen, bool_or(i.ended_at IS NULL) AS open
25
+ FROM agent_chat.instances i WHERE i.session_id = m.session_id
26
+ ) seen ON true
27
+ WHERE NOT COALESCE(seen.open, false)
28
+ AND COALESCE(seen.last_seen <= clock_timestamp() - interval '168 hours', true)
29
+ ORDER BY seen.last_seen NULLS FIRST, m.room_id, m.session_id LIMIT %s FOR UPDATE OF m
30
+ )
31
+ """,
32
+ (limit,),
33
+ ).rowcount
34
+ # End instances whose heartbeat lapsed a day ago, before reconcile, so the same pass settles their attempts.
35
+ # A live worker heartbeats every 30 seconds against a 90 second lease; only dead processes match.
36
+ ended_instances = db.execute(
37
+ """
38
+ WITH lapsed AS (
39
+ SELECT id FROM agent_chat.instances
40
+ WHERE ended_at IS NULL AND heartbeat_at <= clock_timestamp() - interval '24 hours'
41
+ ORDER BY heartbeat_at, id LIMIT %s FOR UPDATE
42
+ ) UPDATE agent_chat.instances SET ended_at = clock_timestamp()
43
+ WHERE id IN (SELECT id FROM lapsed) RETURNING id
44
+ """,
45
+ (limit,),
46
+ ).rowcount
47
+ reservations = deliveries.reconcile(db, limit=limit)
48
+ expired_undelivered = deliveries.expire_undelivered(db, limit=limit)
49
+ # Expire only a cursor prefix. A backwards wall-clock adjustment must not
50
+ # expire a later event while silently skipping an earlier retained event.
51
+ tail = db.execute(
52
+ """
53
+ SELECT position, created_at <= clock_timestamp() - interval '720 hours' AS expired
54
+ FROM agent_chat.events ORDER BY position LIMIT %s
55
+ """,
56
+ (limit,),
57
+ ).fetchall()
58
+ floor = clock["retained_floor"]
59
+ for event in tail:
60
+ if not event["expired"]:
61
+ break
62
+ floor = event["position"]
63
+ removed_events = db.execute("DELETE FROM agent_chat.events WHERE position <= %s", (floor,)).rowcount
64
+ db.execute("UPDATE agent_chat.event_clock SET retained_floor = %s WHERE singleton", (floor,))
65
+ redacted = db.execute(
66
+ """
67
+ WITH expired AS (
68
+ SELECT id FROM agent_chat.messages
69
+ WHERE expires_at <= clock_timestamp() AND body IS NOT NULL
70
+ ORDER BY expires_at, id LIMIT %s FOR UPDATE
71
+ ) UPDATE agent_chat.messages SET body = NULL
72
+ WHERE id IN (SELECT id FROM expired) RETURNING id
73
+ """,
74
+ (limit,),
75
+ ).fetchall()
76
+ ids = [row["id"] for row in redacted]
77
+ db.execute("DELETE FROM agent_chat.requests WHERE message_id = ANY(%s)", (ids,))
78
+ db.execute("DELETE FROM agent_chat.recipients WHERE message_id = ANY(%s)", (ids,))
79
+ # Keep admission evidence even if its message just expired. A resume or
80
+ # prune must not refill the rolling wake budget. No content is stored here.
81
+ removed_batches = db.execute(
82
+ """
83
+ DELETE FROM agent_chat.delivery_batches b WHERE b.id IN (
84
+ SELECT candidate.id FROM agent_chat.delivery_batches candidate
85
+ WHERE NOT EXISTS (SELECT 1 FROM agent_chat.recipients r WHERE r.delivery_batch_id = candidate.id)
86
+ AND NOT EXISTS (SELECT 1 FROM agent_chat.delivery_attempts a WHERE a.batch_id = candidate.id
87
+ AND (a.outcome IS NULL
88
+ OR a.admitted_at > clock_timestamp() - make_interval(secs => %s)))
89
+ ORDER BY candidate.id LIMIT %s
90
+ )
91
+ """,
92
+ (WAKE_WINDOW_SECONDS, limit),
93
+ ).rowcount
94
+ # Remove leaf tombstones only. A retained child or event keeps its parent.
95
+ # Subsequent batches collect ancestors, including the final thread root.
96
+ deleted = db.execute(
97
+ """
98
+ WITH leaves AS (
99
+ SELECT m.id FROM agent_chat.messages m
100
+ JOIN agent_chat.threads t ON t.id = m.thread_id
101
+ WHERE m.body IS NULL
102
+ AND NOT EXISTS (SELECT 1 FROM agent_chat.messages child WHERE child.reply_to = m.id)
103
+ AND NOT EXISTS (SELECT 1 FROM agent_chat.events e WHERE e.message_id = m.id)
104
+ AND NOT EXISTS (SELECT 1 FROM agent_chat.recipients r WHERE r.replying_message_id = m.id)
105
+ AND (m.id <> t.root_message_id OR NOT EXISTS (
106
+ SELECT 1 FROM agent_chat.messages sibling WHERE sibling.thread_id = t.id AND sibling.id <> m.id
107
+ ))
108
+ ORDER BY m.expires_at, m.id LIMIT %s FOR UPDATE OF m
109
+ ) DELETE FROM agent_chat.messages WHERE id IN (SELECT id FROM leaves) RETURNING thread_id
110
+ """,
111
+ (limit,),
112
+ ).fetchall()
113
+ db.execute(
114
+ """
115
+ DELETE FROM agent_chat.threads t WHERE id = ANY(%s)
116
+ AND NOT EXISTS (SELECT 1 FROM agent_chat.messages m WHERE m.thread_id = t.id)
117
+ """,
118
+ ([row["thread_id"] for row in deleted],),
119
+ )
120
+ # Authentication expiry is eight hours, not the conversation retention window.
121
+ removed_browser_sessions = db.execute(
122
+ """
123
+ DELETE FROM agent_chat.browser_sessions WHERE token_hash IN (
124
+ SELECT token_hash FROM agent_chat.browser_sessions
125
+ WHERE expires_at <= clock_timestamp() ORDER BY expires_at, token_hash LIMIT %s FOR UPDATE
126
+ )
127
+ """,
128
+ (limit,),
129
+ ).rowcount
130
+ # Room state rows are independent of events; one that expired long ago is no longer worth showing as stale.
131
+ removed_state = db.execute(
132
+ """
133
+ DELETE FROM agent_chat.room_state WHERE (room_id, state_key) IN (
134
+ SELECT room_id, state_key FROM agent_chat.room_state
135
+ WHERE expires_at <= clock_timestamp() - interval '720 hours'
136
+ ORDER BY expires_at, room_id, state_key LIMIT %s FOR UPDATE
137
+ )
138
+ """,
139
+ (limit,),
140
+ ).rowcount
141
+ return {
142
+ "events": removed_events,
143
+ "redacted": len(redacted),
144
+ "deleted": len(deleted),
145
+ "ended_instances": ended_instances,
146
+ "memberships": memberships,
147
+ "expired_undelivered": expired_undelivered,
148
+ # Every other progress-making operation belongs in the maintenance
149
+ # result too; admin.prune stops on a result whose counts are all zero.
150
+ "reservations": reservations,
151
+ "delivery_batches": removed_batches,
152
+ "browser_sessions": removed_browser_sessions,
153
+ "room_state": removed_state,
154
+ }