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.
- lorebase_keeper/__init__.py +1 -0
- lorebase_keeper/__main__.py +456 -0
- lorebase_keeper/agents/__init__.py +1 -0
- lorebase_keeper/agents/budget.py +247 -0
- lorebase_keeper/agents/context.py +529 -0
- lorebase_keeper/agents/explain.py +582 -0
- lorebase_keeper/agents/feed.py +259 -0
- lorebase_keeper/agents/markdown.py +219 -0
- lorebase_keeper/agents/pack.py +403 -0
- lorebase_keeper/agents/settings.py +111 -0
- lorebase_keeper/app.py +373 -0
- lorebase_keeper/auth/__init__.py +4 -0
- lorebase_keeper/auth/api_keys.py +127 -0
- lorebase_keeper/auth/audit.py +356 -0
- lorebase_keeper/auth/cache.py +53 -0
- lorebase_keeper/auth/config.py +618 -0
- lorebase_keeper/auth/deps.py +183 -0
- lorebase_keeper/auth/keyring.py +14 -0
- lorebase_keeper/auth/oidc.py +242 -0
- lorebase_keeper/auth/permissions.py +142 -0
- lorebase_keeper/auth/ports.py +212 -0
- lorebase_keeper/auth/principals.py +377 -0
- lorebase_keeper/auth/provider.py +250 -0
- lorebase_keeper/auth/rbac.py +247 -0
- lorebase_keeper/auth/read_audit.py +357 -0
- lorebase_keeper/auth/runtime.py +113 -0
- lorebase_keeper/auth/sessions.py +452 -0
- lorebase_keeper/bootstrap.py +151 -0
- lorebase_keeper/client_address.py +129 -0
- lorebase_keeper/context.py +226 -0
- lorebase_keeper/db.py +93 -0
- lorebase_keeper/deps.py +47 -0
- lorebase_keeper/errors.py +257 -0
- lorebase_keeper/health.py +61 -0
- lorebase_keeper/kindhealth/__init__.py +6 -0
- lorebase_keeper/kindhealth/config.py +51 -0
- lorebase_keeper/kindhealth/markdown.py +163 -0
- lorebase_keeper/kindhealth/models.py +179 -0
- lorebase_keeper/kindhealth/report.py +154 -0
- lorebase_keeper/kindhealth/scan.py +512 -0
- lorebase_keeper/middleware.py +285 -0
- lorebase_keeper/pagination.py +87 -0
- lorebase_keeper/ratelimit/__init__.py +10 -0
- lorebase_keeper/ratelimit/bucket.py +118 -0
- lorebase_keeper/ratelimit/config.py +283 -0
- lorebase_keeper/ratelimit/enforce.py +393 -0
- lorebase_keeper/ratelimit/limiter.py +149 -0
- lorebase_keeper/ratelimit/quotas.py +204 -0
- lorebase_keeper/ratelimit/shared.py +242 -0
- lorebase_keeper/readiness.py +257 -0
- lorebase_keeper/reading/__init__.py +1 -0
- lorebase_keeper/reading/caching.py +251 -0
- lorebase_keeper/reading/compiler.py +678 -0
- lorebase_keeper/reading/cursors.py +56 -0
- lorebase_keeper/reading/diff.py +408 -0
- lorebase_keeper/reading/graph.py +268 -0
- lorebase_keeper/reading/history.py +152 -0
- lorebase_keeper/reading/points.py +410 -0
- lorebase_keeper/reading/problems.py +74 -0
- lorebase_keeper/reading/record_history.py +722 -0
- lorebase_keeper/reading/records.py +780 -0
- lorebase_keeper/reading/requests.py +107 -0
- lorebase_keeper/reading/runtime.py +145 -0
- lorebase_keeper/reading/search.py +708 -0
- lorebase_keeper/reading/sensitivity.py +882 -0
- lorebase_keeper/reading/settings.py +339 -0
- lorebase_keeper/reading/snapshots.py +148 -0
- lorebase_keeper/reading/tree.py +98 -0
- lorebase_keeper/reading/views.py +264 -0
- lorebase_keeper/reading/visibility.py +93 -0
- lorebase_keeper/routes/__init__.py +1 -0
- lorebase_keeper/routes/admin.py +597 -0
- lorebase_keeper/routes/agents.py +160 -0
- lorebase_keeper/routes/branches.py +438 -0
- lorebase_keeper/routes/derivations.py +215 -0
- lorebase_keeper/routes/documents.py +497 -0
- lorebase_keeper/routes/domain_api.py +59 -0
- lorebase_keeper/routes/domains.py +220 -0
- lorebase_keeper/routes/events.py +187 -0
- lorebase_keeper/routes/kind_health.py +166 -0
- lorebase_keeper/routes/operations.py +392 -0
- lorebase_keeper/routes/proposal_items.py +563 -0
- lorebase_keeper/routes/proposals.py +1107 -0
- lorebase_keeper/routes/read.py +493 -0
- lorebase_keeper/routes/revisions.py +523 -0
- lorebase_keeper/routes/schema.py +682 -0
- lorebase_keeper/routes/schema_inference.py +437 -0
- lorebase_keeper/routes/schema_suggestions.py +328 -0
- lorebase_keeper/routes/sessions.py +286 -0
- lorebase_keeper/routes/source_preview.py +232 -0
- lorebase_keeper/routes/sources.py +200 -0
- lorebase_keeper/routes/trace.py +506 -0
- lorebase_keeper/routes/vault.py +332 -0
- lorebase_keeper/routes/webhooks.py +298 -0
- lorebase_keeper/routes/whoami.py +88 -0
- lorebase_keeper/services/__init__.py +1 -0
- lorebase_keeper/services/agent_writes.py +1035 -0
- lorebase_keeper/services/branches.py +337 -0
- lorebase_keeper/services/config.py +431 -0
- lorebase_keeper/services/derivation_preview.py +279 -0
- lorebase_keeper/services/document_urls.py +114 -0
- lorebase_keeper/services/domains.py +118 -0
- lorebase_keeper/services/errors.py +196 -0
- lorebase_keeper/services/operation_catalog.py +806 -0
- lorebase_keeper/services/operation_events.py +199 -0
- lorebase_keeper/services/operations.py +1229 -0
- lorebase_keeper/services/pii_import.py +222 -0
- lorebase_keeper/services/proposal_reads.py +158 -0
- lorebase_keeper/services/proposals.py +850 -0
- lorebase_keeper/services/reads.py +286 -0
- lorebase_keeper/services/schema.py +601 -0
- lorebase_keeper/services/schema_inference.py +390 -0
- lorebase_keeper/services/schema_suggestions.py +418 -0
- lorebase_keeper/services/source_preview.py +127 -0
- lorebase_keeper/settings.py +313 -0
- lorebase_keeper/tracing/__init__.py +1 -0
- lorebase_keeper/tracing/capture.py +350 -0
- lorebase_keeper/tracing/config.py +157 -0
- lorebase_keeper/tracing/explain.py +97 -0
- lorebase_keeper/tracing/middleware.py +359 -0
- lorebase_keeper/tracing/notes.py +80 -0
- lorebase_keeper/tracing/recorder.py +180 -0
- lorebase_keeper-0.2.3.dist-info/METADATA +21 -0
- lorebase_keeper-0.2.3.dist-info/RECORD +126 -0
- lorebase_keeper-0.2.3.dist-info/WHEEL +4 -0
- 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
|
+
}
|