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,187 @@
|
|
|
1
|
+
"""The branch adapter (0009, Playback and branching): replay a parent run's first K model
|
|
2
|
+
calls from its cassette, then hand every later call to another model.
|
|
3
|
+
|
|
4
|
+
An experimental branch re-executes the run a cassette was recorded from, but only its
|
|
5
|
+
first K model calls come from the cassette. K is the branch point. Model calls are the
|
|
6
|
+
only points where the model can switch, so K counts them: the run's calls across its
|
|
7
|
+
workers, in the order they are answered, as the cassette and `harness.model_call` number
|
|
8
|
+
them.
|
|
9
|
+
|
|
10
|
+
All of a branch run's models share one `BranchPlayer`. Each call first takes `think_ms`
|
|
11
|
+
of virtual time, once, as with every adapter (0009). The adapter then decides where the
|
|
12
|
+
call goes, at that moment rather than when the call starts: calls are numbered in the
|
|
13
|
+
order they are answered, and two workers can be thinking at once.
|
|
14
|
+
|
|
15
|
+
- While fewer than K calls have been answered, the call is one of the parent's. It is
|
|
16
|
+
hashed as the parent's recorder hashed it, with the parent's model, and answered with
|
|
17
|
+
the parent's recorded response, under the replay's checks (`fivefold.agents.replay`):
|
|
18
|
+
the same worker and the same request hash, in order. A request that differs fails the
|
|
19
|
+
call with `ReplayError`, naming the call's number and both hashes, and so does every
|
|
20
|
+
later call.
|
|
21
|
+
- Once K calls have been answered, every later call goes to the next model: the scripted
|
|
22
|
+
model or the live adapter, built to take no `think_ms` of its own.
|
|
23
|
+
|
|
24
|
+
`BranchPlayer.finish`, once the run's agents are done, raises the first failure, or a
|
|
25
|
+
`ReplayError` if the run made fewer than K calls: the run fails, as a replay does. A run
|
|
26
|
+
that asks for more calls than the parent's cassette holds is no failure here: with K at the
|
|
27
|
+
cassette's length, the next model answers them.
|
|
28
|
+
|
|
29
|
+
The scripted model can continue only a conversation it could have made itself: it checks
|
|
30
|
+
that each tool result answers its own call ids (`fivefold.agents.scripted`). So a branch to
|
|
31
|
+
the scripted model from a parent whose replies came from another model, such as a live one
|
|
32
|
+
with random tool call ids, ends its worker with `ScriptError` at the first call after the
|
|
33
|
+
branch point, unless K is 0.
|
|
34
|
+
|
|
35
|
+
Checked in langchain-core 1.8.0 (`language_models/chat_models.py`): a `BaseChatModel`
|
|
36
|
+
subclass implements `_generate`, `_agenerate` and `_llm_type`; `ainvoke(input, config=None,
|
|
37
|
+
*, stop=None, **kwargs)` passes `stop` and the other arguments on to `_agenerate`; one with no
|
|
38
|
+
`_astream` always answers through `_agenerate`; `bind_tools(tools, *, tool_choice=None,
|
|
39
|
+
**kwargs)` returns a `Runnable` of the model with the tools bound.
|
|
40
|
+
"""
|
|
41
|
+
|
|
42
|
+
from __future__ import annotations
|
|
43
|
+
|
|
44
|
+
from collections.abc import Awaitable, Callable, Sequence
|
|
45
|
+
from typing import Any
|
|
46
|
+
|
|
47
|
+
from langchain_core.language_models import LanguageModelInput
|
|
48
|
+
from langchain_core.language_models.chat_models import BaseChatModel
|
|
49
|
+
from langchain_core.messages import AIMessage, BaseMessage
|
|
50
|
+
from langchain_core.outputs import ChatGeneration, ChatResult
|
|
51
|
+
from langchain_core.runnables import Runnable
|
|
52
|
+
from pydantic import JsonValue, PrivateAttr
|
|
53
|
+
|
|
54
|
+
from fivefold.agents.replay import CassettePlayer, ReplayError
|
|
55
|
+
from fivefold.recorder.cassette import (
|
|
56
|
+
Cassette,
|
|
57
|
+
Tool,
|
|
58
|
+
plain_object,
|
|
59
|
+
request_hash,
|
|
60
|
+
request_params,
|
|
61
|
+
tool_schemas,
|
|
62
|
+
)
|
|
63
|
+
|
|
64
|
+
Think = Callable[[], Awaitable[None]]
|
|
65
|
+
"""Takes `think_ms` of virtual time."""
|
|
66
|
+
|
|
67
|
+
|
|
68
|
+
class BranchError(ValueError):
|
|
69
|
+
"""A branch that cannot start: its branch point is not one of the parent's calls."""
|
|
70
|
+
|
|
71
|
+
|
|
72
|
+
def check_branch_point(parent: Cassette, point: int) -> None:
|
|
73
|
+
"""Refuse a branch point that is not from 0 to the number of calls in `parent`."""
|
|
74
|
+
calls = len(parent.calls)
|
|
75
|
+
if not 0 <= point <= calls:
|
|
76
|
+
raise BranchError(
|
|
77
|
+
f"the branch point must be from 0 to {calls}, the model calls in the parent's"
|
|
78
|
+
f" cassette, not {point}"
|
|
79
|
+
)
|
|
80
|
+
|
|
81
|
+
|
|
82
|
+
class BranchPlayer:
|
|
83
|
+
"""Serves the parent cassette's first `point` calls, in order, to every agent worker
|
|
84
|
+
of one branch run, then lets every later call through to the next model."""
|
|
85
|
+
|
|
86
|
+
def __init__(self, parent: Cassette, point: int) -> None:
|
|
87
|
+
check_branch_point(parent, point)
|
|
88
|
+
self.parent = parent
|
|
89
|
+
self.point = point
|
|
90
|
+
self._player = CassettePlayer(
|
|
91
|
+
Cassette(run=parent.run, model=parent.model, calls=parent.calls[:point])
|
|
92
|
+
)
|
|
93
|
+
|
|
94
|
+
@property
|
|
95
|
+
def served(self) -> int:
|
|
96
|
+
"""How many of the parent's calls the branch has replayed."""
|
|
97
|
+
return self._player.served
|
|
98
|
+
|
|
99
|
+
@property
|
|
100
|
+
def replaying(self) -> bool:
|
|
101
|
+
"""Whether the next call to be answered is one of the parent's: fewer than K calls
|
|
102
|
+
were answered, or the replay of the parent's calls already failed."""
|
|
103
|
+
return self._player.failure is not None or self._player.served < self.point
|
|
104
|
+
|
|
105
|
+
def answer(self, worker: str, request: str) -> AIMessage:
|
|
106
|
+
"""The parent's response to the next of its calls, if `worker` asked it as
|
|
107
|
+
recorded. `request` is the request's hash with the parent's model."""
|
|
108
|
+
return self._player.answer(worker, request)
|
|
109
|
+
|
|
110
|
+
def finish(self) -> None:
|
|
111
|
+
"""Raise unless the run replayed the parent's first K calls, each as recorded."""
|
|
112
|
+
if self._player.failure is not None:
|
|
113
|
+
raise self._player.failure
|
|
114
|
+
served = self._player.served
|
|
115
|
+
if served < self.point:
|
|
116
|
+
raise ReplayError(
|
|
117
|
+
f"the branch made {served} model calls, but it replays the parent's first"
|
|
118
|
+
f" {self.point}: calls {served + 1} to {self.point} were never asked",
|
|
119
|
+
call=served + 1,
|
|
120
|
+
recorded=self.parent.calls[served].request,
|
|
121
|
+
)
|
|
122
|
+
|
|
123
|
+
|
|
124
|
+
class BranchModel(BaseChatModel):
|
|
125
|
+
"""A chat model that answers the parent's first K calls from its cassette and every
|
|
126
|
+
later call with the next model (0009)."""
|
|
127
|
+
|
|
128
|
+
_player: BranchPlayer = PrivateAttr()
|
|
129
|
+
_next: BaseChatModel = PrivateAttr()
|
|
130
|
+
_bound: Runnable[LanguageModelInput, AIMessage] = PrivateAttr()
|
|
131
|
+
_worker: str = PrivateAttr()
|
|
132
|
+
_think: Think = PrivateAttr()
|
|
133
|
+
_tools: list[JsonValue] = PrivateAttr()
|
|
134
|
+
_with_tools: dict[str, JsonValue] = PrivateAttr()
|
|
135
|
+
|
|
136
|
+
def __init__(
|
|
137
|
+
self, player: BranchPlayer, next_model: BaseChatModel, *, worker: str, think: Think
|
|
138
|
+
) -> None:
|
|
139
|
+
"""Branch `player`'s parent for the agent worker `worker`. `next_model` answers
|
|
140
|
+
the calls after the branch point and must take no `think_ms` of its own: this
|
|
141
|
+
model takes `think` once per call, whichever way the call goes."""
|
|
142
|
+
super().__init__()
|
|
143
|
+
self._player = player
|
|
144
|
+
self._next = next_model
|
|
145
|
+
self._bound = next_model
|
|
146
|
+
self._worker = worker
|
|
147
|
+
self._think = think
|
|
148
|
+
self._tools = []
|
|
149
|
+
self._with_tools = {}
|
|
150
|
+
|
|
151
|
+
@property
|
|
152
|
+
def _llm_type(self) -> str:
|
|
153
|
+
return "fivefold-branch"
|
|
154
|
+
|
|
155
|
+
def _generate(
|
|
156
|
+
self,
|
|
157
|
+
messages: list[BaseMessage],
|
|
158
|
+
stop: list[str] | None = None,
|
|
159
|
+
run_manager: Any = None,
|
|
160
|
+
**kwargs: Any,
|
|
161
|
+
) -> ChatResult:
|
|
162
|
+
raise NotImplementedError("the branch model runs on the scheduler's loop only")
|
|
163
|
+
|
|
164
|
+
async def _agenerate(
|
|
165
|
+
self,
|
|
166
|
+
messages: list[BaseMessage],
|
|
167
|
+
stop: list[str] | None = None,
|
|
168
|
+
run_manager: Any = None,
|
|
169
|
+
**kwargs: Any,
|
|
170
|
+
) -> ChatResult:
|
|
171
|
+
await self._think()
|
|
172
|
+
if self._player.replaying:
|
|
173
|
+
params = request_params(self._player.parent.model, self._with_tools, stop, kwargs)
|
|
174
|
+
request = request_hash(messages, tools=self._tools, params=params)
|
|
175
|
+
reply = self._player.answer(self._worker, request)
|
|
176
|
+
else:
|
|
177
|
+
reply = await self._bound.ainvoke(messages, stop=stop, **kwargs)
|
|
178
|
+
return ChatResult(generations=[ChatGeneration(message=reply)])
|
|
179
|
+
|
|
180
|
+
def bind_tools(self, tools: Sequence[Tool], **kwargs: Any) -> BranchModel:
|
|
181
|
+
"""Bind `tools` to the next model, and hash them with every replayed request, as
|
|
182
|
+
the parent's recorder did."""
|
|
183
|
+
bound = BranchModel(self._player, self._next, worker=self._worker, think=self._think)
|
|
184
|
+
bound._bound = self._next.bind_tools(tools, **kwargs)
|
|
185
|
+
bound._tools = tool_schemas(tools)
|
|
186
|
+
bound._with_tools = plain_object(kwargs, "what was bound with the tools")
|
|
187
|
+
return bound
|
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
"""The agent's checkpointer: LangGraph's Postgres saver, run inline (0008, 0009).
|
|
2
|
+
|
|
3
|
+
LangGraph keeps each worker's state in the run database's `agent` schema, where role
|
|
4
|
+
`ff_agent` has its search path (0008). A worker killed by F11 resumes from its last
|
|
5
|
+
checkpoint there.
|
|
6
|
+
|
|
7
|
+
The async Postgres saver does socket I/O that the deterministic scheduler cannot see,
|
|
8
|
+
so the run would go idle while a query is in flight. `InlinePostgresSaver` is the sync
|
|
9
|
+
saver with async methods that call the sync ones directly: each checkpoint write is part
|
|
10
|
+
of the agent's step, as every other database call in a run is (0009).
|
|
11
|
+
|
|
12
|
+
Checked in langgraph-checkpoint-postgres 3.2.1 and langgraph-checkpoint 4.3.2: the sync
|
|
13
|
+
`PostgresSaver` takes a psycopg connection made with `autocommit=True`,
|
|
14
|
+
`prepare_threshold=0` and `row_factory=dict_row` (as its `from_conn_string` makes one),
|
|
15
|
+
and `setup()` creates its tables; the base saver's async methods raise
|
|
16
|
+
`NotImplementedError` until a subclass provides them.
|
|
17
|
+
"""
|
|
18
|
+
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
from collections.abc import AsyncIterator, Sequence
|
|
22
|
+
from typing import Any
|
|
23
|
+
|
|
24
|
+
import psycopg
|
|
25
|
+
from langchain_core.runnables import RunnableConfig
|
|
26
|
+
from langgraph.checkpoint.base import (
|
|
27
|
+
ChannelVersions,
|
|
28
|
+
Checkpoint,
|
|
29
|
+
CheckpointMetadata,
|
|
30
|
+
CheckpointTuple,
|
|
31
|
+
)
|
|
32
|
+
from langgraph.checkpoint.postgres import PostgresSaver
|
|
33
|
+
from psycopg.rows import DictRow, dict_row
|
|
34
|
+
|
|
35
|
+
|
|
36
|
+
def connect(conninfo: str) -> psycopg.Connection[DictRow]:
|
|
37
|
+
"""A connection as the saver needs it."""
|
|
38
|
+
return psycopg.connect(conninfo, autocommit=True, prepare_threshold=0, row_factory=dict_row)
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class InlinePostgresSaver(PostgresSaver):
|
|
42
|
+
"""The sync Postgres saver, with async methods that run it inline."""
|
|
43
|
+
|
|
44
|
+
async def aget_tuple(self, config: RunnableConfig) -> CheckpointTuple | None:
|
|
45
|
+
return self.get_tuple(config)
|
|
46
|
+
|
|
47
|
+
async def alist(
|
|
48
|
+
self,
|
|
49
|
+
config: RunnableConfig | None,
|
|
50
|
+
*,
|
|
51
|
+
filter: dict[str, Any] | None = None,
|
|
52
|
+
before: RunnableConfig | None = None,
|
|
53
|
+
limit: int | None = None,
|
|
54
|
+
) -> AsyncIterator[CheckpointTuple]:
|
|
55
|
+
for item in self.list(config, filter=filter, before=before, limit=limit):
|
|
56
|
+
yield item
|
|
57
|
+
|
|
58
|
+
async def aput(
|
|
59
|
+
self,
|
|
60
|
+
config: RunnableConfig,
|
|
61
|
+
checkpoint: Checkpoint,
|
|
62
|
+
metadata: CheckpointMetadata,
|
|
63
|
+
new_versions: ChannelVersions,
|
|
64
|
+
) -> RunnableConfig:
|
|
65
|
+
return self.put(config, checkpoint, metadata, new_versions)
|
|
66
|
+
|
|
67
|
+
async def aput_writes(
|
|
68
|
+
self,
|
|
69
|
+
config: RunnableConfig,
|
|
70
|
+
writes: Sequence[tuple[str, Any]],
|
|
71
|
+
task_id: str,
|
|
72
|
+
task_path: str = "",
|
|
73
|
+
) -> None:
|
|
74
|
+
self.put_writes(config, writes, task_id, task_path)
|
|
75
|
+
|
|
76
|
+
async def adelete_thread(self, thread_id: str) -> None:
|
|
77
|
+
self.delete_thread(thread_id)
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
"""An agent worker's MCP connection to the gateway, in G modes (0008, 0009).
|
|
2
|
+
|
|
3
|
+
The worker talks to the gateway through one MCP session at a time. A session ends when
|
|
4
|
+
its connection does, for example when the gateway crashes (F1, 0006). The next call
|
|
5
|
+
then opens a new connection and session, with the MCP handshake, as an MCP client does
|
|
6
|
+
when its server has forgotten the session. A call already waiting when the connection
|
|
7
|
+
ends fails with `ConnectionError`, which the framework's retry handles (0008). Each
|
|
8
|
+
handshake request waits at most T, as a tool call does (0005).
|
|
9
|
+
|
|
10
|
+
Each session runs in a task of the worker, so the worker's crash ends it.
|
|
11
|
+
|
|
12
|
+
MCP SDK calls used (mcp 2.3.0): `ClientSession(read_stream, write_stream)` as an async
|
|
13
|
+
context manager, `ClientSession.initialize`, `list_tools` and `call_tool`;
|
|
14
|
+
`MCPError.code`; and `mcp_types.CONNECTION_CLOSED`, the code a call gets when its
|
|
15
|
+
connection has closed (`mcp/shared/jsonrpc_dispatcher.py`).
|
|
16
|
+
"""
|
|
17
|
+
|
|
18
|
+
from __future__ import annotations
|
|
19
|
+
|
|
20
|
+
import asyncio
|
|
21
|
+
from collections.abc import Awaitable, Callable
|
|
22
|
+
from dataclasses import dataclass
|
|
23
|
+
from typing import Any, Protocol
|
|
24
|
+
|
|
25
|
+
import mcp_types as types
|
|
26
|
+
from mcp.client.session import ClientSession
|
|
27
|
+
from mcp.shared.exceptions import MCPError
|
|
28
|
+
|
|
29
|
+
from fivefold.harness.scheduler import Scheduler, SchedulerTimeout
|
|
30
|
+
from fivefold.harness.transport import TransportTimeout
|
|
31
|
+
|
|
32
|
+
|
|
33
|
+
async def within[T](scheduler: Scheduler, call: Awaitable[T], timeout_ms: int, what: str) -> T:
|
|
34
|
+
"""Wait for `call` at most `timeout_ms` virtual ms; raise `TransportTimeout` after."""
|
|
35
|
+
try:
|
|
36
|
+
return await scheduler.wait_for(call, timeout_ms)
|
|
37
|
+
except SchedulerTimeout:
|
|
38
|
+
raise TransportTimeout(f"{what}: no answer within {timeout_ms} ms") from None
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
class Channel(Protocol):
|
|
42
|
+
"""One connection, as its agent end sees it. Its two streams satisfy the MCP SDK's
|
|
43
|
+
stream protocols, as `ClientSession` needs (`mcp/shared/_stream_protocols.py`)."""
|
|
44
|
+
|
|
45
|
+
@property
|
|
46
|
+
def client_read(self) -> Any:
|
|
47
|
+
"""What the gateway sends."""
|
|
48
|
+
...
|
|
49
|
+
|
|
50
|
+
@property
|
|
51
|
+
def client_write(self) -> Any:
|
|
52
|
+
"""Where the agent sends."""
|
|
53
|
+
...
|
|
54
|
+
|
|
55
|
+
@property
|
|
56
|
+
def ended(self) -> bool:
|
|
57
|
+
"""Whether the connection has ended, or is about to."""
|
|
58
|
+
...
|
|
59
|
+
|
|
60
|
+
def close(self) -> None:
|
|
61
|
+
"""End the connection from the agent's side."""
|
|
62
|
+
|
|
63
|
+
|
|
64
|
+
@dataclass
|
|
65
|
+
class _Session:
|
|
66
|
+
channel: Channel
|
|
67
|
+
session: ClientSession
|
|
68
|
+
done: asyncio.Event
|
|
69
|
+
|
|
70
|
+
|
|
71
|
+
class GatewayConnection:
|
|
72
|
+
"""The worker's connection to the gateway: one session at a time, a new one as needed."""
|
|
73
|
+
|
|
74
|
+
def __init__(
|
|
75
|
+
self,
|
|
76
|
+
scheduler: Scheduler,
|
|
77
|
+
connect: Callable[[], Channel],
|
|
78
|
+
*,
|
|
79
|
+
worker: str,
|
|
80
|
+
timeout_ms: int,
|
|
81
|
+
) -> None:
|
|
82
|
+
"""`connect` opens a new connection; `timeout_ms` bounds each handshake request."""
|
|
83
|
+
self._scheduler = scheduler
|
|
84
|
+
self._connect = connect
|
|
85
|
+
self._worker = worker
|
|
86
|
+
self._timeout_ms = timeout_ms
|
|
87
|
+
self._current: _Session | None = None
|
|
88
|
+
self._opening = asyncio.Lock()
|
|
89
|
+
|
|
90
|
+
async def list_tools(self) -> types.ListToolsResult:
|
|
91
|
+
"""The gateway's tools, from `tools/list`."""
|
|
92
|
+
session = await self._session()
|
|
93
|
+
return await within(self._scheduler, session.list_tools(), self._timeout_ms, "tools/list")
|
|
94
|
+
|
|
95
|
+
async def call_tool(
|
|
96
|
+
self, name: str, arguments: dict[str, Any], timeout_ms: int
|
|
97
|
+
) -> types.CallToolResult:
|
|
98
|
+
"""Call a tool, waiting at most `timeout_ms` for its result."""
|
|
99
|
+
session = await self._session()
|
|
100
|
+
try:
|
|
101
|
+
return await within(
|
|
102
|
+
self._scheduler, session.call_tool(name, arguments), timeout_ms, name
|
|
103
|
+
)
|
|
104
|
+
except MCPError as error:
|
|
105
|
+
if error.code != types.CONNECTION_CLOSED:
|
|
106
|
+
raise
|
|
107
|
+
self._end()
|
|
108
|
+
raise ConnectionError(f"{name}: the connection to the gateway closed") from error
|
|
109
|
+
|
|
110
|
+
def close(self) -> None:
|
|
111
|
+
"""End the current session and its connection, if there is one."""
|
|
112
|
+
self._end()
|
|
113
|
+
|
|
114
|
+
async def _session(self) -> ClientSession:
|
|
115
|
+
async with self._opening:
|
|
116
|
+
current = self._current
|
|
117
|
+
if current is not None and not current.channel.ended:
|
|
118
|
+
return current.session
|
|
119
|
+
self._end()
|
|
120
|
+
channel = self._connect()
|
|
121
|
+
opened: asyncio.Future[ClientSession] = asyncio.get_running_loop().create_future()
|
|
122
|
+
done = asyncio.Event()
|
|
123
|
+
self._scheduler.spawn(
|
|
124
|
+
self._worker, self._hold(channel, opened, done), name=f"{self._worker} session"
|
|
125
|
+
)
|
|
126
|
+
session = await opened
|
|
127
|
+
fresh = _Session(channel, session, done)
|
|
128
|
+
self._current = fresh
|
|
129
|
+
try:
|
|
130
|
+
await within(self._scheduler, session.initialize(), self._timeout_ms, "initialize")
|
|
131
|
+
except BaseException:
|
|
132
|
+
if self._current is fresh:
|
|
133
|
+
self._end()
|
|
134
|
+
raise
|
|
135
|
+
return session
|
|
136
|
+
|
|
137
|
+
async def _hold(
|
|
138
|
+
self, channel: Channel, opened: asyncio.Future[ClientSession], done: asyncio.Event
|
|
139
|
+
) -> None:
|
|
140
|
+
"""Keep one session open until it is no longer needed."""
|
|
141
|
+
try:
|
|
142
|
+
async with ClientSession(channel.client_read, channel.client_write) as session:
|
|
143
|
+
opened.set_result(session)
|
|
144
|
+
await done.wait()
|
|
145
|
+
except Exception as error:
|
|
146
|
+
if not opened.done():
|
|
147
|
+
opened.set_exception(error)
|
|
148
|
+
|
|
149
|
+
def _end(self) -> None:
|
|
150
|
+
current, self._current = self._current, None
|
|
151
|
+
if current is not None:
|
|
152
|
+
current.done.set()
|
|
153
|
+
current.channel.close()
|