robert-github-agent 0.1.0b1__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 (111) hide show
  1. robert_agent/__init__.py +1 -0
  2. robert_agent/acceptance.py +394 -0
  3. robert_agent/acceptance_suite.py +287 -0
  4. robert_agent/audit_result.py +501 -0
  5. robert_agent/authorize.py +117 -0
  6. robert_agent/board.py +538 -0
  7. robert_agent/chat_status.py +338 -0
  8. robert_agent/cli/__init__.py +1 -0
  9. robert_agent/cli/exit_codes.py +5 -0
  10. robert_agent/cli/main.py +535 -0
  11. robert_agent/cli/output.py +20 -0
  12. robert_agent/common.py +6 -0
  13. robert_agent/controlled_e2e_acceptance.py +394 -0
  14. robert_agent/daemon.py +607 -0
  15. robert_agent/daemon_state.py +319 -0
  16. robert_agent/diagnostics.py +119 -0
  17. robert_agent/discover.py +775 -0
  18. robert_agent/dispatch.py +217 -0
  19. robert_agent/doctor.py +94 -0
  20. robert_agent/github_api.py +12 -0
  21. robert_agent/init_config.py +126 -0
  22. robert_agent/integrations/__init__.py +1 -0
  23. robert_agent/integrations/openclaw.py +285 -0
  24. robert_agent/live_discovery_acceptance.py +70 -0
  25. robert_agent/live_worker_acceptance.py +363 -0
  26. robert_agent/live_worktree_acceptance.py +344 -0
  27. robert_agent/loop_engine.py +285 -0
  28. robert_agent/memory_curator.py +105 -0
  29. robert_agent/migrate.py +157 -0
  30. robert_agent/notify.py +74 -0
  31. robert_agent/paths.py +16 -0
  32. robert_agent/production_write_canary.py +254 -0
  33. robert_agent/project_memory.py +503 -0
  34. robert_agent/publish.py +743 -0
  35. robert_agent/publish_dedupe_acceptance.py +270 -0
  36. robert_agent/redaction.py +41 -0
  37. robert_agent/render_prompt.py +544 -0
  38. robert_agent/resource_files.py +8 -0
  39. robert_agent/resources/__init__.py +1 -0
  40. robert_agent/resources/acceptance-matrix.md +120 -0
  41. robert_agent/resources/classifier.md +19 -0
  42. robert_agent/resources/command-matrix.md +38 -0
  43. robert_agent/resources/config.example.yml +20 -0
  44. robert_agent/resources/db/migrations/001_legacy_dd_to_robert.sql +14 -0
  45. robert_agent/resources/db/schema.sql +479 -0
  46. robert_agent/resources/failure-modes.md +36 -0
  47. robert_agent/resources/fixtures/actor-permission.json +1 -0
  48. robert_agent/resources/fixtures/discovery.json +1 -0
  49. robert_agent/resources/fixtures/redaction.json +1 -0
  50. robert_agent/resources/fixtures/review-followup.json +1 -0
  51. robert_agent/resources/fixtures/worker-results.json +1 -0
  52. robert_agent/resources/fixtures/workstreams.json +1 -0
  53. robert_agent/resources/github-events.md +77 -0
  54. robert_agent/resources/kanban-control.md +165 -0
  55. robert_agent/resources/redaction.md +29 -0
  56. robert_agent/resources/result-contract.md +56 -0
  57. robert_agent/resources/routes.yml +82 -0
  58. robert_agent/resources/schemas/config.schema.json +123 -0
  59. robert_agent/resources/schemas/event.schema.json +18 -0
  60. robert_agent/resources/schemas/result.schema.json +99 -0
  61. robert_agent/resources/schemas/route.schema.json +23 -0
  62. robert_agent/resources/schemas/snapshot.schema.json +17 -0
  63. robert_agent/resources/schemas/task.schema.json +15 -0
  64. robert_agent/resources/trust-model.md +16 -0
  65. robert_agent/resources/worker-prompt.md +121 -0
  66. robert_agent/resources/worker-protocol.md +47 -0
  67. robert_agent/resources/workflow.yml +50 -0
  68. robert_agent/resources/workstream-model.md +17 -0
  69. robert_agent/route.py +232 -0
  70. robert_agent/route_config.py +64 -0
  71. robert_agent/run_once.py +5375 -0
  72. robert_agent/runtime_knowledge.py +392 -0
  73. robert_agent/service.py +161 -0
  74. robert_agent/skills.py +28 -0
  75. robert_agent/status.py +1051 -0
  76. robert_agent/storage.py +376 -0
  77. robert_agent/summarize.py +100 -0
  78. robert_agent/supervise.py +72 -0
  79. robert_agent/usage.py +192 -0
  80. robert_agent/validate_config.py +616 -0
  81. robert_agent/wakeup.py +261 -0
  82. robert_agent/web.py +2893 -0
  83. robert_agent/web_assets/board.css +255 -0
  84. robert_agent/web_assets/board.html +165 -0
  85. robert_agent/web_assets/board.js +660 -0
  86. robert_agent/web_assets/github-shell.css +122 -0
  87. robert_agent/web_assets/index.html +103 -0
  88. robert_agent/web_assets/operations.css +168 -0
  89. robert_agent/web_assets/workbench.css +131 -0
  90. robert_agent/web_assets/workbench.js +581 -0
  91. robert_agent/work_items.py +1016 -0
  92. robert_agent/workbench.py +701 -0
  93. robert_agent/worker/__init__.py +1 -0
  94. robert_agent/worker/heartbeat.py +190 -0
  95. robert_agent/worker/result.py +321 -0
  96. robert_agent/worker/snapshot.py +98 -0
  97. robert_agent/worker_adapters/__init__.py +138 -0
  98. robert_agent/worker_adapters/cbc.py +68 -0
  99. robert_agent/worker_adapters/codex.py +56 -0
  100. robert_agent/worker_adapters/command.py +33 -0
  101. robert_agent/worker_adapters/tcodex.py +56 -0
  102. robert_agent/worker_heartbeat.py +6 -0
  103. robert_agent/worker_result.py +6 -0
  104. robert_agent/worker_snapshot.py +6 -0
  105. robert_agent/workstream.py +55 -0
  106. robert_agent/worktree.py +297 -0
  107. robert_github_agent-0.1.0b1.dist-info/METADATA +217 -0
  108. robert_github_agent-0.1.0b1.dist-info/RECORD +111 -0
  109. robert_github_agent-0.1.0b1.dist-info/WHEEL +4 -0
  110. robert_github_agent-0.1.0b1.dist-info/entry_points.txt +2 -0
  111. robert_github_agent-0.1.0b1.dist-info/licenses/LICENSE +201 -0
@@ -0,0 +1,1016 @@
1
+ """Transactional commands for repository-scoped DD work items."""
2
+
3
+ from contextlib import closing
4
+ from dataclasses import dataclass
5
+ from datetime import datetime, timezone
6
+ import hashlib
7
+ import json
8
+ from pathlib import Path
9
+ import sqlite3
10
+ from uuid import uuid4
11
+
12
+ from robert_agent import wakeup
13
+
14
+
15
+ MAX_TITLE = 200
16
+ MAX_DESCRIPTION = 20_000
17
+ MAX_REPLY = 8_000
18
+ MAX_IDEMPOTENCY_KEY = 128
19
+ PRIORITIES = frozenset({"P0", "P1", "P2", "P3"})
20
+ COMMANDS = frozenset(
21
+ {
22
+ "edit",
23
+ "start",
24
+ "approve",
25
+ "reply",
26
+ "request_changes",
27
+ "retry",
28
+ "cancel",
29
+ "reopen",
30
+ }
31
+ )
32
+ QUESTION_EVENTS = frozenset({"operator_question", "completion_acceptance_requested"})
33
+ DECISION_EVENTS = frozenset({"operator_decision_required"})
34
+ FAILURE_EVENTS = frozenset(
35
+ {
36
+ "execution_failed",
37
+ "publication_failed",
38
+ "manual_worker_unavailable",
39
+ "review_attention",
40
+ "unmerged_pr_closed",
41
+ }
42
+ )
43
+
44
+
45
+ @dataclass(frozen=True)
46
+ class CommandContext:
47
+ actor_kind: str
48
+ actor_identity: str
49
+ allowed_repo_ids: frozenset[str]
50
+ allowed_workers: frozenset[str]
51
+
52
+
53
+ class WorkItemValidationError(ValueError):
54
+ pass
55
+
56
+
57
+ class WorkItemConflictError(RuntimeError):
58
+ pass
59
+
60
+
61
+ class WorkItemNotFoundError(LookupError):
62
+ pass
63
+
64
+
65
+ def utc_now():
66
+ return datetime.now(timezone.utc).isoformat()
67
+
68
+
69
+ def _decode_json(value, default):
70
+ if not value:
71
+ return default
72
+ try:
73
+ parsed = json.loads(value)
74
+ except (TypeError, ValueError):
75
+ return default
76
+ return parsed
77
+
78
+
79
+ def _validate_idempotency_key(value):
80
+ if not isinstance(value, str) or not value.strip():
81
+ raise WorkItemValidationError("idempotency_key is required")
82
+ if len(value) > MAX_IDEMPOTENCY_KEY:
83
+ raise WorkItemValidationError("idempotency_key is too long")
84
+ return value
85
+
86
+
87
+ def _validate_text(value, field, maximum, *, required=False):
88
+ if not isinstance(value, str):
89
+ raise WorkItemValidationError(f"{field} must be a string")
90
+ value = value.strip() if required else value
91
+ if required and not value:
92
+ raise WorkItemValidationError(f"{field} is required")
93
+ if len(value) > maximum:
94
+ raise WorkItemValidationError(f"{field} is too long")
95
+ return value
96
+
97
+
98
+ def _validate_priority(priority):
99
+ if priority not in PRIORITIES:
100
+ raise WorkItemValidationError("priority must be one of P0, P1, P2, P3")
101
+ return priority
102
+
103
+
104
+ def _validate_routing(context, routing_mode, requested_worker):
105
+ if routing_mode not in {"auto", "manual"}:
106
+ raise WorkItemValidationError("routing_mode must be auto or manual")
107
+ if routing_mode == "auto":
108
+ if requested_worker is not None:
109
+ raise WorkItemValidationError("automatic routing cannot select a worker")
110
+ return routing_mode, None
111
+ requested_worker = _validate_text(
112
+ requested_worker,
113
+ "requested_worker",
114
+ MAX_TITLE,
115
+ required=True,
116
+ )
117
+ if requested_worker not in context.allowed_workers:
118
+ raise WorkItemValidationError("requested worker is not available")
119
+ return routing_mode, requested_worker
120
+
121
+
122
+ def _item_from_row(row):
123
+ if not hasattr(row, "keys"):
124
+ columns = (
125
+ "work_item_id", "repo_id", "title", "description", "priority",
126
+ "origin_type", "origin_source_id", "routing_mode", "requested_worker",
127
+ "workstream_id", "creation_idempotency_key", "created_by", "activated_at",
128
+ "completed_at", "canceled_at", "version", "created_at", "updated_at",
129
+ "metadata_json",
130
+ )
131
+ row = dict(zip(columns, row))
132
+ return {
133
+ "work_item_id": row["work_item_id"],
134
+ "repo_id": row["repo_id"],
135
+ "title": row["title"],
136
+ "description": row["description"],
137
+ "priority": row["priority"],
138
+ "origin_type": row["origin_type"],
139
+ "origin_source_id": row["origin_source_id"],
140
+ "routing_mode": row["routing_mode"],
141
+ "requested_worker": row["requested_worker"],
142
+ "workstream_id": row["workstream_id"],
143
+ "created_by": row["created_by"],
144
+ "activated_at": row["activated_at"],
145
+ "completed_at": row["completed_at"],
146
+ "canceled_at": row["canceled_at"],
147
+ "version": row["version"],
148
+ "created_at": row["created_at"],
149
+ "updated_at": row["updated_at"],
150
+ }
151
+
152
+
153
+ def _load_item(conn, work_item_id):
154
+ row = conn.execute(
155
+ "SELECT * FROM work_items WHERE work_item_id = ?",
156
+ (work_item_id,),
157
+ ).fetchone()
158
+ if not row:
159
+ raise WorkItemNotFoundError("work item not found")
160
+ return row
161
+
162
+
163
+ def _event_from_row(row):
164
+ if not hasattr(row, "keys"):
165
+ columns = (
166
+ "event_id", "work_item_id", "event_type", "actor_kind",
167
+ "actor_identity", "body", "resolves_event_id", "idempotency_key",
168
+ "created_at", "metadata_json",
169
+ )
170
+ row = dict(zip(columns, row))
171
+ return {
172
+ "event_id": row["event_id"],
173
+ "work_item_id": row["work_item_id"],
174
+ "event_type": row["event_type"],
175
+ "actor_kind": row["actor_kind"],
176
+ "actor_identity": row["actor_identity"],
177
+ "body": row["body"],
178
+ "resolves_event_id": row["resolves_event_id"],
179
+ "idempotency_key": row["idempotency_key"],
180
+ "created_at": row["created_at"],
181
+ "metadata": _decode_json(row["metadata_json"], {}) or {},
182
+ }
183
+
184
+
185
+ def _insert_event(
186
+ conn,
187
+ work_item_id,
188
+ *,
189
+ event_type,
190
+ actor_kind,
191
+ actor_identity,
192
+ idempotency_key,
193
+ body="",
194
+ resolves_event_id=None,
195
+ metadata=None,
196
+ now=None,
197
+ ):
198
+ now = now or utc_now()
199
+ event_id = f"wie-{uuid4().hex}"
200
+ metadata_json = json.dumps(metadata or {}, ensure_ascii=False, sort_keys=True)
201
+ conn.execute(
202
+ """
203
+ INSERT INTO work_item_events(
204
+ event_id, work_item_id, event_type, actor_kind, actor_identity,
205
+ body, resolves_event_id, idempotency_key, created_at, metadata_json
206
+ ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
207
+ """,
208
+ (
209
+ event_id,
210
+ work_item_id,
211
+ event_type,
212
+ actor_kind,
213
+ actor_identity,
214
+ body,
215
+ resolves_event_id,
216
+ idempotency_key,
217
+ now,
218
+ metadata_json,
219
+ ),
220
+ )
221
+ return {
222
+ "event_id": event_id,
223
+ "work_item_id": work_item_id,
224
+ "event_type": event_type,
225
+ "actor_kind": actor_kind,
226
+ "actor_identity": actor_identity,
227
+ "body": body,
228
+ "resolves_event_id": resolves_event_id,
229
+ "idempotency_key": idempotency_key,
230
+ "created_at": now,
231
+ "metadata": metadata or {},
232
+ }
233
+
234
+
235
+ def record_system_event(
236
+ conn,
237
+ work_item_id,
238
+ *,
239
+ event_type,
240
+ idempotency_key,
241
+ body="",
242
+ resolves_event_id=None,
243
+ metadata=None,
244
+ now=None,
245
+ ):
246
+ _validate_idempotency_key(idempotency_key)
247
+ _load_item(conn, work_item_id)
248
+ existing = conn.execute(
249
+ """
250
+ SELECT * FROM work_item_events
251
+ WHERE work_item_id = ? AND idempotency_key = ?
252
+ """,
253
+ (work_item_id, idempotency_key),
254
+ ).fetchone()
255
+ if existing:
256
+ return _event_from_row(existing)
257
+ return _insert_event(
258
+ conn,
259
+ work_item_id,
260
+ event_type=event_type,
261
+ actor_kind="system",
262
+ actor_identity="robert",
263
+ idempotency_key=idempotency_key,
264
+ body=body,
265
+ resolves_event_id=resolves_event_id,
266
+ metadata=metadata,
267
+ now=now,
268
+ )
269
+
270
+
271
+ def resolve_work_item_for_workstream(conn, workstream_id):
272
+ current = workstream_id
273
+ visited = set()
274
+ while current and current not in visited:
275
+ visited.add(current)
276
+ row = conn.execute(
277
+ "SELECT * FROM work_items WHERE workstream_id = ?",
278
+ (current,),
279
+ ).fetchone()
280
+ if row:
281
+ return _item_from_row(row)
282
+ stream = conn.execute(
283
+ "SELECT origin_workstream_id FROM workstreams WHERE workstream_id = ?",
284
+ (current,),
285
+ ).fetchone()
286
+ current = stream[0] if stream else None
287
+ return None
288
+
289
+
290
+ def ensure_github_work_item(
291
+ conn,
292
+ *,
293
+ repo_id,
294
+ source_id,
295
+ workstream_id,
296
+ actor_identity,
297
+ route_confidence,
298
+ now,
299
+ ):
300
+ existing = resolve_work_item_for_workstream(conn, workstream_id)
301
+ if existing:
302
+ return existing
303
+
304
+ root_workstream_id = workstream_id
305
+ visited = set()
306
+ while root_workstream_id not in visited:
307
+ visited.add(root_workstream_id)
308
+ row = conn.execute(
309
+ """
310
+ SELECT origin_workstream_id
311
+ FROM workstreams
312
+ WHERE workstream_id = ?
313
+ """,
314
+ (root_workstream_id,),
315
+ ).fetchone()
316
+ if not row or not row[0]:
317
+ break
318
+ root_workstream_id = row[0]
319
+
320
+ root = conn.execute(
321
+ """
322
+ SELECT w.primary_source_id, w.created_at, gs.title, gs.author_login
323
+ FROM workstreams w
324
+ LEFT JOIN github_sources gs ON gs.source_id = w.primary_source_id
325
+ WHERE w.workstream_id = ?
326
+ """,
327
+ (root_workstream_id,),
328
+ ).fetchone()
329
+ root_source_id = (root[0] if root else None) or source_id
330
+ duplicate = conn.execute(
331
+ "SELECT * FROM work_items WHERE origin_source_id = ?",
332
+ (root_source_id,),
333
+ ).fetchone()
334
+ if duplicate:
335
+ return _item_from_row(duplicate)
336
+
337
+ digest = hashlib.sha256(root_workstream_id.encode("utf-8")).hexdigest()[:20]
338
+ work_item_id = f"wi-{digest}"
339
+ title = (root[2] if root else None) or f"Workstream {root_workstream_id}"
340
+ created_by = actor_identity or (root[3] if root else None) or "system"
341
+ created_at = (root[1] if root else None) or now
342
+ activated_at = now if route_confidence == "high" else None
343
+ conn.execute(
344
+ """
345
+ INSERT INTO work_items(
346
+ work_item_id, repo_id, title, description, priority,
347
+ origin_type, origin_source_id, routing_mode, requested_worker,
348
+ workstream_id, creation_idempotency_key, created_by, activated_at,
349
+ version, created_at, updated_at, metadata_json
350
+ )
351
+ VALUES (?, ?, ?, '', 'P1', 'github', ?, 'auto', NULL, ?, ?, ?, ?, 1, ?, ?, '{}')
352
+ ON CONFLICT DO NOTHING
353
+ """,
354
+ (
355
+ work_item_id,
356
+ repo_id,
357
+ title,
358
+ root_source_id,
359
+ root_workstream_id,
360
+ f"github:{root_source_id}",
361
+ created_by,
362
+ activated_at,
363
+ created_at,
364
+ now,
365
+ ),
366
+ )
367
+ item = conn.execute(
368
+ "SELECT * FROM work_items WHERE workstream_id = ? OR origin_source_id = ?",
369
+ (root_workstream_id, root_source_id),
370
+ ).fetchone()
371
+ if not item:
372
+ raise WorkItemConflictError("GitHub work item identity conflicts with existing data")
373
+ item_payload = _item_from_row(item)
374
+ event_type = "github_intake" if route_confidence == "high" else "operator_decision_required"
375
+ _insert_event(
376
+ conn,
377
+ item_payload["work_item_id"],
378
+ event_type=event_type,
379
+ actor_kind="github",
380
+ actor_identity=created_by,
381
+ idempotency_key=f"github-intake:{root_source_id}",
382
+ metadata={
383
+ "route_confidence": route_confidence,
384
+ "source_id": source_id,
385
+ "workstream_id": workstream_id,
386
+ },
387
+ now=now,
388
+ )
389
+ return item_payload
390
+
391
+
392
+ def _stored_command_result(conn, work_item_id, idempotency_key):
393
+ row = conn.execute(
394
+ """
395
+ SELECT metadata_json
396
+ FROM work_item_events
397
+ WHERE work_item_id = ? AND idempotency_key = ?
398
+ """,
399
+ (work_item_id, idempotency_key),
400
+ ).fetchone()
401
+ if not row:
402
+ return None
403
+ metadata = _decode_json(row[0], {}) or {}
404
+ return metadata.get("command_result")
405
+
406
+
407
+ def _unresolved_event(conn, work_item_id, event_types):
408
+ placeholders = ",".join("?" for _event_type in event_types)
409
+ return conn.execute(
410
+ f"""
411
+ SELECT e.*
412
+ FROM work_item_events e
413
+ WHERE e.work_item_id = ?
414
+ AND e.event_type IN ({placeholders})
415
+ AND NOT EXISTS (
416
+ SELECT 1 FROM work_item_events response
417
+ WHERE response.resolves_event_id = e.event_id
418
+ )
419
+ ORDER BY e.created_at DESC, e.event_id DESC
420
+ LIMIT 1
421
+ """,
422
+ [work_item_id] + sorted(event_types),
423
+ ).fetchone()
424
+
425
+
426
+ def record_github_response(
427
+ conn,
428
+ workstream_id,
429
+ *,
430
+ actor_identity,
431
+ body,
432
+ event_fingerprint,
433
+ metadata=None,
434
+ now=None,
435
+ ):
436
+ item = resolve_work_item_for_workstream(conn, workstream_id)
437
+ if not item:
438
+ return None
439
+ question = _unresolved_event(conn, item["work_item_id"], QUESTION_EVENTS)
440
+ if not question:
441
+ return None
442
+ idempotency_key = (
443
+ "github-response:"
444
+ + hashlib.sha256(event_fingerprint.encode("utf-8")).hexdigest()[:24]
445
+ )
446
+ existing = conn.execute(
447
+ "SELECT * FROM work_item_events WHERE work_item_id = ? AND idempotency_key = ?",
448
+ (item["work_item_id"], idempotency_key),
449
+ ).fetchone()
450
+ if existing:
451
+ return _event_from_row(existing)
452
+ now = now or utc_now()
453
+ response = _insert_event(
454
+ conn,
455
+ item["work_item_id"],
456
+ event_type="user_response",
457
+ actor_kind="github",
458
+ actor_identity=actor_identity,
459
+ idempotency_key=idempotency_key,
460
+ body=body,
461
+ resolves_event_id=(question["event_id"] if hasattr(question, "keys") else question[0]),
462
+ metadata={"event_fingerprint": event_fingerprint, **(metadata or {})},
463
+ now=now,
464
+ )
465
+ conn.execute(
466
+ "UPDATE work_items SET version = version + 1, updated_at = ? WHERE work_item_id = ?",
467
+ (now, item["work_item_id"]),
468
+ )
469
+ return response
470
+
471
+
472
+ def _has_open_pull_request(conn, workstream_id):
473
+ if not workstream_id:
474
+ return False
475
+ return bool(
476
+ conn.execute(
477
+ """
478
+ SELECT 1
479
+ FROM workstreams w
480
+ JOIN github_sources gs ON gs.source_id = w.primary_source_id
481
+ WHERE (w.workstream_id = ? OR w.origin_workstream_id = ?)
482
+ AND gs.source_type = 'pull_request'
483
+ AND LOWER(COALESCE(gs.state, 'open')) = 'open'
484
+ LIMIT 1
485
+ """,
486
+ (workstream_id, workstream_id),
487
+ ).fetchone()
488
+ )
489
+
490
+
491
+ def _active_or_latest_task(conn, workstream_id):
492
+ row = conn.execute(
493
+ """
494
+ SELECT t.*
495
+ FROM workstreams w
496
+ JOIN tasks t ON t.task_id = w.active_task_id
497
+ WHERE w.workstream_id = ?
498
+ """,
499
+ (workstream_id,),
500
+ ).fetchone()
501
+ if row:
502
+ return row
503
+ return conn.execute(
504
+ """
505
+ SELECT * FROM tasks
506
+ WHERE workstream_id = ?
507
+ ORDER BY created_at DESC, task_id DESC
508
+ LIMIT 1
509
+ """,
510
+ (workstream_id,),
511
+ ).fetchone()
512
+
513
+
514
+ def _create_task(
515
+ conn,
516
+ item,
517
+ *,
518
+ parent_task_id=None,
519
+ routing_mode=None,
520
+ requested_worker=None,
521
+ trigger_event_id=None,
522
+ now,
523
+ ):
524
+ task_id = f"task-{uuid4().hex}"
525
+ routing_mode = routing_mode or item["routing_mode"]
526
+ if routing_mode == "auto":
527
+ requested_worker = None
528
+ elif requested_worker is None:
529
+ requested_worker = item["requested_worker"]
530
+ metadata = {
531
+ "origin_type": item["origin_type"],
532
+ "work_item_id": item["work_item_id"],
533
+ }
534
+ if trigger_event_id:
535
+ metadata["trigger_work_item_event_id"] = trigger_event_id
536
+ conn.execute(
537
+ """
538
+ INSERT INTO tasks(
539
+ task_id, workstream_id, lifecycle, parent_task_id, priority,
540
+ routing_mode, requested_worker, created_at, updated_at, metadata_json
541
+ ) VALUES (?, ?, 'detected', ?, ?, ?, ?, ?, ?, ?)
542
+ """,
543
+ (
544
+ task_id,
545
+ item["workstream_id"],
546
+ parent_task_id,
547
+ item["priority"],
548
+ routing_mode,
549
+ requested_worker,
550
+ now,
551
+ now,
552
+ json.dumps(metadata, sort_keys=True),
553
+ ),
554
+ )
555
+ conn.execute(
556
+ """
557
+ UPDATE workstreams
558
+ SET lifecycle = 'active', active_task_id = ?, updated_at = ?
559
+ WHERE workstream_id = ?
560
+ """,
561
+ (task_id, now, item["workstream_id"]),
562
+ )
563
+ wakeup.request_wakeup(
564
+ conn,
565
+ repo_id=item["repo_id"],
566
+ reason="manual_operator_request",
567
+ dedupe_key=f"work-item-event:{trigger_event_id or task_id}",
568
+ work_item_id=item["work_item_id"],
569
+ task_id=task_id,
570
+ metadata={"work_item_id": item["work_item_id"]},
571
+ now=now,
572
+ )
573
+ return task_id
574
+
575
+
576
+ def _activate(conn, item, context, idempotency_key, now, *, initial_version=None):
577
+ if item["origin_type"] != "web" or item["activated_at"] is not None:
578
+ raise WorkItemConflictError("only a web Backlog item can be started")
579
+ workstream_id = f"local:{item['work_item_id']}"
580
+ version = initial_version if initial_version is not None else item["version"] + 1
581
+ conn.execute(
582
+ """
583
+ INSERT INTO workstreams(
584
+ workstream_id, repo_id, lifecycle, active_task_id,
585
+ created_at, updated_at, metadata_json
586
+ ) VALUES (?, ?, 'active', NULL, ?, ?, ?)
587
+ """,
588
+ (
589
+ workstream_id,
590
+ item["repo_id"],
591
+ now,
592
+ now,
593
+ json.dumps({"origin_type": "web", "work_item_id": item["work_item_id"]}),
594
+ ),
595
+ )
596
+ conn.execute(
597
+ """
598
+ UPDATE work_items
599
+ SET workstream_id = ?, activated_at = ?, updated_at = ?, version = ?
600
+ WHERE work_item_id = ?
601
+ """,
602
+ (workstream_id, now, now, version, item["work_item_id"]),
603
+ )
604
+ item = _load_item(conn, item["work_item_id"])
605
+ task_id = _create_task(conn, item, now=now)
606
+ result = {"ok": True, "command": "start", "item": _item_from_row(_load_item(conn, item["work_item_id"])), "task_id": task_id}
607
+ _insert_event(
608
+ conn,
609
+ item["work_item_id"],
610
+ event_type="activated",
611
+ actor_kind=context.actor_kind,
612
+ actor_identity=context.actor_identity,
613
+ idempotency_key=idempotency_key,
614
+ metadata={"command_result": result, "task_id": task_id},
615
+ now=now,
616
+ )
617
+ _insert_event(
618
+ conn,
619
+ item["work_item_id"],
620
+ event_type="routing_selected",
621
+ actor_kind=context.actor_kind,
622
+ actor_identity=context.actor_identity,
623
+ idempotency_key=f"{idempotency_key}:routing",
624
+ metadata={
625
+ "routing_mode": item["routing_mode"],
626
+ "requested_worker": item["requested_worker"],
627
+ "task_id": task_id,
628
+ },
629
+ now=now,
630
+ )
631
+ return result
632
+
633
+
634
+ def create_work_item(
635
+ db_path,
636
+ *,
637
+ context,
638
+ repo_id,
639
+ title,
640
+ description,
641
+ priority,
642
+ routing_mode,
643
+ requested_worker,
644
+ start,
645
+ idempotency_key,
646
+ ):
647
+ _validate_idempotency_key(idempotency_key)
648
+ if repo_id not in context.allowed_repo_ids:
649
+ raise WorkItemValidationError("repository is not enabled")
650
+ title = _validate_text(title, "title", MAX_TITLE, required=True)
651
+ description = _validate_text(description, "description", MAX_DESCRIPTION)
652
+ priority = _validate_priority(priority)
653
+ routing_mode, requested_worker = _validate_routing(
654
+ context,
655
+ routing_mode,
656
+ requested_worker,
657
+ )
658
+ if not isinstance(start, bool):
659
+ raise WorkItemValidationError("start must be a boolean")
660
+
661
+ db_path = Path(db_path).expanduser()
662
+ with closing(sqlite3.connect(db_path, isolation_level=None)) as conn:
663
+ conn.row_factory = sqlite3.Row
664
+ conn.execute("PRAGMA foreign_keys = ON")
665
+ conn.execute("PRAGMA busy_timeout = 5000")
666
+ conn.execute("BEGIN IMMEDIATE")
667
+ try:
668
+ existing = conn.execute(
669
+ "SELECT * FROM work_items WHERE creation_idempotency_key = ?",
670
+ (idempotency_key,),
671
+ ).fetchone()
672
+ if existing:
673
+ metadata = _decode_json(existing["metadata_json"], {}) or {}
674
+ result = metadata.get("command_result")
675
+ if result:
676
+ conn.commit()
677
+ return result
678
+ result = {"ok": True, "command": "create", "item": _item_from_row(existing)}
679
+ conn.commit()
680
+ return result
681
+
682
+ now = utc_now()
683
+ work_item_id = f"wi-{uuid4().hex}"
684
+ conn.execute(
685
+ """
686
+ INSERT INTO work_items(
687
+ work_item_id, repo_id, title, description, priority,
688
+ origin_type, routing_mode, requested_worker,
689
+ creation_idempotency_key, created_by, version,
690
+ created_at, updated_at, metadata_json
691
+ ) VALUES (?, ?, ?, ?, ?, 'web', ?, ?, ?, ?, 1, ?, ?, '{}')
692
+ """,
693
+ (
694
+ work_item_id,
695
+ repo_id,
696
+ title,
697
+ description,
698
+ priority,
699
+ routing_mode,
700
+ requested_worker,
701
+ idempotency_key,
702
+ context.actor_identity,
703
+ now,
704
+ now,
705
+ ),
706
+ )
707
+ _insert_event(
708
+ conn,
709
+ work_item_id,
710
+ event_type="created",
711
+ actor_kind=context.actor_kind,
712
+ actor_identity=context.actor_identity,
713
+ idempotency_key=f"create:{idempotency_key}",
714
+ now=now,
715
+ )
716
+ item = _load_item(conn, work_item_id)
717
+ if start:
718
+ result = _activate(
719
+ conn,
720
+ item,
721
+ context,
722
+ f"start:{idempotency_key}",
723
+ now,
724
+ initial_version=1,
725
+ )
726
+ result["command"] = "create_and_start"
727
+ else:
728
+ result = {"ok": True, "command": "create", "item": _item_from_row(item)}
729
+ conn.execute(
730
+ "UPDATE work_items SET metadata_json = ? WHERE work_item_id = ?",
731
+ (
732
+ json.dumps({"command_result": result}, ensure_ascii=False, sort_keys=True),
733
+ work_item_id,
734
+ ),
735
+ )
736
+ conn.commit()
737
+ return result
738
+ except Exception:
739
+ conn.rollback()
740
+ raise
741
+
742
+
743
+ def _finish_parent_for_child(conn, parent_task, now):
744
+ if not parent_task:
745
+ return None
746
+ if parent_task["lifecycle"] in {"waiting_for_user", "failed"}:
747
+ conn.execute(
748
+ "UPDATE tasks SET lifecycle = 'completed', updated_at = ? WHERE task_id = ?",
749
+ (now, parent_task["task_id"]),
750
+ )
751
+ return parent_task["task_id"]
752
+
753
+
754
+ def _command_event_type(command):
755
+ return {
756
+ "edit": "edited",
757
+ "approve": "approved",
758
+ "reply": "user_response",
759
+ "request_changes": "changes_requested",
760
+ "retry": "retry_requested",
761
+ "cancel": "canceled",
762
+ "reopen": "reopened",
763
+ }[command]
764
+
765
+
766
+ def execute_command(
767
+ db_path,
768
+ work_item_id,
769
+ *,
770
+ context,
771
+ command,
772
+ expected_version,
773
+ idempotency_key,
774
+ body="",
775
+ routing_mode=None,
776
+ requested_worker=None,
777
+ title=None,
778
+ description=None,
779
+ priority=None,
780
+ ):
781
+ _validate_idempotency_key(idempotency_key)
782
+ if command not in COMMANDS:
783
+ raise WorkItemValidationError("unknown work item command")
784
+ if not isinstance(expected_version, int) or isinstance(expected_version, bool):
785
+ raise WorkItemValidationError("expected_version must be an integer")
786
+ body = _validate_text(body, "body", MAX_REPLY)
787
+
788
+ db_path = Path(db_path).expanduser()
789
+ with closing(sqlite3.connect(db_path, isolation_level=None)) as conn:
790
+ conn.row_factory = sqlite3.Row
791
+ conn.execute("PRAGMA foreign_keys = ON")
792
+ conn.execute("PRAGMA busy_timeout = 5000")
793
+ conn.execute("BEGIN IMMEDIATE")
794
+ try:
795
+ item = _load_item(conn, work_item_id)
796
+ if item["repo_id"] not in context.allowed_repo_ids:
797
+ raise WorkItemNotFoundError("work item not found")
798
+ replay = _stored_command_result(conn, work_item_id, idempotency_key)
799
+ if replay:
800
+ conn.commit()
801
+ return replay
802
+ if item["version"] != expected_version:
803
+ raise WorkItemConflictError("work item version is stale")
804
+
805
+ now = utc_now()
806
+ if command == "start":
807
+ result = _activate(conn, item, context, idempotency_key, now)
808
+ conn.commit()
809
+ return result
810
+
811
+ if command == "edit":
812
+ if item["activated_at"] is not None or item["canceled_at"] is not None:
813
+ raise WorkItemConflictError("only a Backlog item can be edited")
814
+ updates = {}
815
+ if title is not None:
816
+ updates["title"] = _validate_text(title, "title", MAX_TITLE, required=True)
817
+ if description is not None:
818
+ updates["description"] = _validate_text(
819
+ description,
820
+ "description",
821
+ MAX_DESCRIPTION,
822
+ )
823
+ if priority is not None:
824
+ updates["priority"] = _validate_priority(priority)
825
+ if routing_mode is not None:
826
+ selected_mode, selected_worker = _validate_routing(
827
+ context,
828
+ routing_mode,
829
+ requested_worker,
830
+ )
831
+ updates["routing_mode"] = selected_mode
832
+ updates["requested_worker"] = selected_worker
833
+ elif requested_worker is not None:
834
+ raise WorkItemValidationError("routing_mode is required with requested_worker")
835
+ if not updates:
836
+ raise WorkItemValidationError("edit requires at least one field")
837
+ assignments = ", ".join(f"{field} = ?" for field in updates)
838
+ conn.execute(
839
+ f"""
840
+ UPDATE work_items
841
+ SET {assignments}, version = version + 1, updated_at = ?
842
+ WHERE work_item_id = ?
843
+ """,
844
+ list(updates.values()) + [now, work_item_id],
845
+ )
846
+ resolved_event_id = None
847
+ task_id = None
848
+ elif command == "cancel":
849
+ running = conn.execute(
850
+ """
851
+ SELECT 1
852
+ FROM attempts a
853
+ JOIN tasks t ON t.task_id = a.task_id
854
+ WHERE t.workstream_id = ? AND a.status = 'running'
855
+ LIMIT 1
856
+ """,
857
+ (item["workstream_id"],),
858
+ ).fetchone()
859
+ if running:
860
+ raise WorkItemConflictError("a running attempt cannot be canceled")
861
+ if item["canceled_at"] is not None or item["completed_at"] is not None:
862
+ raise WorkItemConflictError("work item cannot be canceled from its current state")
863
+ conn.execute(
864
+ """
865
+ UPDATE work_items
866
+ SET canceled_at = ?, updated_at = ?, version = version + 1
867
+ WHERE work_item_id = ?
868
+ """,
869
+ (now, now, work_item_id),
870
+ )
871
+ if item["workstream_id"]:
872
+ conn.execute(
873
+ """
874
+ UPDATE tasks SET lifecycle = 'canceled', updated_at = ?
875
+ WHERE workstream_id = ?
876
+ AND lifecycle IN ('detected', 'authorized', 'classified', 'queued', 'waiting_for_user', 'failed')
877
+ """,
878
+ (now, item["workstream_id"]),
879
+ )
880
+ conn.execute(
881
+ "UPDATE attempts SET status = 'canceled', finished_at = ? WHERE task_id IN (SELECT task_id FROM tasks WHERE workstream_id = ?) AND status = 'prepared'",
882
+ (now, item["workstream_id"]),
883
+ )
884
+ conn.execute(
885
+ "UPDATE workstreams SET lifecycle = 'canceled', active_task_id = NULL, updated_at = ? WHERE workstream_id = ?",
886
+ (now, item["workstream_id"]),
887
+ )
888
+ resolved_event_id = None
889
+ task_id = None
890
+ elif command == "reopen":
891
+ if item["completed_at"] is None or item["canceled_at"] is not None:
892
+ raise WorkItemConflictError("only a completed work item can be reopened")
893
+ conn.execute(
894
+ "UPDATE work_items SET completed_at = NULL, updated_at = ?, version = version + 1 WHERE work_item_id = ?",
895
+ (now, work_item_id),
896
+ )
897
+ parent = _active_or_latest_task(conn, item["workstream_id"])
898
+ parent_task_id = _finish_parent_for_child(conn, parent, now)
899
+ item = _load_item(conn, work_item_id)
900
+ task_id = _create_task(
901
+ conn,
902
+ item,
903
+ parent_task_id=parent_task_id,
904
+ trigger_event_id=idempotency_key,
905
+ now=now,
906
+ )
907
+ resolved_event_id = None
908
+ else:
909
+ allowed_events = QUESTION_EVENTS | FAILURE_EVENTS
910
+ if command == "approve":
911
+ allowed_events |= DECISION_EVENTS
912
+ unresolved = _unresolved_event(conn, work_item_id, allowed_events)
913
+ review_changes = (
914
+ command == "request_changes"
915
+ and not unresolved
916
+ and _has_open_pull_request(conn, item["workstream_id"])
917
+ )
918
+ if not unresolved and not review_changes:
919
+ raise WorkItemConflictError("work item is not waiting for operator input")
920
+ if command == "reply" and unresolved["event_type"] not in QUESTION_EVENTS:
921
+ raise WorkItemConflictError("the current attention item does not accept a reply")
922
+ if command == "retry" and unresolved["event_type"] not in FAILURE_EVENTS:
923
+ raise WorkItemConflictError("the current attention item is not retryable")
924
+ if command in {"reply", "request_changes"} and not body.strip():
925
+ raise WorkItemValidationError("body is required")
926
+ unresolved_metadata = (
927
+ _decode_json(unresolved["metadata_json"], {}) or {}
928
+ if unresolved
929
+ else {}
930
+ )
931
+ if command == "approve" and unresolved["event_type"] in DECISION_EVENTS:
932
+ conn.execute(
933
+ """
934
+ UPDATE work_items
935
+ SET activated_at = COALESCE(activated_at, ?),
936
+ updated_at = ?,
937
+ version = version + 1
938
+ WHERE work_item_id = ?
939
+ """,
940
+ (now, now, work_item_id),
941
+ )
942
+ task_id = None
943
+ elif command == "approve" and unresolved_metadata.get("kind") == "completion_acceptance":
944
+ parent = _active_or_latest_task(conn, item["workstream_id"])
945
+ if parent and parent["lifecycle"] in {"waiting_for_user", "failed"}:
946
+ conn.execute(
947
+ "UPDATE tasks SET lifecycle = 'completed', updated_at = ? WHERE task_id = ?",
948
+ (now, parent["task_id"]),
949
+ )
950
+ conn.execute(
951
+ "UPDATE workstreams SET lifecycle = 'completed', active_task_id = NULL, updated_at = ? WHERE workstream_id = ?",
952
+ (now, item["workstream_id"]),
953
+ )
954
+ conn.execute(
955
+ "UPDATE work_items SET completed_at = ?, updated_at = ?, version = version + 1 WHERE work_item_id = ?",
956
+ (now, now, work_item_id),
957
+ )
958
+ task_id = None
959
+ else:
960
+ selected_mode = item["routing_mode"]
961
+ selected_worker = item["requested_worker"]
962
+ if routing_mode is not None:
963
+ selected_mode, selected_worker = _validate_routing(
964
+ context,
965
+ routing_mode,
966
+ requested_worker,
967
+ )
968
+ conn.execute(
969
+ "UPDATE work_items SET routing_mode = ?, requested_worker = ? WHERE work_item_id = ?",
970
+ (selected_mode, selected_worker, work_item_id),
971
+ )
972
+ elif requested_worker is not None:
973
+ raise WorkItemValidationError("routing_mode is required with requested_worker")
974
+ parent = _active_or_latest_task(conn, item["workstream_id"])
975
+ parent_task_id = _finish_parent_for_child(conn, parent, now)
976
+ conn.execute(
977
+ "UPDATE work_items SET updated_at = ?, version = version + 1 WHERE work_item_id = ?",
978
+ (now, work_item_id),
979
+ )
980
+ item = _load_item(conn, work_item_id)
981
+ task_id = _create_task(
982
+ conn,
983
+ item,
984
+ parent_task_id=parent_task_id,
985
+ routing_mode=selected_mode,
986
+ requested_worker=selected_worker,
987
+ trigger_event_id=idempotency_key,
988
+ now=now,
989
+ )
990
+ resolved_event_id = unresolved["event_id"] if unresolved else None
991
+
992
+ current_item = _item_from_row(_load_item(conn, work_item_id))
993
+ result = {
994
+ "ok": True,
995
+ "command": command,
996
+ "item": current_item,
997
+ "task_id": task_id,
998
+ "resolved_event_id": resolved_event_id,
999
+ }
1000
+ _insert_event(
1001
+ conn,
1002
+ work_item_id,
1003
+ event_type=_command_event_type(command),
1004
+ actor_kind=context.actor_kind,
1005
+ actor_identity=context.actor_identity,
1006
+ idempotency_key=idempotency_key,
1007
+ body=body,
1008
+ resolves_event_id=resolved_event_id,
1009
+ metadata={"command_result": result, "task_id": task_id},
1010
+ now=now,
1011
+ )
1012
+ conn.commit()
1013
+ return result
1014
+ except Exception:
1015
+ conn.rollback()
1016
+ raise