lorebase-keeper 0.2.3__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 (126) hide show
  1. lorebase_keeper/__init__.py +1 -0
  2. lorebase_keeper/__main__.py +456 -0
  3. lorebase_keeper/agents/__init__.py +1 -0
  4. lorebase_keeper/agents/budget.py +247 -0
  5. lorebase_keeper/agents/context.py +529 -0
  6. lorebase_keeper/agents/explain.py +582 -0
  7. lorebase_keeper/agents/feed.py +259 -0
  8. lorebase_keeper/agents/markdown.py +219 -0
  9. lorebase_keeper/agents/pack.py +403 -0
  10. lorebase_keeper/agents/settings.py +111 -0
  11. lorebase_keeper/app.py +373 -0
  12. lorebase_keeper/auth/__init__.py +4 -0
  13. lorebase_keeper/auth/api_keys.py +127 -0
  14. lorebase_keeper/auth/audit.py +356 -0
  15. lorebase_keeper/auth/cache.py +53 -0
  16. lorebase_keeper/auth/config.py +618 -0
  17. lorebase_keeper/auth/deps.py +183 -0
  18. lorebase_keeper/auth/keyring.py +14 -0
  19. lorebase_keeper/auth/oidc.py +242 -0
  20. lorebase_keeper/auth/permissions.py +142 -0
  21. lorebase_keeper/auth/ports.py +212 -0
  22. lorebase_keeper/auth/principals.py +377 -0
  23. lorebase_keeper/auth/provider.py +250 -0
  24. lorebase_keeper/auth/rbac.py +247 -0
  25. lorebase_keeper/auth/read_audit.py +357 -0
  26. lorebase_keeper/auth/runtime.py +113 -0
  27. lorebase_keeper/auth/sessions.py +452 -0
  28. lorebase_keeper/bootstrap.py +151 -0
  29. lorebase_keeper/client_address.py +129 -0
  30. lorebase_keeper/context.py +226 -0
  31. lorebase_keeper/db.py +93 -0
  32. lorebase_keeper/deps.py +47 -0
  33. lorebase_keeper/errors.py +257 -0
  34. lorebase_keeper/health.py +61 -0
  35. lorebase_keeper/kindhealth/__init__.py +6 -0
  36. lorebase_keeper/kindhealth/config.py +51 -0
  37. lorebase_keeper/kindhealth/markdown.py +163 -0
  38. lorebase_keeper/kindhealth/models.py +179 -0
  39. lorebase_keeper/kindhealth/report.py +154 -0
  40. lorebase_keeper/kindhealth/scan.py +512 -0
  41. lorebase_keeper/middleware.py +285 -0
  42. lorebase_keeper/pagination.py +87 -0
  43. lorebase_keeper/ratelimit/__init__.py +10 -0
  44. lorebase_keeper/ratelimit/bucket.py +118 -0
  45. lorebase_keeper/ratelimit/config.py +283 -0
  46. lorebase_keeper/ratelimit/enforce.py +393 -0
  47. lorebase_keeper/ratelimit/limiter.py +149 -0
  48. lorebase_keeper/ratelimit/quotas.py +204 -0
  49. lorebase_keeper/ratelimit/shared.py +242 -0
  50. lorebase_keeper/readiness.py +257 -0
  51. lorebase_keeper/reading/__init__.py +1 -0
  52. lorebase_keeper/reading/caching.py +251 -0
  53. lorebase_keeper/reading/compiler.py +678 -0
  54. lorebase_keeper/reading/cursors.py +56 -0
  55. lorebase_keeper/reading/diff.py +408 -0
  56. lorebase_keeper/reading/graph.py +268 -0
  57. lorebase_keeper/reading/history.py +152 -0
  58. lorebase_keeper/reading/points.py +410 -0
  59. lorebase_keeper/reading/problems.py +74 -0
  60. lorebase_keeper/reading/record_history.py +722 -0
  61. lorebase_keeper/reading/records.py +780 -0
  62. lorebase_keeper/reading/requests.py +107 -0
  63. lorebase_keeper/reading/runtime.py +145 -0
  64. lorebase_keeper/reading/search.py +708 -0
  65. lorebase_keeper/reading/sensitivity.py +882 -0
  66. lorebase_keeper/reading/settings.py +339 -0
  67. lorebase_keeper/reading/snapshots.py +148 -0
  68. lorebase_keeper/reading/tree.py +98 -0
  69. lorebase_keeper/reading/views.py +264 -0
  70. lorebase_keeper/reading/visibility.py +93 -0
  71. lorebase_keeper/routes/__init__.py +1 -0
  72. lorebase_keeper/routes/admin.py +597 -0
  73. lorebase_keeper/routes/agents.py +160 -0
  74. lorebase_keeper/routes/branches.py +438 -0
  75. lorebase_keeper/routes/derivations.py +215 -0
  76. lorebase_keeper/routes/documents.py +497 -0
  77. lorebase_keeper/routes/domain_api.py +59 -0
  78. lorebase_keeper/routes/domains.py +220 -0
  79. lorebase_keeper/routes/events.py +187 -0
  80. lorebase_keeper/routes/kind_health.py +166 -0
  81. lorebase_keeper/routes/operations.py +392 -0
  82. lorebase_keeper/routes/proposal_items.py +563 -0
  83. lorebase_keeper/routes/proposals.py +1107 -0
  84. lorebase_keeper/routes/read.py +493 -0
  85. lorebase_keeper/routes/revisions.py +523 -0
  86. lorebase_keeper/routes/schema.py +682 -0
  87. lorebase_keeper/routes/schema_inference.py +437 -0
  88. lorebase_keeper/routes/schema_suggestions.py +328 -0
  89. lorebase_keeper/routes/sessions.py +286 -0
  90. lorebase_keeper/routes/source_preview.py +232 -0
  91. lorebase_keeper/routes/sources.py +200 -0
  92. lorebase_keeper/routes/trace.py +506 -0
  93. lorebase_keeper/routes/vault.py +332 -0
  94. lorebase_keeper/routes/webhooks.py +298 -0
  95. lorebase_keeper/routes/whoami.py +88 -0
  96. lorebase_keeper/services/__init__.py +1 -0
  97. lorebase_keeper/services/agent_writes.py +1035 -0
  98. lorebase_keeper/services/branches.py +337 -0
  99. lorebase_keeper/services/config.py +431 -0
  100. lorebase_keeper/services/derivation_preview.py +279 -0
  101. lorebase_keeper/services/document_urls.py +114 -0
  102. lorebase_keeper/services/domains.py +118 -0
  103. lorebase_keeper/services/errors.py +196 -0
  104. lorebase_keeper/services/operation_catalog.py +806 -0
  105. lorebase_keeper/services/operation_events.py +199 -0
  106. lorebase_keeper/services/operations.py +1229 -0
  107. lorebase_keeper/services/pii_import.py +222 -0
  108. lorebase_keeper/services/proposal_reads.py +158 -0
  109. lorebase_keeper/services/proposals.py +850 -0
  110. lorebase_keeper/services/reads.py +286 -0
  111. lorebase_keeper/services/schema.py +601 -0
  112. lorebase_keeper/services/schema_inference.py +390 -0
  113. lorebase_keeper/services/schema_suggestions.py +418 -0
  114. lorebase_keeper/services/source_preview.py +127 -0
  115. lorebase_keeper/settings.py +313 -0
  116. lorebase_keeper/tracing/__init__.py +1 -0
  117. lorebase_keeper/tracing/capture.py +350 -0
  118. lorebase_keeper/tracing/config.py +157 -0
  119. lorebase_keeper/tracing/explain.py +97 -0
  120. lorebase_keeper/tracing/middleware.py +359 -0
  121. lorebase_keeper/tracing/notes.py +80 -0
  122. lorebase_keeper/tracing/recorder.py +180 -0
  123. lorebase_keeper-0.2.3.dist-info/METADATA +21 -0
  124. lorebase_keeper-0.2.3.dist-info/RECORD +126 -0
  125. lorebase_keeper-0.2.3.dist-info/WHEEL +4 -0
  126. lorebase_keeper-0.2.3.dist-info/entry_points.txt +2 -0
@@ -0,0 +1,1035 @@
1
+ """Agent writes: Operations that need review become a task branch and a Proposal.
2
+
3
+ An Operation executed on a protected branch, or whose review policy asks for review, is
4
+ refused with `review-required` (see `services.operations`). A caller that names a `task`
5
+ gets this instead:
6
+
7
+ review-required (protected branch or review policy)
8
+ -> branch `{branch_prefix}/{principal}/{task}` (created from the target head as
9
+ `branch_mode`, an overlay by default; reused when it exists and belongs to the caller)
10
+ -> dry run (validation: violations are refused as usual, nothing is created)
11
+ -> the Operation on the task branch (`reviewed_by_proposal`: the Proposal is the review)
12
+ -> a Proposal task branch -> target, created or updated (one open Proposal per branch and
13
+ target), titled from `title_template`, described by the `intent` and the executions
14
+ -> merge, when the request asks for it and the Domain allows it for the caller's role
15
+ (`allowed_roles_for_auto_merge`), the Proposal has no open Conflict and the approvals
16
+ the target requires are in place (an Operation whose own review policy demands review
17
+ also needs an actual approval).
18
+
19
+ The result is the Proposal and where it stands: `proposed`, `merged` or `conflicts`, with
20
+ `next` hints (problem-details style: action, detail, method, href) saying what comes next.
21
+ Every step has its own transaction and is repeatable: a retry with the same idempotency key
22
+ finds the commit it made, the branch and the Proposal. Without a key a retry runs the
23
+ Operation again on the task branch.
24
+
25
+ Settings are `keeper.agent_writes`; a Domain overrides any member with the same name in its
26
+ `agent_writes` setting. When a Proposal merges or closes, `release_branch` deletes the task
27
+ branch unless another open Proposal still uses it.
28
+ """
29
+
30
+ from __future__ import annotations
31
+
32
+ import json
33
+ import logging
34
+ import re
35
+ from collections.abc import Awaitable, Callable, Collection, Mapping
36
+ from dataclasses import dataclass, field
37
+ from typing import Any, Literal
38
+
39
+ from pydantic import ValidationError
40
+
41
+ from lorebase_core.canonical import hex
42
+ from lorebase_keeper.auth.permissions import Permission
43
+ from lorebase_keeper.auth.principals import Principal
44
+ from lorebase_keeper.auth.rbac import AccessContext
45
+ from lorebase_keeper.context import StoreAccess, require_branch, require_domain
46
+ from lorebase_keeper.errors import VALIDATION_FAILED, ProblemError, ProblemType
47
+ from lorebase_keeper.services import branches, proposals
48
+ from lorebase_keeper.services import operations as operations_service
49
+ from lorebase_keeper.services.config import AgentWriteSettings
50
+ from lorebase_keeper.services.errors import (
51
+ ALREADY_EXISTS,
52
+ IDEMPOTENCY_CONFLICT,
53
+ REVIEW_REQUIRED,
54
+ )
55
+ from lorebase_keeper.services.operations import (
56
+ REVIEW_POLICY,
57
+ ExecutionOutcome,
58
+ ExecutionRequest,
59
+ ExecutionStatus,
60
+ )
61
+ from lorebase_keeper.settings import KeeperSettings
62
+ from lorebase_store.commit import StaleHeadError
63
+ from lorebase_store.digests import DigestKeys
64
+ from lorebase_store.materialize import BranchMode
65
+ from lorebase_store.models.enums import ProposalOrigin, ProposalStatus, RefKind
66
+ from lorebase_store.repositories import (
67
+ InvocationRepository,
68
+ InvocationRow,
69
+ ProposalFilter,
70
+ ProposalRepository,
71
+ ProposalRow,
72
+ RefRepository,
73
+ RefRow,
74
+ )
75
+
76
+ logger = logging.getLogger("lorebase.keeper.agent_writes")
77
+
78
+ OVERRIDE_KEY = "agent_writes"
79
+ """Key of the Domain setting that overrides `keeper.agent_writes`."""
80
+ DIVERTED = frozenset({REVIEW_REQUIRED, IDEMPOTENCY_CONFLICT})
81
+ """Refusals of an execution on the target branch that the agent flow takes over: review is
82
+ needed, or the idempotency key was used by the earlier execution on the task branch."""
83
+ INTENT_MAX_CHARS = 4000
84
+ OPERATIONS_HEADING = "Operations:"
85
+ BRANCH_LIMIT = ProblemType("agent-branch-limit", 409, "Too many task branches")
86
+
87
+ Status = Literal["proposed", "merged", "conflicts"]
88
+ Hint = dict[str, str]
89
+ Check = Callable[[Permission, AccessContext], Awaitable[None]]
90
+ Roles = Callable[[AccessContext], Awaitable[frozenset[str]]]
91
+ Emit = Callable[..., Awaitable[None]]
92
+ """`emit(action, target, **details)` writes an audit entry for a step of the flow."""
93
+
94
+ _UNSAFE = re.compile(r"[^a-z0-9._-]+|-{2,}")
95
+
96
+
97
+ # Pure helpers ----------------------------------------------------------------------------
98
+
99
+
100
+ @dataclass(frozen=True)
101
+ class AgentRequest:
102
+ """What the caller said about the review flow."""
103
+
104
+ task: str | None = None
105
+ intent: str | None = None
106
+ auto_propose: bool | None = None
107
+ auto_merge: bool | None = None
108
+
109
+
110
+ @dataclass(frozen=True)
111
+ class Decision:
112
+ """What to do with an execution that needs review."""
113
+
114
+ propose: bool
115
+ merge: bool
116
+ merge_requested: bool
117
+ merge_allowed: bool
118
+ refusal: str | None = None
119
+ """Why no Proposal is opened: `disabled`, `declined` or `task-required`."""
120
+
121
+
122
+ def slug(text: str) -> str:
123
+ """Lower case, runs of characters outside `a-z0-9._-` (and of dashes) become one `-`, no
124
+ leading or trailing separators: usable as one segment of a branch name."""
125
+ return _UNSAFE.sub("-", text.strip().lower()).strip("-._")
126
+
127
+
128
+ def task_slug(task: str, settings: AgentWriteSettings) -> str:
129
+ """The normalized task; 422 when nothing is left or it is too long."""
130
+ value = slug(task)
131
+ if not value or len(value) > settings.max_task_length:
132
+ raise ProblemError(
133
+ VALIDATION_FAILED,
134
+ "One or more request members are invalid.",
135
+ extensions={
136
+ "errors": [
137
+ {
138
+ "pointer": "/body/task",
139
+ "message": "must hold letters or digits and normalize to at most "
140
+ f"{settings.max_task_length} characters",
141
+ "code": "invalid",
142
+ }
143
+ ]
144
+ },
145
+ )
146
+ return value
147
+
148
+
149
+ def owner_prefix(settings: AgentWriteSettings, principal_id: str) -> str:
150
+ """Start of the names of a principal's task branches."""
151
+ owner = slug(principal_id)
152
+ if not owner:
153
+ raise ProblemError(VALIDATION_FAILED, "The principal id cannot form a branch name.")
154
+ return f"{settings.branch_prefix}/{owner}/"
155
+
156
+
157
+ def branch_name(settings: AgentWriteSettings, principal_id: str, task: str) -> str:
158
+ """`{branch_prefix}/{principal}/{task}`."""
159
+ return owner_prefix(settings, principal_id) + task_slug(task, settings)
160
+
161
+
162
+ def is_task_branch(settings: AgentWriteSettings, name: str) -> bool:
163
+ """Whether `name` has the shape of a task branch: `{branch_prefix}/{principal}/{task}`."""
164
+ head = settings.branch_prefix + "/"
165
+ return name.startswith(head) and name.removeprefix(head).count("/") == 1
166
+
167
+
168
+ def effective_settings(
169
+ base: AgentWriteSettings, domain_settings: Mapping[str, Any] | None
170
+ ) -> AgentWriteSettings:
171
+ """`base` with the members the Domain's `agent_writes` setting overrides; 422 when that
172
+ setting is not valid."""
173
+ raw = (domain_settings or {}).get(OVERRIDE_KEY)
174
+ if raw is None:
175
+ return base
176
+ try:
177
+ if not isinstance(raw, Mapping):
178
+ raise ValueError("must be an object")
179
+ return AgentWriteSettings.model_validate({**base.model_dump(mode="python"), **raw})
180
+ except (ValidationError, ValueError) as error:
181
+ detail = error.errors()[0]["msg"] if isinstance(error, ValidationError) else str(error)
182
+ raise ProblemError(
183
+ VALIDATION_FAILED, f"The Domain setting {OVERRIDE_KEY} is not valid: {detail}"
184
+ ) from None
185
+
186
+
187
+ def decide(
188
+ settings: AgentWriteSettings,
189
+ request: AgentRequest,
190
+ *,
191
+ agent: bool,
192
+ roles: Collection[str],
193
+ ) -> Decision:
194
+ """Whether to open a Proposal, and whether to merge it at once.
195
+
196
+ A Proposal needs the flow enabled, a task, and either `auto_propose` in the request or
197
+ (when it leaves it out) an agent principal and `auto_propose` in the settings. Merging
198
+ needs `auto_merge` (request, else settings) and one of `roles` in
199
+ `allowed_roles_for_auto_merge`.
200
+ """
201
+ wanted = (
202
+ request.auto_propose
203
+ if request.auto_propose is not None
204
+ else (settings.auto_propose and agent)
205
+ )
206
+ merge_requested = request.auto_merge if request.auto_merge is not None else settings.auto_merge
207
+ merge_allowed = not set(roles).isdisjoint(settings.allowed_roles_for_auto_merge)
208
+ refusal: str | None = None
209
+ if not settings.enabled:
210
+ refusal = "disabled"
211
+ elif not wanted:
212
+ refusal = "declined"
213
+ elif request.task is None:
214
+ refusal = "task-required"
215
+ propose = refusal is None
216
+ return Decision(
217
+ propose=propose,
218
+ merge=propose and merge_requested and merge_allowed,
219
+ merge_requested=merge_requested,
220
+ merge_allowed=merge_allowed,
221
+ refusal=refusal,
222
+ )
223
+
224
+
225
+ def merge_blockers(approval: proposals.Approval, *, policy_review: bool) -> list[str]:
226
+ """Why a Proposal must not be merged automatically although the role may: approvals the
227
+ target requires are missing, or the Operation's own review policy asks for a review and
228
+ nobody approved."""
229
+ blockers: list[str] = []
230
+ if not approval.satisfied:
231
+ blockers.append("approvals-pending")
232
+ if policy_review and not approval.approvers:
233
+ blockers.append("review-policy-needs-approval")
234
+ return blockers
235
+
236
+
237
+ def operation_line(
238
+ operation: str,
239
+ parameters: Mapping[str, Any],
240
+ invocation_id: str,
241
+ settings: AgentWriteSettings,
242
+ ) -> str:
243
+ """One execution as listed in a Proposal description."""
244
+ shown: list[str] = []
245
+ for name in sorted(parameters):
246
+ if not settings.summary_parameter_values:
247
+ shown.append(name)
248
+ continue
249
+ value = json.dumps(parameters[name], ensure_ascii=False, default=str)
250
+ if len(value) > settings.summary_value_chars:
251
+ value = value[: settings.summary_value_chars - 1] + "…"
252
+ shown.append(f"{name}={value}")
253
+ return f"- {operation}({', '.join(shown)}) [{invocation_id}]"
254
+
255
+
256
+ def describe(
257
+ intent: str | None, line: str, previous: str | None, settings: AgentWriteSettings
258
+ ) -> str:
259
+ """Description of a Proposal: the intent, then the executions (the earlier ones of
260
+ `previous` first, at most `max_summary_operations` of the latest)."""
261
+ heading = "\n\n" + OPERATIONS_HEADING + "\n"
262
+ earlier_intent, _, tail = (previous or "").partition(heading)
263
+ lines = [entry for entry in tail.splitlines() if entry.startswith("- ")]
264
+ if line.rsplit("[", 1)[-1] not in {entry.rsplit("[", 1)[-1] for entry in lines}:
265
+ lines.append(line)
266
+ kept = lines[-settings.max_summary_operations :]
267
+ text = (intent if intent is not None else earlier_intent).strip()
268
+ listing = OPERATIONS_HEADING + "\n" + "\n".join(kept)
269
+ return f"{text}\n\n{listing}" if text else listing
270
+
271
+
272
+ def hint(
273
+ action: str,
274
+ detail: str,
275
+ *,
276
+ method: str | None = None,
277
+ href: str | None = None,
278
+ permission: str | None = None,
279
+ ) -> Hint:
280
+ """A next step for the agent."""
281
+ found = {"action": action, "detail": detail}
282
+ for name, value in (("method", method), ("href", href), ("permission", permission)):
283
+ if value is not None:
284
+ found[name] = value
285
+ return found
286
+
287
+
288
+ # Results ---------------------------------------------------------------------------------
289
+
290
+
291
+ @dataclass(frozen=True)
292
+ class ProposalSummary:
293
+ id: str
294
+ title: str
295
+ status: str
296
+ source_ref: str
297
+ target_ref: str
298
+ url: str
299
+ created: bool
300
+
301
+
302
+ @dataclass(frozen=True)
303
+ class ApprovalSummary:
304
+ required: int
305
+ approvals: int
306
+ satisfied: bool
307
+
308
+
309
+ @dataclass(frozen=True)
310
+ class AttemptSummary:
311
+ id: str
312
+ result: str | None
313
+ open_conflicts: int
314
+ resolved_conflicts: int
315
+ counts: dict[str, dict[str, int]]
316
+
317
+
318
+ @dataclass(frozen=True)
319
+ class MergeSummary:
320
+ requested: bool
321
+ allowed: bool
322
+ performed: bool
323
+ blockers: list[str] = field(default_factory=list)
324
+
325
+
326
+ @dataclass(frozen=True)
327
+ class AgentWriteOutcome:
328
+ """Where an agent write stands."""
329
+
330
+ status: Status
331
+ operation: str
332
+ branch: str
333
+ target: str
334
+ invocation_id: str
335
+ parameters_hash: str
336
+ revision: str | None
337
+ revisions: list[str]
338
+ edit_count: int
339
+ replayed: bool
340
+ proposal: ProposalSummary
341
+ approval: ApprovalSummary
342
+ attempt: AttemptSummary | None
343
+ merge: MergeSummary
344
+ merged_revision: str | None
345
+ branch_created: bool
346
+ branch_deleted: bool
347
+ warnings: list[dict[str, Any]]
348
+ next: list[Hint]
349
+
350
+
351
+ # Flow ------------------------------------------------------------------------------------
352
+
353
+
354
+ @dataclass(frozen=True)
355
+ class _Prepared:
356
+ settings: AgentWriteSettings
357
+ default_branch: str
358
+ target: RefRow
359
+ branches: dict[str, RefRow]
360
+ invocation: InvocationRow | None
361
+
362
+
363
+ def diverts(problem: ProblemError) -> bool:
364
+ """Whether the agent flow may take over from this refusal."""
365
+ return problem.problem in DIVERTED
366
+
367
+
368
+ def _paths(keeper: KeeperSettings, domain_id: str) -> str:
369
+ return f"{keeper.api_prefix}/domains/{domain_id}"
370
+
371
+
372
+ def manual_hints(base: str, operation: str) -> list[Hint]:
373
+ """Doing by hand what the flow does: a work branch, the Operation on it, a Proposal."""
374
+ return [
375
+ hint(
376
+ "create_branch",
377
+ "Create a work branch from the target and run the Operation there.",
378
+ method="POST",
379
+ href=f"{base}/branches",
380
+ permission=Permission.BRANCH_CREATE.value,
381
+ ),
382
+ hint(
383
+ "execute_on_branch",
384
+ "Execute the Operation with `branch` set to the work branch.",
385
+ method="POST",
386
+ href=f"{base}/operations/{operation}/execute",
387
+ ),
388
+ hint(
389
+ "open_proposal",
390
+ "Open a Proposal from the work branch into the target.",
391
+ method="POST",
392
+ href=f"{base}/proposals",
393
+ permission=Permission.PROPOSAL_CREATE.value,
394
+ ),
395
+ ]
396
+
397
+
398
+ def hinted(original: ProblemError, base: str, refusal: str | None) -> ProblemError:
399
+ """`original` with `next` hints when it is `review-required`; other problems unchanged."""
400
+ if original.problem is not REVIEW_REQUIRED:
401
+ return original
402
+ operation = str(original.extensions.get("operation", "{operation}"))
403
+ steps: list[Hint] = []
404
+ if refusal == "disabled":
405
+ steps.append(hint("agent_writes_disabled", "Task branches are turned off for this Domain."))
406
+ elif refusal == "declined":
407
+ steps.append(
408
+ hint("auto_propose", "Send `auto_propose: true` and a `task` to open a Proposal.")
409
+ )
410
+ else:
411
+ steps.append(
412
+ hint(
413
+ "name_a_task",
414
+ "Repeat the request with `task` (a short slug) and `intent`: Keeper runs the "
415
+ "Operation on a task branch and opens a Proposal.",
416
+ method="POST",
417
+ href=f"{base}/operations/{operation}/execute",
418
+ )
419
+ )
420
+ steps.extend(manual_hints(base, operation))
421
+ original.extensions["next"] = steps
422
+ return original
423
+
424
+
425
+ def next_steps(
426
+ status: Status,
427
+ base: str,
428
+ proposal: ProposalSummary,
429
+ *,
430
+ approval: ApprovalSummary,
431
+ merge: MergeSummary,
432
+ merged_revision: str | None,
433
+ ) -> list[Hint]:
434
+ """What the agent (or a human on its behalf) does next."""
435
+ here = f"{base}/proposals/{proposal.id}"
436
+ if status == "merged":
437
+ return [
438
+ hint(
439
+ "refresh",
440
+ f"The target moved to {merged_revision}; take a new context pack before the "
441
+ "next write.",
442
+ method="POST",
443
+ href=f"{base}/context",
444
+ )
445
+ ]
446
+ if status == "conflicts":
447
+ return [
448
+ hint(
449
+ "inspect_conflicts",
450
+ "The Proposal has open Conflicts with the target.",
451
+ method="GET",
452
+ href=f"{here}/conflicts",
453
+ ),
454
+ hint(
455
+ "resolve_conflicts",
456
+ "A reviewer resolves them (choose ours, theirs or a value) and merges again.",
457
+ method="POST",
458
+ href=f"{here}/conflicts:resolve",
459
+ permission=Permission.CONFLICT_RESOLVE.value,
460
+ ),
461
+ hint(
462
+ "close_and_retry",
463
+ "Or close the Proposal and run the Operation again on the current target.",
464
+ method="POST",
465
+ href=f"{here}/close",
466
+ ),
467
+ ]
468
+ steps: list[Hint] = []
469
+ if "approvals-pending" in merge.blockers or "review-policy-needs-approval" in merge.blockers:
470
+ steps.append(
471
+ hint(
472
+ "await_review",
473
+ f"Waiting for approval ({approval.approvals} of {approval.required} required).",
474
+ method="POST",
475
+ href=f"{here}/reviews",
476
+ permission=Permission.PROPOSAL_REVIEW.value,
477
+ )
478
+ )
479
+ elif not merge.performed:
480
+ steps.append(
481
+ hint(
482
+ "merge",
483
+ "Merging needs a maintainer"
484
+ + ("" if merge.requested else " (auto_merge was not requested)")
485
+ + (
486
+ ""
487
+ if merge.allowed or not merge.requested
488
+ else " (the role of this agent may not merge automatically)"
489
+ )
490
+ + ".",
491
+ method="POST",
492
+ href=f"{here}/merge",
493
+ permission=Permission.PROPOSAL_MERGE.value,
494
+ )
495
+ )
496
+ steps.append(hint("get_proposal", "Read the state of the Proposal.", method="GET", href=here))
497
+ return steps
498
+
499
+
500
+ def _attempt_summary(view: proposals.AttemptView) -> AttemptSummary:
501
+ per_code: dict[str, dict[str, int]] = {}
502
+ for (code, resolved), count in sorted(view.counts.items()):
503
+ entry = per_code.setdefault(code, {"open": 0, "resolved": 0})
504
+ entry["resolved" if resolved else "open"] += count
505
+ return AttemptSummary(
506
+ id=view.attempt.id,
507
+ result=view.attempt.result,
508
+ open_conflicts=sum(c["open"] for c in per_code.values()),
509
+ resolved_conflicts=sum(c["resolved"] for c in per_code.values()),
510
+ counts=per_code,
511
+ )
512
+
513
+
514
+ async def _prepare(
515
+ store: StoreAccess,
516
+ domain_id: str,
517
+ request: ExecutionRequest,
518
+ principal: Principal,
519
+ keeper: KeeperSettings,
520
+ ) -> _Prepared:
521
+ async with store.sessions() as session, session.begin():
522
+ domain = await require_domain(session, domain_id)
523
+ target = await require_branch(session, domain_id, request.branch or domain.default_branch)
524
+ refs = await RefRepository(session, domain_id).all()
525
+ invocation = None
526
+ if request.idempotency_key is not None:
527
+ invocation = await InvocationRepository(session, domain_id).by_key(
528
+ principal.id, request.idempotency_key
529
+ )
530
+ return _Prepared(
531
+ settings=effective_settings(keeper.agent_writes, domain.settings),
532
+ default_branch=domain.default_branch,
533
+ target=target,
534
+ branches={ref.name: ref for ref in refs},
535
+ invocation=invocation,
536
+ )
537
+
538
+
539
+ def _check_ownership(
540
+ prepared: _Prepared, settings: AgentWriteSettings, principal: Principal, name: str
541
+ ) -> None:
542
+ existing = prepared.branches.get(name)
543
+ if existing is not None:
544
+ if existing.kind is not RefKind.BRANCH or existing.created_by != principal.id:
545
+ raise ProblemError(
546
+ ALREADY_EXISTS,
547
+ f"A branch or tag named {name!r} exists and is not a task branch of this "
548
+ "principal; use another task.",
549
+ )
550
+ return
551
+ mine = sorted(
552
+ n for n in prepared.branches if n.startswith(owner_prefix(settings, principal.id))
553
+ )
554
+ if len(mine) >= settings.max_open_branches_per_principal:
555
+ raise ProblemError(
556
+ BRANCH_LIMIT,
557
+ f"{len(mine)} task branches are open (limit "
558
+ f"{settings.max_open_branches_per_principal}); merge or close their Proposals "
559
+ "first, or reuse one of them as the task.",
560
+ extensions={"branches": mine},
561
+ )
562
+
563
+
564
+ def _check_replay(
565
+ prepared: _Prepared,
566
+ request: ExecutionRequest,
567
+ name: str,
568
+ *,
569
+ domain_id: str,
570
+ digests: DigestKeys,
571
+ ) -> InvocationRow | None:
572
+ """The earlier execution under the idempotency key when it is this one; conflict when the
573
+ key was used for something else."""
574
+ found = prepared.invocation
575
+ if found is None:
576
+ return None
577
+ accepted = operations_service.parameters_hashes(
578
+ request.operation, name, request.parameters, domain_id=domain_id, digests=digests
579
+ )
580
+ if found.params.get("parameters_hash") not in accepted:
581
+ raise ProblemError(
582
+ IDEMPOTENCY_CONFLICT,
583
+ "This Idempotency-Key was used with another Operation, branch or parameters.",
584
+ extensions={"invocation_id": found.id},
585
+ )
586
+ return found
587
+
588
+
589
+ async def _find_proposal(
590
+ store: StoreAccess, domain_id: str, source: str, target: str, *, any_status: bool
591
+ ) -> ProposalRow | None:
592
+ async with store.sessions() as session, session.begin():
593
+ await require_domain(session, domain_id)
594
+ found = await ProposalRepository(session, domain_id).page(
595
+ ProposalFilter(
596
+ status=None if any_status else ProposalStatus.OPEN,
597
+ source_ref=source,
598
+ target_ref=target,
599
+ ),
600
+ limit=1,
601
+ )
602
+ return found[0] if found else None
603
+
604
+
605
+ async def _upsert_proposal(
606
+ store: StoreAccess,
607
+ domain_id: str,
608
+ keeper: KeeperSettings,
609
+ settings: AgentWriteSettings,
610
+ principal: Principal,
611
+ *,
612
+ name: str,
613
+ target: str,
614
+ task: str,
615
+ intent: str | None,
616
+ line: str,
617
+ replayed: bool,
618
+ emit: Emit,
619
+ ) -> tuple[ProposalRow, bool]:
620
+ """The Proposal of the task branch: created, or its description extended. A replay reuses
621
+ the latest Proposal of the branch whatever its state."""
622
+ existing = await _find_proposal(store, domain_id, name, target, any_status=replayed)
623
+ if existing is None:
624
+ title = settings.title_template.format(principal=principal.id, task=task)
625
+ try:
626
+ created = await proposals.create(
627
+ store,
628
+ domain_id,
629
+ proposals.NewProposal(
630
+ source_ref=name,
631
+ target_ref=target,
632
+ title=title,
633
+ description=describe(intent, line, None, settings),
634
+ origin=ProposalOrigin.OPERATION,
635
+ ),
636
+ principal,
637
+ keeper.proposals,
638
+ idempotency_key=None,
639
+ )
640
+ except ProblemError as error:
641
+ if error.problem is not ALREADY_EXISTS:
642
+ raise
643
+ existing = await _find_proposal(store, domain_id, name, target, any_status=False)
644
+ if existing is None:
645
+ raise
646
+ else:
647
+ row = created.view.proposal
648
+ await emit(
649
+ "proposal.create",
650
+ row.id,
651
+ source=name,
652
+ target_branch=target,
653
+ origin=ProposalOrigin.OPERATION.value,
654
+ )
655
+ return row, True
656
+ if existing.status is ProposalStatus.OPEN and existing.author == principal.id:
657
+ text = describe(intent, line, existing.description, settings)
658
+ if text != existing.description:
659
+ view = await proposals.update(
660
+ store, domain_id, existing.id, keeper.proposals, title=None, description=text
661
+ )
662
+ await emit("proposal.update", existing.id, fields=["description"])
663
+ return view.proposal, False
664
+ return existing, False
665
+
666
+
667
+ async def run(
668
+ store: StoreAccess,
669
+ domain_id: str,
670
+ request: ExecutionRequest,
671
+ agent: AgentRequest,
672
+ principal: Principal,
673
+ keeper: KeeperSettings,
674
+ *,
675
+ original: ProblemError,
676
+ check: Check,
677
+ roles_of: Roles,
678
+ emit: Emit,
679
+ ) -> ExecutionOutcome | AgentWriteOutcome:
680
+ """Run `request` through a task branch and a Proposal after `original` refused it.
681
+
682
+ Raises `original` (with `next` hints) when the flow does not apply: no task, turned off,
683
+ or declined by the request. Violations, stale heads and permission failures are raised as
684
+ for any execution, before anything is created. Returns an `ExecutionOutcome` for an
685
+ Operation that has nothing to change (no branch or Proposal is made for it).
686
+ """
687
+ base = _paths(keeper, domain_id)
688
+ if agent.task is None:
689
+ raise hinted(original, base, "task-required")
690
+ prepared = await _prepare(store, domain_id, request, principal, keeper)
691
+ settings = prepared.settings
692
+ name = branch_name(settings, principal.id, agent.task)
693
+ task = name.rsplit("/", 1)[1]
694
+ branches.check_ref_name(name, keeper.branches, "/body/task")
695
+ target = prepared.target.name
696
+ context = AccessContext(branch=name)
697
+ decision = decide(
698
+ settings,
699
+ agent,
700
+ agent=principal.type in settings.principal_types,
701
+ roles=await roles_of(context),
702
+ )
703
+ if not decision.propose:
704
+ raise hinted(original, base, decision.refusal)
705
+ reason = str(original.extensions.get("reason", ""))
706
+
707
+ _check_ownership(prepared, settings, principal, name)
708
+ exists = name in prepared.branches
709
+ async with store.sessions() as session:
710
+ digests = await store.runtime.digests.ready(session)
711
+ replay = _check_replay(prepared, request, name, domain_id=domain_id, digests=digests)
712
+ await check(Permission.DATA_READ, AccessContext(branch=target))
713
+ await check(Permission.PROPOSAL_CREATE, context)
714
+ if not exists:
715
+ await check(Permission.BRANCH_CREATE, context)
716
+ if request.expected_head is not None and request.expected_head != prepared.target.head:
717
+ raise StaleHeadError(target, request.expected_head, prepared.target.head)
718
+
719
+ on_branch = ExecutionRequest(
720
+ operation=request.operation,
721
+ parameters=request.parameters,
722
+ branch=name,
723
+ idempotency_key=request.idempotency_key,
724
+ message=request.message,
725
+ reviewed_by_proposal=True,
726
+ )
727
+ proposals_path = f"{base}/proposals"
728
+ if replay is None:
729
+ dry = await operations_service.execute(
730
+ store,
731
+ domain_id,
732
+ ExecutionRequest(
733
+ operation=request.operation,
734
+ parameters=request.parameters,
735
+ branch=name if exists else target,
736
+ dry_run=True,
737
+ message=request.message,
738
+ reviewed_by_proposal=True,
739
+ ),
740
+ principal,
741
+ keeper.operations,
742
+ check=check,
743
+ proposals_path=proposals_path,
744
+ )
745
+ if dry.violations:
746
+ raise operations_service.refused(dry, limit=keeper.operations.max_issues)
747
+ if dry.edit_count == 0 and not exists:
748
+ dry.status = ExecutionStatus.COMMITTED
749
+ dry.branch = target
750
+ return dry
751
+
752
+ created_branch = False
753
+ if replay is None or exists:
754
+ if not exists:
755
+ try:
756
+ await branches.create(
757
+ store,
758
+ domain_id,
759
+ name,
760
+ principal,
761
+ keeper.branches,
762
+ source=target,
763
+ revision=None,
764
+ idempotency_key=None,
765
+ mode=BranchMode(settings.branch_mode),
766
+ )
767
+ created_branch = True
768
+ await emit("branch.create", name, source=target, purpose="agent-task")
769
+ except ProblemError as error:
770
+ if error.problem is not ALREADY_EXISTS:
771
+ raise
772
+ executed = await operations_service.execute(
773
+ store,
774
+ domain_id,
775
+ on_branch,
776
+ principal,
777
+ keeper.operations,
778
+ check=check,
779
+ proposals_path=proposals_path,
780
+ )
781
+ else:
782
+ executed = _recalled(replay, name)
783
+
784
+ parameters = replay.params.get("parameters", {}) if replay else executed.parameters
785
+ line = operation_line(request.operation, parameters, executed.invocation_id, settings)
786
+ row, created = await _upsert_proposal(
787
+ store,
788
+ domain_id,
789
+ keeper,
790
+ settings,
791
+ principal,
792
+ name=name,
793
+ target=target,
794
+ task=task,
795
+ intent=agent.intent,
796
+ line=line,
797
+ replayed=replay is not None,
798
+ emit=emit,
799
+ )
800
+ return await _settle(
801
+ store,
802
+ domain_id,
803
+ keeper,
804
+ settings,
805
+ principal,
806
+ decision,
807
+ row,
808
+ created,
809
+ executed,
810
+ emit=emit,
811
+ branch_created=created_branch,
812
+ policy_review=reason == REVIEW_POLICY,
813
+ )
814
+
815
+
816
+ def _recalled(found: InvocationRow, branch: str) -> ExecutionOutcome:
817
+ """The result of an execution whose task branch is gone (its Proposal was merged)."""
818
+ params = found.params
819
+ return ExecutionOutcome(
820
+ status=ExecutionStatus.COMMITTED,
821
+ operation=str(params.get("operation")),
822
+ branch=branch,
823
+ invocation_id=found.id,
824
+ parameters_hash=str(params.get("parameters_hash")),
825
+ head=bytes.fromhex(str(params["head"])),
826
+ revisions=[bytes.fromhex(str(r)) for r in params.get("revisions", [])],
827
+ edit_count=int(params.get("edit_count", 0)),
828
+ replayed=True,
829
+ )
830
+
831
+
832
+ async def _settle(
833
+ store: StoreAccess,
834
+ domain_id: str,
835
+ keeper: KeeperSettings,
836
+ settings: AgentWriteSettings,
837
+ principal: Principal,
838
+ decision: Decision,
839
+ row: ProposalRow,
840
+ created: bool,
841
+ executed: ExecutionOutcome,
842
+ *,
843
+ emit: Emit,
844
+ branch_created: bool,
845
+ policy_review: bool,
846
+ ) -> AgentWriteOutcome:
847
+ """Conflicts, approvals and the merge: the state the response reports."""
848
+ base = _paths(keeper, domain_id)
849
+ view = await proposals.get(store, domain_id, row.id, keeper.proposals)
850
+ status: Status = "proposed"
851
+ attempt: AttemptSummary | None = None
852
+ blockers: list[str] = []
853
+ performed = False
854
+ deleted = False
855
+ merged_revision: str | None = None
856
+ current = view.proposal
857
+ if current.status is ProposalStatus.MERGED:
858
+ status = "merged"
859
+ merged_revision = None if current.merged_revision is None else hex(current.merged_revision)
860
+ elif current.status is ProposalStatus.CLOSED:
861
+ raise ProblemError(
862
+ proposals.PROPOSAL_NOT_OPEN,
863
+ f"Proposal {current.id!r} was closed; use another task for a new Proposal.",
864
+ extensions={"proposal": current.id, "status": current.status.value},
865
+ )
866
+ else:
867
+ conflicts = await proposals.conflicts(
868
+ store,
869
+ domain_id,
870
+ current.id,
871
+ principal,
872
+ keeper.proposals,
873
+ proposals.ConflictQuery(limit=1),
874
+ )
875
+ attempt = _attempt_summary(conflicts)
876
+ blockers = merge_blockers(view.approval, policy_review=policy_review)
877
+ if attempt.open_conflicts:
878
+ status = "conflicts"
879
+ elif decision.merge and not blockers:
880
+ merged = await _merge(store, domain_id, keeper, principal, current)
881
+ if merged is None:
882
+ blockers = ["approvals-pending"]
883
+ elif merged.head is None:
884
+ status, attempt = "conflicts", _attempt_summary(merged.view)
885
+ else:
886
+ performed, status = True, "merged"
887
+ current = merged.proposal
888
+ merged_revision = hex(merged.head)
889
+ attempt = _attempt_summary(merged.view)
890
+ await emit(
891
+ "proposal.merge",
892
+ current.id,
893
+ revision=merged_revision,
894
+ result=merged.view.attempt.result,
895
+ automatic=True,
896
+ )
897
+ deleted = merged.source_deleted or await release_branch(
898
+ store, domain_id, current, keeper, emit=emit
899
+ )
900
+ elif decision.merge:
901
+ logger.info("automatic merge held back: %s", ", ".join(blockers))
902
+ summary = ProposalSummary(
903
+ id=current.id,
904
+ title=current.title,
905
+ status=current.status.value,
906
+ source_ref=current.source_ref,
907
+ target_ref=current.target_ref,
908
+ url=f"{base}/proposals/{current.id}",
909
+ created=created,
910
+ )
911
+ approval = ApprovalSummary(
912
+ required=view.approval.required,
913
+ approvals=len(view.approval.approvers),
914
+ satisfied=view.approval.satisfied,
915
+ )
916
+ merge = MergeSummary(
917
+ requested=decision.merge_requested,
918
+ allowed=decision.merge_allowed,
919
+ performed=performed,
920
+ blockers=blockers,
921
+ )
922
+ revisions = [hex(r) for r in executed.revisions]
923
+ return AgentWriteOutcome(
924
+ status=status,
925
+ operation=executed.operation,
926
+ branch=current.source_ref,
927
+ target=current.target_ref,
928
+ invocation_id=executed.invocation_id,
929
+ parameters_hash=executed.parameters_hash,
930
+ revision=revisions[-1] if revisions else None,
931
+ revisions=revisions,
932
+ edit_count=executed.edit_count,
933
+ replayed=executed.replayed,
934
+ proposal=summary,
935
+ approval=approval,
936
+ attempt=attempt,
937
+ merge=merge,
938
+ merged_revision=merged_revision,
939
+ branch_created=branch_created,
940
+ branch_deleted=deleted,
941
+ warnings=[f.document() for f in executed.warnings],
942
+ next=next_steps(
943
+ status,
944
+ base,
945
+ summary,
946
+ approval=approval,
947
+ merge=merge,
948
+ merged_revision=merged_revision,
949
+ ),
950
+ )
951
+
952
+
953
+ async def _merge(
954
+ store: StoreAccess,
955
+ domain_id: str,
956
+ keeper: KeeperSettings,
957
+ principal: Principal,
958
+ row: ProposalRow,
959
+ ) -> proposals.MergeOutcome | None:
960
+ """Merge `row`: the outcome (`head` is `None` while Conflicts remain), or `None` when the
961
+ approvals went missing meanwhile."""
962
+ try:
963
+ outcome = await proposals.merge(
964
+ store,
965
+ domain_id,
966
+ row.id,
967
+ principal,
968
+ keeper.proposals,
969
+ idempotency_key=None,
970
+ message=f"Merge {row.source_ref} (automatic)",
971
+ page_limit=1,
972
+ )
973
+ except ProblemError as error:
974
+ if error.problem is proposals.APPROVALS_REQUIRED:
975
+ return None
976
+ raise
977
+ return outcome
978
+
979
+
980
+ # Cleanup ---------------------------------------------------------------------------------
981
+
982
+
983
+ async def release_branch(
984
+ store: StoreAccess,
985
+ domain_id: str,
986
+ proposal: ProposalRow,
987
+ keeper: KeeperSettings,
988
+ *,
989
+ emit: Emit | None = None,
990
+ ) -> bool:
991
+ """Delete the task branch of a Proposal that merged or closed, unless
992
+ `delete_branch_on_merge` is off or another open Proposal still has it as source. Never
993
+ raises for a branch that cannot be deleted; returns whether it was."""
994
+ if proposal.status is ProposalStatus.OPEN:
995
+ return False
996
+ async with store.sessions() as session, session.begin():
997
+ domain = await require_domain(session, domain_id)
998
+ settings = effective_settings(keeper.agent_writes, domain.settings)
999
+ source = proposal.source_ref
1000
+ if not (settings.delete_branch_on_merge and is_task_branch(settings, source)):
1001
+ return False
1002
+ ref = await RefRepository(session, domain_id).get(source)
1003
+ if ref is None or ref.kind is not RefKind.BRANCH or ref.protected:
1004
+ return False
1005
+ if source == domain.default_branch:
1006
+ return False
1007
+ others = await ProposalRepository(session, domain_id).page(
1008
+ ProposalFilter(status=ProposalStatus.OPEN, source_ref=source), limit=1
1009
+ )
1010
+ if others:
1011
+ return False
1012
+ try:
1013
+ await branches.delete(store, domain_id, source, keeper.branches)
1014
+ except ProblemError as error:
1015
+ logger.warning("task branch %s kept: %s", source, error.problem_detail)
1016
+ return False
1017
+ if emit is not None:
1018
+ await emit("branch.delete", source, reason=f"proposal-{proposal.status.value}")
1019
+ return True
1020
+
1021
+
1022
+ def audit_details(outcome: AgentWriteOutcome) -> dict[str, Any]:
1023
+ """Facts about an agent write for the audit entry of the request."""
1024
+ return {
1025
+ "invocation_id": outcome.invocation_id,
1026
+ "parameters_hash": outcome.parameters_hash,
1027
+ "branch": outcome.branch,
1028
+ "target_branch": outcome.target,
1029
+ "proposal": outcome.proposal.id,
1030
+ "status": outcome.status,
1031
+ "revisions": outcome.revisions,
1032
+ "replayed": outcome.replayed,
1033
+ "merge_requested": outcome.merge.requested,
1034
+ "merge_performed": outcome.merge.performed,
1035
+ }