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.
Files changed (128) hide show
  1. fivefold/__init__.py +4 -0
  2. fivefold/_data/db/bootstrap.sql +26 -0
  3. fivefold/_data/db/migrations/0001_schemas.sql +67 -0
  4. fivefold/_data/db/migrations/0002_gateway.sql +224 -0
  5. fivefold/_data/db/migrations/0003_gateway_record_0010.sql +91 -0
  6. fivefold/_data/db/migrations/0004_harness.sql +141 -0
  7. fivefold/_data/db/migrations/0005_sim.sql +679 -0
  8. fivefold/_data/db/migrations/0006_gateway_reads.sql +66 -0
  9. fivefold/_data/db/migrations/0007_eval.sql +33 -0
  10. fivefold/_data/db/migrations/0008_run_stop.sql +18 -0
  11. fivefold/_data/db/migrations/0009_message_copies.sql +69 -0
  12. fivefold/_data/db/migrations/0010_gateway_g1_check.sql +14 -0
  13. fivefold/_data/db/migrations/0011_model_calls.sql +37 -0
  14. fivefold/_data/db/migrations/0012_recovery_latency.sql +23 -0
  15. fivefold/_data/db/migrations/0013_split_topology.sql +33 -0
  16. fivefold/_data/db/migrations/0014_tool_call_args.sql +20 -0
  17. fivefold/_data/db/registry/0001_registry.sql +31 -0
  18. fivefold/_data/faults/expected.yaml +406 -0
  19. fivefold/_data/scenarios/dev/dev-001-single-po.yaml +45 -0
  20. fivefold/_data/scenarios/dev/dev-002-human-approval.yaml +47 -0
  21. fivefold/agents/__init__.py +7 -0
  22. fivefold/agents/branch.py +187 -0
  23. fivefold/agents/checkpoint.py +77 -0
  24. fivefold/agents/connection.py +153 -0
  25. fivefold/agents/live.py +492 -0
  26. fivefold/agents/policy.py +426 -0
  27. fivefold/agents/remote.py +333 -0
  28. fivefold/agents/replay.py +170 -0
  29. fivefold/agents/scripted.py +122 -0
  30. fivefold/agents/tools.py +229 -0
  31. fivefold/agents/worker.py +164 -0
  32. fivefold/domain/__init__.py +5 -0
  33. fivefold/domain/api.py +517 -0
  34. fivefold/domain/authority.py +149 -0
  35. fivefold/domain/contracts.py +80 -0
  36. fivefold/domain/identity.py +113 -0
  37. fivefold/domain/prices.py +178 -0
  38. fivefold/domain/report.py +92 -0
  39. fivefold/domain/rules.py +346 -0
  40. fivefold/domain/scenario.py +524 -0
  41. fivefold/evaluator/__init__.py +155 -0
  42. fivefold/evaluator/__main__.py +127 -0
  43. fivefold/evaluator/authorization.py +146 -0
  44. fivefold/evaluator/checks.py +331 -0
  45. fivefold/evaluator/evaluate.py +109 -0
  46. fivefold/evaluator/evidence.py +392 -0
  47. fivefold/evaluator/freshness.py +136 -0
  48. fivefold/evaluator/liveness.py +236 -0
  49. fivefold/evaluator/load.py +354 -0
  50. fivefold/evaluator/metrics.py +95 -0
  51. fivefold/evaluator/records.py +452 -0
  52. fivefold/evaluator/recovery.py +209 -0
  53. fivefold/evaluator/report.py +1096 -0
  54. fivefold/evaluator/result.py +344 -0
  55. fivefold/evaluator/store.py +83 -0
  56. fivefold/faults/__init__.py +5 -0
  57. fivefold/faults/catalog.py +278 -0
  58. fivefold/faults/plan.py +538 -0
  59. fivefold/gateway/__init__.py +6 -0
  60. fivefold/gateway/admin.py +179 -0
  61. fivefold/gateway/admin_api.py +398 -0
  62. fivefold/gateway/codec.py +372 -0
  63. fivefold/gateway/destination.py +64 -0
  64. fivefold/gateway/dispatcher.py +379 -0
  65. fivefold/gateway/freshness.py +83 -0
  66. fivefold/gateway/invariants.py +761 -0
  67. fivefold/gateway/memory.py +277 -0
  68. fivefold/gateway/pg_store.py +657 -0
  69. fivefold/gateway/records.py +592 -0
  70. fivefold/gateway/server.py +102 -0
  71. fivefold/gateway/sim_client.py +295 -0
  72. fivefold/gateway/state_machine.py +376 -0
  73. fivefold/gateway/steps.py +897 -0
  74. fivefold/gateway/store.py +635 -0
  75. fivefold/gateway/tools.py +424 -0
  76. fivefold/gateway/twin.py +199 -0
  77. fivefold/gateway/wire.py +138 -0
  78. fivefold/harness/__init__.py +6 -0
  79. fivefold/harness/actors.py +230 -0
  80. fivefold/harness/cells.py +303 -0
  81. fivefold/harness/clock.py +209 -0
  82. fivefold/harness/demo.py +397 -0
  83. fivefold/harness/fault_effects.py +122 -0
  84. fivefold/harness/live_options.py +159 -0
  85. fivefold/harness/log.py +540 -0
  86. fivefold/harness/mcp_link.py +409 -0
  87. fivefold/harness/migrations.py +520 -0
  88. fivefold/harness/models.py +368 -0
  89. fivefold/harness/registry.py +105 -0
  90. fivefold/harness/reports.py +100 -0
  91. fivefold/harness/rng.py +57 -0
  92. fivefold/harness/run.py +881 -0
  93. fivefold/harness/scheduler.py +441 -0
  94. fivefold/harness/sim_points.py +215 -0
  95. fivefold/harness/split/__init__.py +34 -0
  96. fivefold/harness/split/__main__.py +275 -0
  97. fivefold/harness/split/credentials.py +74 -0
  98. fivefold/harness/split/faults.py +75 -0
  99. fivefold/harness/split/gateway.py +769 -0
  100. fivefold/harness/split/hops.py +291 -0
  101. fivefold/harness/split/lifecycle.py +322 -0
  102. fivefold/harness/split/rundir.py +152 -0
  103. fivefold/harness/split/service.py +157 -0
  104. fivefold/harness/split/simulator.py +432 -0
  105. fivefold/harness/study.py +643 -0
  106. fivefold/harness/transport.py +533 -0
  107. fivefold/paths.py +24 -0
  108. fivefold/py.typed +0 -0
  109. fivefold/recorder/__init__.py +18 -0
  110. fivefold/recorder/__main__.py +308 -0
  111. fivefold/recorder/cassette.py +322 -0
  112. fivefold/recorder/playback.py +316 -0
  113. fivefold/recorder/recording.py +133 -0
  114. fivefold/sim/__init__.py +37 -0
  115. fivefold/sim/config.py +52 -0
  116. fivefold/sim/endpoint.py +176 -0
  117. fivefold/sim/ledger.py +583 -0
  118. fivefold/sim/service.py +834 -0
  119. fivefold/viewer/__init__.py +14 -0
  120. fivefold/viewer/__main__.py +75 -0
  121. fivefold/viewer/app.py +122 -0
  122. fivefold/viewer/records.py +108 -0
  123. fivefold/viewer/source.py +196 -0
  124. fivefold/viewer/timeline.py +61 -0
  125. fivefold-0.1.0.dist-info/METADATA +169 -0
  126. fivefold-0.1.0.dist-info/RECORD +128 -0
  127. fivefold-0.1.0.dist-info/WHEEL +4 -0
  128. fivefold-0.1.0.dist-info/licenses/LICENSE +202 -0
@@ -0,0 +1,229 @@
1
+ """The agent's tools: the gateway's over MCP in G modes, the simulator's in B0 (0008).
2
+
3
+ Every tool returns the destination's answer to the model as JSON text, successes and
4
+ refusals alike. A tool raises only on a transport failure or a server error, so that
5
+ LangGraph's retry policy applies, as it would to an HTTP client (0008):
6
+
7
+ - no answer within the call's timeout raises `TransportTimeout`, which is not an
8
+ `OSError`, so the default retry predicate retries it;
9
+ - in G modes, a connection to the gateway that closes while a call waits raises
10
+ `ConnectionError`, which the default predicate also retries; the next call opens a new
11
+ connection (`fivefold.agents.connection`);
12
+ - the gateway's `gateway_timeout` tool error, its 504, raises `ServerError`.
13
+
14
+ The timeout of a call is the tool's declared server-side wait plus T (0005, 0008): T for
15
+ reads and simulator calls, `tool_wait_ms` plus T for gateway writes, and `wait_ms` plus T
16
+ for calls that wait. Timeouts run on the scheduler's virtual clock.
17
+
18
+ A status tool's wait is at most the run's `max_wait_ms` (0005). B0's
19
+ `get_approval_status` refuses a longer wait before anything is sent, as it refuses any
20
+ other invalid argument: the request model raises pydantic's `ValidationError`, which the
21
+ tool node hands back to the model (0008). In G modes the gateway refuses it; the
22
+ agent's own timeout for a gateway status call counts at most `max_wait_ms`, so the call
23
+ ends even when the gateway does not answer.
24
+
25
+ Checked in langchain-core 1.8.0: `StructuredTool.from_function(coroutine=, name=,
26
+ description=, args_schema=)` takes a Pydantic model or a JSON Schema dict
27
+ (`ArgsSchema`, `langchain_core/tools/base.py`), and passes the tool call's arguments to
28
+ the coroutine as keyword arguments.
29
+ """
30
+
31
+ from __future__ import annotations
32
+
33
+ import json
34
+ from collections.abc import Awaitable, Callable, Mapping
35
+ from dataclasses import dataclass
36
+ from typing import Any, Protocol
37
+
38
+ import mcp_types as types
39
+ from langchain_core.tools import BaseTool, StructuredTool
40
+ from pydantic import BaseModel
41
+
42
+ from fivefold.domain.api import (
43
+ GetApprovalStatus,
44
+ GetBudget,
45
+ GetInventory,
46
+ GetOrderStatus,
47
+ GetQuote,
48
+ GetReservationStatus,
49
+ ListSuppliers,
50
+ RequestApproval,
51
+ ReserveInventory,
52
+ SubmitPurchaseOrder,
53
+ WaitLimit,
54
+ )
55
+ from fivefold.domain.report import FinalReport
56
+ from fivefold.harness.scheduler import Scheduler
57
+ from fivefold.harness.transport import Calls
58
+
59
+ GATEWAY_WRITES = frozenset({"submit_purchase_order", "reserve_inventory"})
60
+ SIMULATOR = "simulator"
61
+ REPORT_SINK = "report_sink"
62
+
63
+
64
+ class ServerError(Exception):
65
+ """The destination answered with a server error; the framework's retry applies."""
66
+
67
+
68
+ @dataclass(frozen=True)
69
+ class Timeouts:
70
+ """The parts of a call's timeout, in virtual ms (0005)."""
71
+
72
+ t_ms: int
73
+ """T: the destination's dispatch timeout."""
74
+ tool_wait_ms: int
75
+ """How long a gateway write waits before it answers."""
76
+ max_wait_ms: int = 60_000
77
+ """The longest `wait_ms` a status tool accepts: the scenario's `max_wait_ms`."""
78
+
79
+
80
+ # G modes: the gateway's tools over MCP ------------------------------------------------------
81
+
82
+
83
+ class ToolCaller(Protocol):
84
+ """An agent worker's MCP connection to the gateway, as its tools use it: in-process
85
+ (`fivefold.agents.connection`) or over streamable HTTP (`fivefold.agents.remote`)."""
86
+
87
+ async def call_tool(
88
+ self, name: str, arguments: dict[str, Any], timeout_ms: int
89
+ ) -> types.CallToolResult:
90
+ """Call a tool, waiting at most `timeout_ms` for its result."""
91
+ ...
92
+
93
+
94
+ def gateway_tools(
95
+ connection: ToolCaller,
96
+ listed: types.ListToolsResult,
97
+ timeouts: Timeouts,
98
+ ) -> list[BaseTool]:
99
+ """The gateway's tools, as `tools/list` described them."""
100
+ return [_gateway_tool(connection, tool, timeouts) for tool in listed.tools]
101
+
102
+
103
+ def _gateway_tool(connection: ToolCaller, tool: types.Tool, timeouts: Timeouts) -> BaseTool:
104
+ name = tool.name
105
+
106
+ async def call(**arguments: Any) -> str:
107
+ if name in GATEWAY_WRITES:
108
+ timeout = timeouts.tool_wait_ms + timeouts.t_ms
109
+ else:
110
+ wait_ms = int(arguments.get("wait_ms", 0) or 0)
111
+ timeout = min(wait_ms, timeouts.max_wait_ms) + timeouts.t_ms
112
+ result = await connection.call_tool(name, arguments, timeout)
113
+ text = "".join(c.text for c in result.content if isinstance(c, types.TextContent))
114
+ if result.is_error and _error_code(text) == "gateway_timeout":
115
+ raise ServerError(f"{name}: {text}")
116
+ return text
117
+
118
+ return StructuredTool.from_function(
119
+ coroutine=call,
120
+ name=name,
121
+ description=tool.description or name,
122
+ args_schema=dict(tool.input_schema),
123
+ )
124
+
125
+
126
+ def _error_code(text: str) -> str | None:
127
+ try:
128
+ body = json.loads(text)
129
+ except json.JSONDecodeError:
130
+ return None
131
+ return str(body.get("error")) if isinstance(body, dict) else None
132
+
133
+
134
+ # B0: the simulator's API and the report sink ------------------------------------------------
135
+
136
+
137
+ @dataclass(frozen=True)
138
+ class _ApiTool:
139
+ name: str
140
+ description: str
141
+ model: type[BaseModel]
142
+ receiver: str = SIMULATOR
143
+
144
+
145
+ BASELINE_TOOLS: tuple[_ApiTool, ...] = (
146
+ _ApiTool("get_quote", "Read a supplier's quote for a sku.", GetQuote),
147
+ _ApiTool("list_suppliers", "Read the supplier directory.", ListSuppliers),
148
+ _ApiTool("get_budget", "Read a cost center's budget.", GetBudget),
149
+ _ApiTool("get_inventory", "Read a sku's stock in a warehouse.", GetInventory),
150
+ _ApiTool("request_approval", "Request approval for an order.", RequestApproval),
151
+ _ApiTool(
152
+ "get_approval_status",
153
+ "An approval's status. Waits up to wait_ms for a decision.",
154
+ GetApprovalStatus,
155
+ ),
156
+ _ApiTool("submit_purchase_order", "Place a purchase order.", SubmitPurchaseOrder),
157
+ _ApiTool("reserve_inventory", "Reserve stock.", ReserveInventory),
158
+ _ApiTool(
159
+ "submit_final_report",
160
+ "Report, for every intent of the task, whether it is done, not done or unknown.",
161
+ FinalReport,
162
+ REPORT_SINK,
163
+ ),
164
+ )
165
+ """B0's tools at every contract level (0008)."""
166
+
167
+ STATUS_TOOLS: tuple[_ApiTool, ...] = (
168
+ _ApiTool("get_order_status", "Which purchase orders exist for an intent.", GetOrderStatus),
169
+ _ApiTool(
170
+ "get_reservation_status", "Which reservations exist for an intent.", GetReservationStatus
171
+ ),
172
+ )
173
+ """B0's status tools, at C1 only (0008)."""
174
+
175
+
176
+ def baseline_tools(
177
+ transport: Calls,
178
+ scheduler: Scheduler,
179
+ timeouts: Timeouts,
180
+ *,
181
+ worker: str,
182
+ status: bool,
183
+ ) -> list[BaseTool]:
184
+ """B0's tools for one agent worker; `status` adds C1's status tools."""
185
+ tools = BASELINE_TOOLS + (STATUS_TOOLS if status else ())
186
+ return [_baseline_tool(transport, scheduler, timeouts, spec, worker) for spec in tools]
187
+
188
+
189
+ def _baseline_tool(
190
+ transport: Calls, scheduler: Scheduler, timeouts: Timeouts, spec: _ApiTool, worker: str
191
+ ) -> BaseTool:
192
+ async def call(**arguments: Any) -> str:
193
+ limit = WaitLimit(timeouts.max_wait_ms)
194
+ request = spec.model.model_validate(_plain(arguments), context=limit)
195
+ body = request.model_dump(mode="json")
196
+ wait_ms = int(body.get("wait_ms", 0) or 0)
197
+ reply = await transport.call(
198
+ hop="agent_sim",
199
+ sender=worker,
200
+ receiver=spec.receiver,
201
+ api=spec.name,
202
+ body=body,
203
+ timeout_ms=wait_ms + timeouts.t_ms,
204
+ intent_id=_text(body.get("intent_id")),
205
+ idempotency_key=_text(body.get("idempotency_key")),
206
+ )
207
+ return json.dumps(reply.body, sort_keys=True)
208
+
209
+ return StructuredTool.from_function(
210
+ coroutine=call, name=spec.name, description=spec.description, args_schema=spec.model
211
+ )
212
+
213
+
214
+ def _plain(value: object) -> object:
215
+ """Arguments as plain data: models a tool layer built become dicts again."""
216
+ if isinstance(value, BaseModel):
217
+ return value.model_dump(mode="json")
218
+ if isinstance(value, Mapping):
219
+ return {str(k): _plain(v) for k, v in value.items()}
220
+ if isinstance(value, list | tuple):
221
+ return [_plain(v) for v in value]
222
+ return value
223
+
224
+
225
+ def _text(value: object) -> str | None:
226
+ return value if isinstance(value, str) else None
227
+
228
+
229
+ ToolFactory = Callable[[], Awaitable[list[BaseTool]]]
@@ -0,0 +1,164 @@
1
+ """An agent worker: the shared LangGraph agent of record 0008, run on the scheduler.
2
+
3
+ The graph has a model node and the prebuilt `ToolNode` with its default error handling,
4
+ and the tool node has a `RetryPolicy` with the library's defaults (0008). The model node
5
+ calls the model with the worker's tools bound to it, so every adapter is asked the same
6
+ requests, with the tools' schemas, as a live model needs them. Each worker has its own
7
+ checkpoint thread, named after the worker, and its own step and token budgets (0009). A
8
+ worker that starts again after a crash resumes from its last checkpoint, so LangGraph
9
+ re-runs the node that was interrupted (0006, F11).
10
+
11
+ The budgets are counted from the conversation, which the checkpoint keeps, so they hold
12
+ across a crash and a replay counts them the same way: the steps are the model's replies,
13
+ and the tokens are their input and output tokens, as each reply's usage reports them. A
14
+ reply that reports no usage counts none, so the scripted adapter, and the replay of a
15
+ scripted run, never use up the token budget. Before each model call, a worker whose steps
16
+ or tokens already reached its budget makes no further call: it ends as `budget`, as it
17
+ does when the live adapter's spend cap refuses a call (`fivefold.agents.live`).
18
+
19
+ A worker ends in one of three ways, which the harness records: its graph finished, a
20
+ budget ran out, or the graph raised, for example when the tool node's retries ran out
21
+ (0008). The run does not stop for a worker's error.
22
+
23
+ Checked in langgraph 1.2.22 and langgraph-prebuilt 1.1.2: `StateGraph(MessagesState)`,
24
+ `add_node(name, node, retry_policy=RetryPolicy())`, `add_conditional_edges(name,
25
+ tools_condition)`, `compile(checkpointer=)`, and `ainvoke(None, config)` to resume a
26
+ thread from its last checkpoint; the config's `recursion_limit` bounds the steps. Checked
27
+ in langchain-core 1.8.0 (`language_models/chat_models.py`): `BaseChatModel.bind_tools
28
+ (tools, *, tool_choice=None, **kwargs)` returns a `Runnable` of the model with the tools
29
+ bound; `AIMessage.usage_metadata` is a `UsageMetadata` or None (`messages/ai.py`).
30
+ """
31
+
32
+ from __future__ import annotations
33
+
34
+ import asyncio
35
+ from collections.abc import Callable, Sequence
36
+ from dataclasses import dataclass
37
+ from enum import StrEnum
38
+ from typing import Any, Final
39
+
40
+ from langchain_core.language_models.chat_models import BaseChatModel
41
+ from langchain_core.messages import AIMessage, BaseMessage, HumanMessage
42
+ from langchain_core.runnables import RunnableConfig
43
+ from langchain_core.tools import BaseTool
44
+ from langgraph.checkpoint.base import BaseCheckpointSaver
45
+ from langgraph.graph import START, MessagesState, StateGraph
46
+ from langgraph.prebuilt import ToolNode, tools_condition
47
+ from langgraph.types import RetryPolicy
48
+
49
+ BUDGET_TEXT: Final = "Step budget used up."
50
+ TOKEN_BUDGET_TEXT: Final = "Token budget used up."
51
+ SPEND_CAP_TEXT: Final = "Spend cap reached."
52
+ BUDGET_TEXTS: Final = (BUDGET_TEXT, TOKEN_BUDGET_TEXT, SPEND_CAP_TEXT)
53
+ """The last message of a worker that ended as `budget`: its steps or tokens ran out, or
54
+ the live adapter's spend cap refused its call."""
55
+
56
+ CallLog = Callable[[], Callable[[AIMessage], None]]
57
+ """The harness's model-call log: called as a model call starts, it returns what to call
58
+ with the call's reply once the model answers."""
59
+
60
+
61
+ class WorkerEnd(StrEnum):
62
+ """How an agent worker ended."""
63
+
64
+ FINISHED = "finished"
65
+ BUDGET = "budget"
66
+ ERROR = "error"
67
+
68
+
69
+ @dataclass(frozen=True)
70
+ class WorkerSpec:
71
+ """One agent worker: its name, which is also its checkpoint thread, and its budgets."""
72
+
73
+ name: str
74
+ task: str
75
+ max_steps: int
76
+ max_tokens: int | None = None
77
+ """None for no token budget."""
78
+
79
+
80
+ def budget_end(message: BaseMessage) -> str | None:
81
+ """The budget that `message` says ran out, if it is the last message of a worker that
82
+ ended as `budget`."""
83
+ if isinstance(message, AIMessage) and not message.tool_calls:
84
+ content = message.content
85
+ if isinstance(content, str) and content in BUDGET_TEXTS:
86
+ return content
87
+ return None
88
+
89
+
90
+ def tokens_used(messages: Sequence[BaseMessage]) -> int:
91
+ """The input and output tokens of the model's replies in `messages`, as their usage
92
+ reports them; a reply that reports none counts none."""
93
+ used = 0
94
+ for message in messages:
95
+ if isinstance(message, AIMessage) and message.usage_metadata is not None:
96
+ used += message.usage_metadata["input_tokens"] + message.usage_metadata["output_tokens"]
97
+ return used
98
+
99
+
100
+ def build_graph(
101
+ model: BaseChatModel,
102
+ tools: Sequence[BaseTool],
103
+ checkpointer: BaseCheckpointSaver[Any],
104
+ *,
105
+ max_steps: int,
106
+ max_tokens: int | None = None,
107
+ on_step: Callable[[int], None] | None = None,
108
+ on_call: CallLog | None = None,
109
+ ) -> Any:
110
+ """The agent's graph: a model node, with the tools bound to the model, and the
111
+ prebuilt tool node, with retries.
112
+
113
+ `on_step` is called with the step's number each time the model finishes a step: the
114
+ fault point `agent.step` (0006). A refused call is no step. `on_call` logs each model
115
+ call (`CallLog`).
116
+ """
117
+ bound = model.bind_tools(list(tools))
118
+
119
+ async def call_model(state: MessagesState) -> dict[str, list[Any]]:
120
+ messages = state["messages"]
121
+ steps = sum(1 for message in messages if isinstance(message, AIMessage))
122
+ if steps >= max_steps:
123
+ return {"messages": [AIMessage(content=BUDGET_TEXT)]}
124
+ if max_tokens is not None and tokens_used(messages) >= max_tokens:
125
+ return {"messages": [AIMessage(content=TOKEN_BUDGET_TEXT)]}
126
+ answered = on_call() if on_call is not None else None
127
+ reply = await bound.ainvoke(messages)
128
+ if answered is not None:
129
+ answered(reply)
130
+ if on_step is not None and budget_end(reply) is None:
131
+ on_step(steps + 1)
132
+ return {"messages": [reply]}
133
+
134
+ graph = StateGraph(MessagesState)
135
+ graph.add_node("model", call_model)
136
+ graph.add_node("tools", ToolNode(list(tools)), retry_policy=RetryPolicy())
137
+ graph.add_edge(START, "model")
138
+ graph.add_conditional_edges("model", tools_condition)
139
+ graph.add_edge("tools", "model")
140
+ return graph.compile(checkpointer=checkpointer)
141
+
142
+
143
+ async def run_worker(graph: Any, spec: WorkerSpec, *, resume: bool) -> tuple[WorkerEnd, str]:
144
+ """Run the worker's graph to its end; resume from the checkpoint after a crash.
145
+
146
+ Returns how it ended and a short description. Cancellation, as a crash causes,
147
+ propagates: the harness restarts the worker.
148
+ """
149
+ config: RunnableConfig = {
150
+ "configurable": {"thread_id": spec.name},
151
+ "recursion_limit": 2 * spec.max_steps + 4,
152
+ }
153
+ start = None if resume else {"messages": [HumanMessage(spec.task)]}
154
+ try:
155
+ final = await graph.ainvoke(start, config)
156
+ except asyncio.CancelledError:
157
+ raise
158
+ except Exception as error:
159
+ return WorkerEnd.ERROR, f"{type(error).__name__}: {error}"
160
+ last = final["messages"][-1]
161
+ budget = budget_end(last)
162
+ if budget is not None:
163
+ return WorkerEnd.BUDGET, budget
164
+ return WorkerEnd.FINISHED, str(last.content)
@@ -0,0 +1,5 @@
1
+ """Shared domain definitions: ids, operations and the dependency rules (0001, 0004).
2
+
3
+ The gateway, the simulator and the evaluator all use this package. It imports none of
4
+ them, so the rules each one enforces are the same rules.
5
+ """