fivefold 0.1.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- fivefold/__init__.py +4 -0
- fivefold/_data/db/bootstrap.sql +26 -0
- fivefold/_data/db/migrations/0001_schemas.sql +67 -0
- fivefold/_data/db/migrations/0002_gateway.sql +224 -0
- fivefold/_data/db/migrations/0003_gateway_record_0010.sql +91 -0
- fivefold/_data/db/migrations/0004_harness.sql +141 -0
- fivefold/_data/db/migrations/0005_sim.sql +679 -0
- fivefold/_data/db/migrations/0006_gateway_reads.sql +66 -0
- fivefold/_data/db/migrations/0007_eval.sql +33 -0
- fivefold/_data/db/migrations/0008_run_stop.sql +18 -0
- fivefold/_data/db/migrations/0009_message_copies.sql +69 -0
- fivefold/_data/db/migrations/0010_gateway_g1_check.sql +14 -0
- fivefold/_data/db/migrations/0011_model_calls.sql +37 -0
- fivefold/_data/db/migrations/0012_recovery_latency.sql +23 -0
- fivefold/_data/db/migrations/0013_split_topology.sql +33 -0
- fivefold/_data/db/migrations/0014_tool_call_args.sql +20 -0
- fivefold/_data/db/registry/0001_registry.sql +31 -0
- fivefold/_data/faults/expected.yaml +406 -0
- fivefold/_data/scenarios/dev/dev-001-single-po.yaml +45 -0
- fivefold/_data/scenarios/dev/dev-002-human-approval.yaml +47 -0
- fivefold/agents/__init__.py +7 -0
- fivefold/agents/branch.py +187 -0
- fivefold/agents/checkpoint.py +77 -0
- fivefold/agents/connection.py +153 -0
- fivefold/agents/live.py +492 -0
- fivefold/agents/policy.py +426 -0
- fivefold/agents/remote.py +333 -0
- fivefold/agents/replay.py +170 -0
- fivefold/agents/scripted.py +122 -0
- fivefold/agents/tools.py +229 -0
- fivefold/agents/worker.py +164 -0
- fivefold/domain/__init__.py +5 -0
- fivefold/domain/api.py +517 -0
- fivefold/domain/authority.py +149 -0
- fivefold/domain/contracts.py +80 -0
- fivefold/domain/identity.py +113 -0
- fivefold/domain/prices.py +178 -0
- fivefold/domain/report.py +92 -0
- fivefold/domain/rules.py +346 -0
- fivefold/domain/scenario.py +524 -0
- fivefold/evaluator/__init__.py +155 -0
- fivefold/evaluator/__main__.py +127 -0
- fivefold/evaluator/authorization.py +146 -0
- fivefold/evaluator/checks.py +331 -0
- fivefold/evaluator/evaluate.py +109 -0
- fivefold/evaluator/evidence.py +392 -0
- fivefold/evaluator/freshness.py +136 -0
- fivefold/evaluator/liveness.py +236 -0
- fivefold/evaluator/load.py +354 -0
- fivefold/evaluator/metrics.py +95 -0
- fivefold/evaluator/records.py +452 -0
- fivefold/evaluator/recovery.py +209 -0
- fivefold/evaluator/report.py +1096 -0
- fivefold/evaluator/result.py +344 -0
- fivefold/evaluator/store.py +83 -0
- fivefold/faults/__init__.py +5 -0
- fivefold/faults/catalog.py +278 -0
- fivefold/faults/plan.py +538 -0
- fivefold/gateway/__init__.py +6 -0
- fivefold/gateway/admin.py +179 -0
- fivefold/gateway/admin_api.py +398 -0
- fivefold/gateway/codec.py +372 -0
- fivefold/gateway/destination.py +64 -0
- fivefold/gateway/dispatcher.py +379 -0
- fivefold/gateway/freshness.py +83 -0
- fivefold/gateway/invariants.py +761 -0
- fivefold/gateway/memory.py +277 -0
- fivefold/gateway/pg_store.py +657 -0
- fivefold/gateway/records.py +592 -0
- fivefold/gateway/server.py +102 -0
- fivefold/gateway/sim_client.py +295 -0
- fivefold/gateway/state_machine.py +376 -0
- fivefold/gateway/steps.py +897 -0
- fivefold/gateway/store.py +635 -0
- fivefold/gateway/tools.py +424 -0
- fivefold/gateway/twin.py +199 -0
- fivefold/gateway/wire.py +138 -0
- fivefold/harness/__init__.py +6 -0
- fivefold/harness/actors.py +230 -0
- fivefold/harness/cells.py +303 -0
- fivefold/harness/clock.py +209 -0
- fivefold/harness/demo.py +397 -0
- fivefold/harness/fault_effects.py +122 -0
- fivefold/harness/live_options.py +159 -0
- fivefold/harness/log.py +540 -0
- fivefold/harness/mcp_link.py +409 -0
- fivefold/harness/migrations.py +520 -0
- fivefold/harness/models.py +368 -0
- fivefold/harness/registry.py +105 -0
- fivefold/harness/reports.py +100 -0
- fivefold/harness/rng.py +57 -0
- fivefold/harness/run.py +881 -0
- fivefold/harness/scheduler.py +441 -0
- fivefold/harness/sim_points.py +215 -0
- fivefold/harness/split/__init__.py +34 -0
- fivefold/harness/split/__main__.py +275 -0
- fivefold/harness/split/credentials.py +74 -0
- fivefold/harness/split/faults.py +75 -0
- fivefold/harness/split/gateway.py +769 -0
- fivefold/harness/split/hops.py +291 -0
- fivefold/harness/split/lifecycle.py +322 -0
- fivefold/harness/split/rundir.py +152 -0
- fivefold/harness/split/service.py +157 -0
- fivefold/harness/split/simulator.py +432 -0
- fivefold/harness/study.py +643 -0
- fivefold/harness/transport.py +533 -0
- fivefold/paths.py +24 -0
- fivefold/py.typed +0 -0
- fivefold/recorder/__init__.py +18 -0
- fivefold/recorder/__main__.py +308 -0
- fivefold/recorder/cassette.py +322 -0
- fivefold/recorder/playback.py +316 -0
- fivefold/recorder/recording.py +133 -0
- fivefold/sim/__init__.py +37 -0
- fivefold/sim/config.py +52 -0
- fivefold/sim/endpoint.py +176 -0
- fivefold/sim/ledger.py +583 -0
- fivefold/sim/service.py +834 -0
- fivefold/viewer/__init__.py +14 -0
- fivefold/viewer/__main__.py +75 -0
- fivefold/viewer/app.py +122 -0
- fivefold/viewer/records.py +108 -0
- fivefold/viewer/source.py +196 -0
- fivefold/viewer/timeline.py +61 -0
- fivefold-0.1.0.dist-info/METADATA +169 -0
- fivefold-0.1.0.dist-info/RECORD +128 -0
- fivefold-0.1.0.dist-info/WHEEL +4 -0
- fivefold-0.1.0.dist-info/licenses/LICENSE +202 -0
|
@@ -0,0 +1,424 @@
|
|
|
1
|
+
"""The gateway's tools, as an agent worker calls them over MCP (0001, 0003, 0008).
|
|
2
|
+
|
|
3
|
+
G1 and G2 expose the same tools with the same schemas; only their behaviour differs
|
|
4
|
+
(0008). The list below is G2's. G1, authorization only, is the store with identity off:
|
|
5
|
+
|
|
6
|
+
- Every write call is a new action with its own approval request, and no fact is
|
|
7
|
+
checked. When the send's outcome is unknown at the end of the call's wait (a timeout
|
|
8
|
+
or a server error), the call fails with the tool error `gateway_timeout`, as a proxy
|
|
9
|
+
returns 504, so the agent's framework retries it. The action stays OutcomeUnknown.
|
|
10
|
+
- `submit_final_report` hands the report to the harness's report sink as it came and
|
|
11
|
+
checks nothing. The sink records it and says what breaks the schema, as it does for
|
|
12
|
+
B0's reports, and the agent is told the same.
|
|
13
|
+
|
|
14
|
+
- Reads (`get_quote`, `list_suppliers`, `get_budget`, `get_inventory`) take the
|
|
15
|
+
simulator's own arguments, read through the gateway's simulator client, record the
|
|
16
|
+
read and return `{read_id, key, version, data}`.
|
|
17
|
+
- Writes (`submit_purchase_order`, `reserve_inventory`) take the business arguments,
|
|
18
|
+
`intent_id`, `based_on` (read ids) and an optional `note`. Fields outside the schema
|
|
19
|
+
are allowed and ignored, because they are volatile (0001, item 7). A call runs
|
|
20
|
+
admission (0001, item 17), starts the action's driver, waits at most `tool_wait_ms`
|
|
21
|
+
for a state the agent can act on, and returns the action's result (0003).
|
|
22
|
+
- `get_action_status(action_id, wait_ms)` waits at most `wait_ms` for a final state. It
|
|
23
|
+
never contacts the destination (0003). Its schema allows at most 60,000 ms, 0005's
|
|
24
|
+
default; a wait above the run's own `max_wait_ms` is refused too, as `invalid_args`,
|
|
25
|
+
so the schema the agent sees stays the same in every run.
|
|
26
|
+
- `submit_final_report(claims)` refuses a report that breaks the schema with
|
|
27
|
+
`invalid_args`, checks the rest against the records, and hands an accepted report to
|
|
28
|
+
the harness's report sink (0003, 0008).
|
|
29
|
+
|
|
30
|
+
What has no refusal reason in 0003 is a tool error, as MCP reports one: a read the
|
|
31
|
+
simulator refused or did not answer in time (`gateway_timeout`, as a proxy's 504), a
|
|
32
|
+
status call for an action that does not exist, and an unknown tool.
|
|
33
|
+
|
|
34
|
+
The store logs the response to each write, status call and G2 report with the call's
|
|
35
|
+
arguments as they arrived (`gw.tool_call`, 0003). Reads are recorded as reads; tool
|
|
36
|
+
errors, G1's reports and a report that breaks the schema are not logged.
|
|
37
|
+
"""
|
|
38
|
+
|
|
39
|
+
from __future__ import annotations
|
|
40
|
+
|
|
41
|
+
from collections.abc import Awaitable, Callable, Mapping
|
|
42
|
+
from dataclasses import dataclass
|
|
43
|
+
from typing import Annotated, Literal, Protocol
|
|
44
|
+
|
|
45
|
+
from pydantic import (
|
|
46
|
+
AfterValidator,
|
|
47
|
+
BaseModel,
|
|
48
|
+
ConfigDict,
|
|
49
|
+
Field,
|
|
50
|
+
StrictInt,
|
|
51
|
+
StringConstraints,
|
|
52
|
+
ValidationError,
|
|
53
|
+
)
|
|
54
|
+
|
|
55
|
+
from fivefold.domain.api import (
|
|
56
|
+
FactRead,
|
|
57
|
+
GetBudget,
|
|
58
|
+
GetInventory,
|
|
59
|
+
GetQuote,
|
|
60
|
+
Id,
|
|
61
|
+
ListSuppliers,
|
|
62
|
+
Minor,
|
|
63
|
+
Quantity,
|
|
64
|
+
WaitLimit,
|
|
65
|
+
within_wait_limit,
|
|
66
|
+
)
|
|
67
|
+
from fivefold.domain.identity import InvalidArgs, action_key, normalize, target_of
|
|
68
|
+
from fivefold.domain.report import FinalReport, InvalidReport, parse_report, validation_messages
|
|
69
|
+
from fivefold.domain.rules import Operation, dependencies
|
|
70
|
+
from fivefold.gateway import wire
|
|
71
|
+
from fivefold.gateway.destination import Unreachable
|
|
72
|
+
from fivefold.gateway.dispatcher import Dispatcher
|
|
73
|
+
from fivefold.gateway.records import (
|
|
74
|
+
ActionResult,
|
|
75
|
+
Claim,
|
|
76
|
+
ClaimStatus,
|
|
77
|
+
Refusal,
|
|
78
|
+
RefusalReason,
|
|
79
|
+
ReportAccepted,
|
|
80
|
+
WriteCall,
|
|
81
|
+
)
|
|
82
|
+
from fivefold.gateway.sim_client import ReadRefused, ReadRequest
|
|
83
|
+
from fivefold.gateway.state_machine import FINAL_STATES, ActionState, EventKind
|
|
84
|
+
from fivefold.gateway.store import ActionStore, UnknownAction
|
|
85
|
+
from fivefold.harness.scheduler import Scheduler
|
|
86
|
+
|
|
87
|
+
_S = ActionState
|
|
88
|
+
|
|
89
|
+
ANSWERED_STATES = frozenset(
|
|
90
|
+
{_S.PENDING_APPROVAL, _S.CONFIRMED, _S.REJECTED, _S.FAILED, _S.OUTCOME_UNKNOWN}
|
|
91
|
+
)
|
|
92
|
+
"""The states a write call returns as soon as the action reaches one (0003)."""
|
|
93
|
+
|
|
94
|
+
ReadId = Annotated[str, StringConstraints(pattern=r"^[^\x00-\x1f\x7f]{1,64}$")]
|
|
95
|
+
"""A cited read id. One the gateway never issued is refused as `unknown_read`."""
|
|
96
|
+
|
|
97
|
+
Note = Annotated[str, StringConstraints(pattern=r"^[^\x00]*$", max_length=2_000)]
|
|
98
|
+
AnyCaseCurrency = Annotated[str, StringConstraints(pattern=r"^[A-Za-z]{3}$")]
|
|
99
|
+
"""A currency code in any case. The gateway uppercases it (0001, item 7)."""
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
class WriteArgs(BaseModel):
|
|
103
|
+
"""What every write tool takes besides its business arguments (0001, 0008)."""
|
|
104
|
+
|
|
105
|
+
model_config = ConfigDict(extra="allow", frozen=True)
|
|
106
|
+
|
|
107
|
+
intent_id: Id
|
|
108
|
+
based_on: list[ReadId] = []
|
|
109
|
+
note: Note | None = None
|
|
110
|
+
|
|
111
|
+
|
|
112
|
+
class PurchaseOrderArgs(WriteArgs):
|
|
113
|
+
"""Arguments of `submit_purchase_order`."""
|
|
114
|
+
|
|
115
|
+
supplier_id: Id
|
|
116
|
+
sku: Id
|
|
117
|
+
quantity: Quantity
|
|
118
|
+
unit_price_minor: Minor
|
|
119
|
+
currency: AnyCaseCurrency
|
|
120
|
+
cost_center: Id
|
|
121
|
+
|
|
122
|
+
|
|
123
|
+
class ReservationArgs(WriteArgs):
|
|
124
|
+
"""Arguments of `reserve_inventory`."""
|
|
125
|
+
|
|
126
|
+
warehouse_id: Id
|
|
127
|
+
sku: Id
|
|
128
|
+
quantity: Quantity
|
|
129
|
+
|
|
130
|
+
|
|
131
|
+
class ActionStatusArgs(BaseModel):
|
|
132
|
+
"""Arguments of `get_action_status`."""
|
|
133
|
+
|
|
134
|
+
model_config = ConfigDict(extra="forbid", frozen=True)
|
|
135
|
+
|
|
136
|
+
action_id: Annotated[str, StringConstraints(pattern=r"^A-[0-9]{4,}$")]
|
|
137
|
+
wait_ms: Annotated[StrictInt, Field(ge=0, le=60_000), AfterValidator(within_wait_limit)] = 0
|
|
138
|
+
"""At most 60,000 by the schema, and at most the run's `max_wait_ms` when validated
|
|
139
|
+
with a `WaitLimit`."""
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
@dataclass(frozen=True)
|
|
143
|
+
class ToolDefinition:
|
|
144
|
+
"""A tool as `tools/list` describes it."""
|
|
145
|
+
|
|
146
|
+
name: str
|
|
147
|
+
description: str
|
|
148
|
+
arguments: type[BaseModel]
|
|
149
|
+
|
|
150
|
+
def input_schema(self) -> dict[str, object]:
|
|
151
|
+
"""The tool's input as JSON Schema."""
|
|
152
|
+
return self.arguments.model_json_schema()
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
TOOLS: tuple[ToolDefinition, ...] = (
|
|
156
|
+
ToolDefinition("get_quote", "Read a supplier's quote for a sku.", GetQuote),
|
|
157
|
+
ToolDefinition("list_suppliers", "Read the supplier directory.", ListSuppliers),
|
|
158
|
+
ToolDefinition("get_budget", "Read a cost center's budget.", GetBudget),
|
|
159
|
+
ToolDefinition("get_inventory", "Read a sku's stock in a warehouse.", GetInventory),
|
|
160
|
+
ToolDefinition(
|
|
161
|
+
"submit_purchase_order",
|
|
162
|
+
"Propose a purchase order for an intent, citing the reads it relies on.",
|
|
163
|
+
PurchaseOrderArgs,
|
|
164
|
+
),
|
|
165
|
+
ToolDefinition(
|
|
166
|
+
"reserve_inventory",
|
|
167
|
+
"Propose an inventory reservation for an intent, citing the reads it relies on.",
|
|
168
|
+
ReservationArgs,
|
|
169
|
+
),
|
|
170
|
+
ToolDefinition(
|
|
171
|
+
"get_action_status",
|
|
172
|
+
"An action's result. Waits up to wait_ms (at most 60000) for a final state.",
|
|
173
|
+
ActionStatusArgs,
|
|
174
|
+
),
|
|
175
|
+
ToolDefinition(
|
|
176
|
+
"submit_final_report",
|
|
177
|
+
"Report, for every intent of the task, whether it is done, not done or unknown.",
|
|
178
|
+
FinalReport,
|
|
179
|
+
),
|
|
180
|
+
)
|
|
181
|
+
"""Every tool G modes expose, in `tools/list` order."""
|
|
182
|
+
|
|
183
|
+
|
|
184
|
+
class ToolError(Exception):
|
|
185
|
+
"""A tool call that failed without a refusal reason; MCP reports it as an error."""
|
|
186
|
+
|
|
187
|
+
def __init__(self, code: str, message: str) -> None:
|
|
188
|
+
super().__init__(f"{code}: {message}")
|
|
189
|
+
self.code = code
|
|
190
|
+
self.message = message
|
|
191
|
+
|
|
192
|
+
|
|
193
|
+
class Reader(Protocol):
|
|
194
|
+
"""Reads facts from the simulator: the gateway's simulator client."""
|
|
195
|
+
|
|
196
|
+
async def read(self, request: ReadRequest) -> FactRead:
|
|
197
|
+
"""Read one fact. Raises `Unreachable` or `ReadRefused`."""
|
|
198
|
+
|
|
199
|
+
|
|
200
|
+
class ReportSink(Protocol):
|
|
201
|
+
"""The harness's report sink."""
|
|
202
|
+
|
|
203
|
+
def submit(
|
|
204
|
+
self,
|
|
205
|
+
worker: str,
|
|
206
|
+
report: object,
|
|
207
|
+
*,
|
|
208
|
+
accepted_by: Literal["gateway", "sink"],
|
|
209
|
+
message_seq: int | None = None,
|
|
210
|
+
) -> tuple[str, ...]:
|
|
211
|
+
"""Record a report; return what breaks its schema."""
|
|
212
|
+
|
|
213
|
+
|
|
214
|
+
@dataclass(frozen=True)
|
|
215
|
+
class ToolTiming:
|
|
216
|
+
"""How long tools wait, in virtual ms (0003, 0005)."""
|
|
217
|
+
|
|
218
|
+
tool_wait_ms: int = 2_500
|
|
219
|
+
max_wait_ms: int = 60_000
|
|
220
|
+
"""The longest `wait_ms` `get_action_status` accepts: the scenario's `max_wait_ms`."""
|
|
221
|
+
|
|
222
|
+
|
|
223
|
+
Json = dict[str, object]
|
|
224
|
+
Handler = Callable[[Mapping[str, object], "Call"], Awaitable[Json]]
|
|
225
|
+
|
|
226
|
+
|
|
227
|
+
@dataclass(frozen=True)
|
|
228
|
+
class Call:
|
|
229
|
+
"""Who made a tool call: the agent worker, and the message that carried the call."""
|
|
230
|
+
|
|
231
|
+
worker: str
|
|
232
|
+
message_seq: int | None
|
|
233
|
+
|
|
234
|
+
|
|
235
|
+
class GatewayTools:
|
|
236
|
+
"""G2's tools for one run. `call` serves one tool call of one agent worker."""
|
|
237
|
+
|
|
238
|
+
def __init__(
|
|
239
|
+
self,
|
|
240
|
+
scheduler: Scheduler,
|
|
241
|
+
store: ActionStore,
|
|
242
|
+
dispatcher: Dispatcher,
|
|
243
|
+
reader: Reader,
|
|
244
|
+
reports: ReportSink,
|
|
245
|
+
*,
|
|
246
|
+
task_id: str,
|
|
247
|
+
intents: Mapping[str, str],
|
|
248
|
+
timing: ToolTiming | None = None,
|
|
249
|
+
) -> None:
|
|
250
|
+
self._scheduler = scheduler
|
|
251
|
+
self._store = store
|
|
252
|
+
self._dispatcher = dispatcher
|
|
253
|
+
self._reader = reader
|
|
254
|
+
self._reports = reports
|
|
255
|
+
self._task_id = task_id
|
|
256
|
+
self._intents = dict(intents)
|
|
257
|
+
self._timing = timing if timing is not None else ToolTiming()
|
|
258
|
+
self._handlers: dict[str, Handler] = {
|
|
259
|
+
"get_quote": self._read_with(GetQuote),
|
|
260
|
+
"list_suppliers": self._read_with(ListSuppliers),
|
|
261
|
+
"get_budget": self._read_with(GetBudget),
|
|
262
|
+
"get_inventory": self._read_with(GetInventory),
|
|
263
|
+
"submit_purchase_order": self._write_with(PurchaseOrderArgs),
|
|
264
|
+
"reserve_inventory": self._write_with(ReservationArgs),
|
|
265
|
+
"get_action_status": self._status,
|
|
266
|
+
"submit_final_report": self._report,
|
|
267
|
+
}
|
|
268
|
+
|
|
269
|
+
async def call(
|
|
270
|
+
self,
|
|
271
|
+
name: str,
|
|
272
|
+
arguments: Mapping[str, object],
|
|
273
|
+
*,
|
|
274
|
+
worker: str,
|
|
275
|
+
message_seq: int | None = None,
|
|
276
|
+
) -> Json:
|
|
277
|
+
"""Serve one tool call from `worker`. Raises `ToolError`.
|
|
278
|
+
|
|
279
|
+
`message_seq` is the harness's seq of the message that carried the call.
|
|
280
|
+
"""
|
|
281
|
+
handler = self._handlers.get(name)
|
|
282
|
+
if handler is None:
|
|
283
|
+
raise ToolError("unknown_tool", f"no tool named {name!r}")
|
|
284
|
+
return await handler(arguments, Call(worker, message_seq))
|
|
285
|
+
|
|
286
|
+
@property
|
|
287
|
+
def _now(self) -> int:
|
|
288
|
+
return self._scheduler.now
|
|
289
|
+
|
|
290
|
+
# Reads -----------------------------------------------------------------------------------
|
|
291
|
+
|
|
292
|
+
def _read_with(self, model: type[ReadRequest]) -> Handler:
|
|
293
|
+
async def read(arguments: Mapping[str, object], call: Call) -> Json:
|
|
294
|
+
try:
|
|
295
|
+
request = model.model_validate(dict(arguments))
|
|
296
|
+
except ValidationError as error:
|
|
297
|
+
raise ToolError("invalid_args", "; ".join(validation_messages(error))) from None
|
|
298
|
+
try:
|
|
299
|
+
fact = await self._reader.read(request)
|
|
300
|
+
except Unreachable as error:
|
|
301
|
+
raise ToolError("gateway_timeout", str(error)) from None
|
|
302
|
+
except ReadRefused as error:
|
|
303
|
+
raise ToolError(error.reason, error.detail) from None
|
|
304
|
+
record = self._store.record_read(fact.key, fact.version, fact.data, self._now)
|
|
305
|
+
return wire.read(record)
|
|
306
|
+
|
|
307
|
+
return read
|
|
308
|
+
|
|
309
|
+
# Writes ----------------------------------------------------------------------------------
|
|
310
|
+
|
|
311
|
+
def _write_with(self, model: type[PurchaseOrderArgs] | type[ReservationArgs]) -> Handler:
|
|
312
|
+
async def write(arguments: Mapping[str, object], caller: Call) -> Json:
|
|
313
|
+
operation = (
|
|
314
|
+
Operation.SUBMIT_PURCHASE_ORDER
|
|
315
|
+
if model is PurchaseOrderArgs
|
|
316
|
+
else Operation.RESERVE_INVENTORY
|
|
317
|
+
)
|
|
318
|
+
try:
|
|
319
|
+
args = model.model_validate(dict(arguments))
|
|
320
|
+
normal = normalize(operation, args.model_dump())
|
|
321
|
+
except ValidationError as error:
|
|
322
|
+
return self._invalid(operation, arguments, "; ".join(validation_messages(error)))
|
|
323
|
+
except InvalidArgs as error:
|
|
324
|
+
return self._invalid(operation, arguments, str(error))
|
|
325
|
+
call = WriteCall(
|
|
326
|
+
intent_id=args.intent_id,
|
|
327
|
+
operation=str(operation),
|
|
328
|
+
target=target_of(operation, normal),
|
|
329
|
+
args=normal,
|
|
330
|
+
action_key=action_key(self._task_id, args.intent_id, operation, normal),
|
|
331
|
+
based_on=tuple(args.based_on),
|
|
332
|
+
dependencies=tuple(d.key for d in dependencies(operation, normal)),
|
|
333
|
+
)
|
|
334
|
+
outcome = self._store.propose(call, self._now, args=arguments)
|
|
335
|
+
if isinstance(outcome, Refusal):
|
|
336
|
+
return wire.refusal(outcome)
|
|
337
|
+
self._dispatcher.drive(outcome.action_id)
|
|
338
|
+
await self._dispatcher.wait(
|
|
339
|
+
outcome.action_id, ANSWERED_STATES.__contains__, self._timing.tool_wait_ms
|
|
340
|
+
)
|
|
341
|
+
if self._store.authorization_only:
|
|
342
|
+
self._fail_unknown_outcome(outcome.action_id)
|
|
343
|
+
result = self._store.status(
|
|
344
|
+
outcome.action_id, self._now, tool=str(operation), args=arguments
|
|
345
|
+
)
|
|
346
|
+
return wire.action(result)
|
|
347
|
+
|
|
348
|
+
return write
|
|
349
|
+
|
|
350
|
+
def _fail_unknown_outcome(self, action_id: str) -> None:
|
|
351
|
+
"""G1: a send with no usable answer ends the call as a proxy's 504 does (0008).
|
|
352
|
+
|
|
353
|
+
Raises `ToolError("gateway_timeout")` when the action's outcome is unknown. The
|
|
354
|
+
records keep the action OutcomeUnknown; the response holds no action state, so,
|
|
355
|
+
like every tool error, it is not logged as a response (I5).
|
|
356
|
+
"""
|
|
357
|
+
view = self._store.view(action_id)
|
|
358
|
+
action = view.action
|
|
359
|
+
if action.state is not _S.OUTCOME_UNKNOWN:
|
|
360
|
+
return
|
|
361
|
+
reason = next(e.reason for e in reversed(view.events) if e.kind is EventKind.TRANSITION)
|
|
362
|
+
raise ToolError(
|
|
363
|
+
"gateway_timeout",
|
|
364
|
+
f"{action.operation} for {action.intent_id}: no usable answer from the simulator"
|
|
365
|
+
f" ({reason})",
|
|
366
|
+
)
|
|
367
|
+
|
|
368
|
+
def _invalid(self, operation: Operation, arguments: Mapping[str, object], why: str) -> Json:
|
|
369
|
+
refusal = self._store.refuse_invalid(str(operation), dict(arguments), why, self._now)
|
|
370
|
+
return wire.refusal(refusal)
|
|
371
|
+
|
|
372
|
+
# Status ----------------------------------------------------------------------------------
|
|
373
|
+
|
|
374
|
+
async def _status(self, arguments: Mapping[str, object], call: Call) -> Json:
|
|
375
|
+
limit = WaitLimit(self._timing.max_wait_ms)
|
|
376
|
+
try:
|
|
377
|
+
args = ActionStatusArgs.model_validate(dict(arguments), context=limit)
|
|
378
|
+
except ValidationError as error:
|
|
379
|
+
raise ToolError("invalid_args", "; ".join(validation_messages(error))) from None
|
|
380
|
+
try:
|
|
381
|
+
self._store.view(args.action_id)
|
|
382
|
+
except UnknownAction:
|
|
383
|
+
raise ToolError("unknown_action", f"no action {args.action_id}") from None
|
|
384
|
+
await self._dispatcher.wait(args.action_id, FINAL_STATES.__contains__, args.wait_ms)
|
|
385
|
+
result: ActionResult = self._store.status(args.action_id, self._now, args=arguments)
|
|
386
|
+
return wire.action(result)
|
|
387
|
+
|
|
388
|
+
# The final report --------------------------------------------------------------------------
|
|
389
|
+
|
|
390
|
+
async def _report(self, arguments: Mapping[str, object], call: Call) -> Json:
|
|
391
|
+
if self._store.authorization_only:
|
|
392
|
+
return self._forward_report(arguments, call)
|
|
393
|
+
try:
|
|
394
|
+
report = parse_report(dict(arguments), self._intents)
|
|
395
|
+
except InvalidReport as invalid:
|
|
396
|
+
message = "; ".join(invalid.errors)
|
|
397
|
+
return wire.refusal(Refusal(RefusalReason.INVALID_ARGS, message=message))
|
|
398
|
+
claims = [
|
|
399
|
+
Claim(c.intent_id, ClaimStatus(str(c.status)), tuple(c.effect_ids), c.note)
|
|
400
|
+
for c in report.claims
|
|
401
|
+
]
|
|
402
|
+
outcome = self._store.submit_report(claims, self._now, worker=call.worker, args=arguments)
|
|
403
|
+
if isinstance(outcome, ReportAccepted):
|
|
404
|
+
self._reports.submit(
|
|
405
|
+
call.worker,
|
|
406
|
+
report.model_dump(mode="json"),
|
|
407
|
+
accepted_by="gateway",
|
|
408
|
+
message_seq=call.message_seq,
|
|
409
|
+
)
|
|
410
|
+
return wire.report(outcome)
|
|
411
|
+
|
|
412
|
+
def _forward_report(self, arguments: Mapping[str, object], call: Call) -> Json:
|
|
413
|
+
"""G1: hand the report to the report sink unchanged, and check nothing (0008).
|
|
414
|
+
|
|
415
|
+
The sink records every report with whether it is valid, and returns what breaks
|
|
416
|
+
the report schema; the agent is told that, as B0's sink tells it, so it can fix the
|
|
417
|
+
report and resubmit. G1 keeps no record of reports.
|
|
418
|
+
"""
|
|
419
|
+
errors = self._reports.submit(
|
|
420
|
+
call.worker, dict(arguments), accepted_by="gateway", message_seq=call.message_seq
|
|
421
|
+
)
|
|
422
|
+
if errors:
|
|
423
|
+
return wire.refusal(Refusal(RefusalReason.INVALID_ARGS, message="; ".join(errors)))
|
|
424
|
+
return wire.accepted()
|
fivefold/gateway/twin.py
ADDED
|
@@ -0,0 +1,199 @@
|
|
|
1
|
+
"""A store that runs every operation on two stores and compares them (0003, testing plan).
|
|
2
|
+
|
|
3
|
+
`TwinStore` checks a store against the in-memory store, the oracle. Every operation runs
|
|
4
|
+
on both. Both must return equal results, or raise the same kind of error with the same
|
|
5
|
+
message, and must hold equal records afterwards, down to the counters that number them.
|
|
6
|
+
Testing plan item 3 of record 0003 runs the gateway's Hypothesis machine this way against
|
|
7
|
+
the Postgres store. It belongs to the tests, not to a running gateway.
|
|
8
|
+
"""
|
|
9
|
+
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
from collections.abc import Mapping, Sequence
|
|
13
|
+
from typing import Any, cast
|
|
14
|
+
|
|
15
|
+
from fivefold.gateway.memory import MemoryStore
|
|
16
|
+
from fivefold.gateway.pg_store import PgStore
|
|
17
|
+
from fivefold.gateway.records import (
|
|
18
|
+
NO_ARGS,
|
|
19
|
+
ActionResult,
|
|
20
|
+
Answer,
|
|
21
|
+
ApprovalStatus,
|
|
22
|
+
Attempt,
|
|
23
|
+
BasisCheck,
|
|
24
|
+
CheckRecord,
|
|
25
|
+
CheckTicket,
|
|
26
|
+
Claim,
|
|
27
|
+
ProbeAnswer,
|
|
28
|
+
ReadRecord,
|
|
29
|
+
Refusal,
|
|
30
|
+
ReportAccepted,
|
|
31
|
+
Resolution,
|
|
32
|
+
Snapshot,
|
|
33
|
+
WriteCall,
|
|
34
|
+
)
|
|
35
|
+
from fivefold.gateway.state_machine import GatewaySettings
|
|
36
|
+
from fivefold.gateway.steps import ActionView
|
|
37
|
+
|
|
38
|
+
|
|
39
|
+
class StoreMismatch(AssertionError):
|
|
40
|
+
"""The two stores disagreed."""
|
|
41
|
+
|
|
42
|
+
|
|
43
|
+
class TwinStore:
|
|
44
|
+
"""The in-memory oracle and a Postgres store, run side by side."""
|
|
45
|
+
|
|
46
|
+
def __init__(self, oracle: MemoryStore, pg: PgStore) -> None:
|
|
47
|
+
self.oracle = oracle
|
|
48
|
+
self.pg = pg
|
|
49
|
+
|
|
50
|
+
def _both(self, name: str, *args: object, **kwargs: object) -> Any:
|
|
51
|
+
try:
|
|
52
|
+
expected = getattr(self.oracle, name)(*args, **kwargs)
|
|
53
|
+
except Exception as error:
|
|
54
|
+
try:
|
|
55
|
+
getattr(self.pg, name)(*args, **kwargs)
|
|
56
|
+
except Exception as other:
|
|
57
|
+
if type(other) is not type(error) or str(other) != str(error):
|
|
58
|
+
raise StoreMismatch(
|
|
59
|
+
f"{name}: memory raised {error!r}, Postgres raised {other!r}"
|
|
60
|
+
) from other
|
|
61
|
+
else:
|
|
62
|
+
raise StoreMismatch(f"{name}: memory raised {error!r}, Postgres did not") from error
|
|
63
|
+
self.compare()
|
|
64
|
+
raise
|
|
65
|
+
actual = getattr(self.pg, name)(*args, **kwargs)
|
|
66
|
+
if actual != expected:
|
|
67
|
+
raise StoreMismatch(f"{name}: Postgres gave {actual!r}, memory {expected!r}")
|
|
68
|
+
self.compare()
|
|
69
|
+
return expected
|
|
70
|
+
|
|
71
|
+
def compare(self) -> None:
|
|
72
|
+
"""Raise `StoreMismatch` unless both stores hold the same records."""
|
|
73
|
+
pg, oracle = self.pg.snapshot(), self.oracle.snapshot()
|
|
74
|
+
parts = ("intents", "actions", "grants", "attempts", "events", "escalations")
|
|
75
|
+
for part in (*parts, "closed_intents", "reports", "reads", "proposals"):
|
|
76
|
+
if getattr(pg, part) != getattr(oracle, part):
|
|
77
|
+
raise StoreMismatch(f"{part} differ")
|
|
78
|
+
if pg.tool_calls != oracle.tool_calls:
|
|
79
|
+
raise StoreMismatch("tool calls differ")
|
|
80
|
+
if pg.run_closed != oracle.run_closed:
|
|
81
|
+
raise StoreMismatch("run_closed differs")
|
|
82
|
+
last_seq = oracle.events[-1].seq if oracle.events else 0
|
|
83
|
+
expected = (
|
|
84
|
+
len(oracle.actions),
|
|
85
|
+
last_seq,
|
|
86
|
+
len(oracle.tool_calls),
|
|
87
|
+
len(oracle.reads),
|
|
88
|
+
len(oracle.proposals),
|
|
89
|
+
)
|
|
90
|
+
if self.pg.counters() != expected:
|
|
91
|
+
raise StoreMismatch(f"counters {self.pg.counters()} differ from {expected}")
|
|
92
|
+
|
|
93
|
+
@property
|
|
94
|
+
def settings(self) -> GatewaySettings:
|
|
95
|
+
return self.oracle.settings
|
|
96
|
+
|
|
97
|
+
def snapshot(self) -> Snapshot:
|
|
98
|
+
return self.oracle.snapshot()
|
|
99
|
+
|
|
100
|
+
def view(self, action_id: str) -> ActionView:
|
|
101
|
+
expected = self.oracle.view(action_id)
|
|
102
|
+
if self.pg.view(action_id) != expected:
|
|
103
|
+
raise StoreMismatch(f"views of {action_id} differ")
|
|
104
|
+
return expected
|
|
105
|
+
|
|
106
|
+
def begin_check(self, action_id: str) -> CheckTicket:
|
|
107
|
+
return cast(CheckTicket, self._both("begin_check", action_id))
|
|
108
|
+
|
|
109
|
+
def record_read(
|
|
110
|
+
self, key: str, version: int, data: Mapping[str, object], vt: int
|
|
111
|
+
) -> ReadRecord:
|
|
112
|
+
return cast(ReadRecord, self._both("record_read", key, version, data, vt))
|
|
113
|
+
|
|
114
|
+
def read_of(self, key: str, version: int) -> ReadRecord | None:
|
|
115
|
+
expected = self.oracle.read_of(key, version)
|
|
116
|
+
if self.pg.read_of(key, version) != expected:
|
|
117
|
+
raise StoreMismatch(f"reads of {key} at {version} differ")
|
|
118
|
+
return expected
|
|
119
|
+
|
|
120
|
+
def propose(
|
|
121
|
+
self, call: WriteCall, vt: int, *, args: Mapping[str, object] = NO_ARGS
|
|
122
|
+
) -> ActionResult | Refusal:
|
|
123
|
+
return cast(ActionResult | Refusal, self._both("propose", call, vt, args=args))
|
|
124
|
+
|
|
125
|
+
def refuse_invalid(
|
|
126
|
+
self, operation: str, args: Mapping[str, object], message: str, vt: int
|
|
127
|
+
) -> Refusal:
|
|
128
|
+
return cast(Refusal, self._both("refuse_invalid", operation, args, message, vt))
|
|
129
|
+
|
|
130
|
+
def status(
|
|
131
|
+
self,
|
|
132
|
+
action_id: str,
|
|
133
|
+
vt: int,
|
|
134
|
+
*,
|
|
135
|
+
tool: str = "get_action_status",
|
|
136
|
+
args: Mapping[str, object] = NO_ARGS,
|
|
137
|
+
) -> ActionResult:
|
|
138
|
+
return cast(ActionResult, self._both("status", action_id, vt, tool=tool, args=args))
|
|
139
|
+
|
|
140
|
+
def submit_report(
|
|
141
|
+
self,
|
|
142
|
+
claims: Sequence[Claim],
|
|
143
|
+
vt: int,
|
|
144
|
+
*,
|
|
145
|
+
worker: str,
|
|
146
|
+
args: Mapping[str, object] = NO_ARGS,
|
|
147
|
+
) -> ReportAccepted | Refusal:
|
|
148
|
+
outcome = self._both("submit_report", claims, vt, worker=worker, args=args)
|
|
149
|
+
return cast(ReportAccepted | Refusal, outcome)
|
|
150
|
+
|
|
151
|
+
def file_approval(
|
|
152
|
+
self,
|
|
153
|
+
action_id: str,
|
|
154
|
+
basis: BasisCheck | None,
|
|
155
|
+
approval_id: str | None,
|
|
156
|
+
vt: int,
|
|
157
|
+
*,
|
|
158
|
+
seen_seq: int,
|
|
159
|
+
) -> None:
|
|
160
|
+
self._both("file_approval", action_id, basis, approval_id, vt, seen_seq=seen_seq)
|
|
161
|
+
|
|
162
|
+
def poll_approval(
|
|
163
|
+
self,
|
|
164
|
+
action_id: str,
|
|
165
|
+
approval: ApprovalStatus,
|
|
166
|
+
basis: BasisCheck | None,
|
|
167
|
+
vt: int,
|
|
168
|
+
*,
|
|
169
|
+
seen_seq: int,
|
|
170
|
+
) -> None:
|
|
171
|
+
self._both("poll_approval", action_id, approval, basis, vt, seen_seq=seen_seq)
|
|
172
|
+
|
|
173
|
+
def time_out_approval(
|
|
174
|
+
self, action_id: str, approval: ApprovalStatus, vt: int, *, seen_seq: int
|
|
175
|
+
) -> None:
|
|
176
|
+
self._both("time_out_approval", action_id, approval, vt, seen_seq=seen_seq)
|
|
177
|
+
|
|
178
|
+
def dispatch(self, action_id: str, check: CheckRecord, vt: int) -> Attempt | None:
|
|
179
|
+
return cast(Attempt | None, self._both("dispatch", action_id, check, vt))
|
|
180
|
+
|
|
181
|
+
def retry(self, action_id: str, check: CheckRecord, vt: int) -> Attempt | None:
|
|
182
|
+
return cast(Attempt | None, self._both("retry", action_id, check, vt))
|
|
183
|
+
|
|
184
|
+
def answer(self, action_id: str, attempt_no: int, answer: Answer, vt: int) -> None:
|
|
185
|
+
self._both("answer", action_id, attempt_no, answer, vt)
|
|
186
|
+
|
|
187
|
+
def probe(self, action_id: str, result: ProbeAnswer, vt: int) -> None:
|
|
188
|
+
self._both("probe", action_id, result, vt)
|
|
189
|
+
|
|
190
|
+
def attest(
|
|
191
|
+
self, action_id: str, resolution: Resolution, effect_id: str | None, actor: str, vt: int
|
|
192
|
+
) -> None:
|
|
193
|
+
self._both("attest", action_id, resolution, effect_id, actor, vt)
|
|
194
|
+
|
|
195
|
+
def restart(self, vt: int) -> None:
|
|
196
|
+
self._both("restart", vt)
|
|
197
|
+
|
|
198
|
+
def close_run(self, vt: int) -> None:
|
|
199
|
+
self._both("close_run", vt)
|