forge-tool 0.1.0__tar.gz → 2.0.0__tar.gz
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.
- {forge_tool-0.1.0 → forge_tool-2.0.0}/PKG-INFO +40 -40
- {forge_tool-0.1.0 → forge_tool-2.0.0}/README.md +38 -38
- {forge_tool-0.1.0 → forge_tool-2.0.0}/pyproject.toml +2 -2
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/dora.py +16 -14
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/handler.py +64 -57
- {forge_tool-0.1.0 → forge_tool-2.0.0}/LICENSE +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/__init__.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/endpoint/__init__.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/endpoint/exceptions.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/endpoint/models.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/endpoint/protocol.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/py.typed +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/wire/__init__.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/wire/codec.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/wire/descriptor.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/wire/envelope.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/wire/errors.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/wire/factories.py +0 -0
- {forge_tool-0.1.0 → forge_tool-2.0.0}/src/forge_tool/wire/messages.py +0 -0
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: forge-tool
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 2.0.0
|
|
4
4
|
Summary: Typed endpoint contracts for Forge query, action, and session tools.
|
|
5
5
|
Author: X-ERA
|
|
6
6
|
License-Expression: Apache-2.0
|
|
7
7
|
License-File: LICENSE
|
|
8
|
-
Requires-Dist: forge-msgs>=
|
|
8
|
+
Requires-Dist: forge-msgs>=2.0.0,<3 ; extra == 'dora'
|
|
9
9
|
Requires-Python: >=3.12
|
|
10
10
|
Provides-Extra: dora
|
|
11
11
|
Description-Content-Type: text/markdown
|
|
@@ -22,7 +22,7 @@ It provides:
|
|
|
22
22
|
- async Query, Action, and Session ToolEndpoint SPI;
|
|
23
23
|
- strict logical envelopes, typed payload codecs, complete factories, and correlation
|
|
24
24
|
validators;
|
|
25
|
-
- a transport-independent Query/Action `ToolEndpointHandler`; and
|
|
25
|
+
- a transport-independent Query/Action/Session `ToolEndpointHandler`; and
|
|
26
26
|
- an optional in-memory Arrow binding for embedding the handler in a Dora Operator or
|
|
27
27
|
Adapter node.
|
|
28
28
|
|
|
@@ -35,19 +35,18 @@ persistent execution service.
|
|
|
35
35
|
| --- | --- | --- | --- |
|
|
36
36
|
| Models, descriptor, and SPI | Implemented | Implemented | Implemented |
|
|
37
37
|
| Logical Wire messages | Implemented | Implemented | Implemented |
|
|
38
|
-
| `ToolEndpointHandler` execution | Implemented | Implemented |
|
|
39
|
-
| Optional Arrow/Dora binding | Implemented | Implemented |
|
|
38
|
+
| `ToolEndpointHandler` execution | Implemented | Implemented | Implemented |
|
|
39
|
+
| Optional Arrow/Dora binding | Implemented | Implemented | Implemented |
|
|
40
40
|
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
Session operation yet.
|
|
41
|
+
Action and Session operations share the handler's bounded execution lifecycle. Their
|
|
42
|
+
control semantics remain distinct: Action admits `cancel`, while Session admits `stop`.
|
|
44
43
|
|
|
45
|
-
The sibling Gateway integration is currently Query-only. Provider-side Action
|
|
46
|
-
therefore does not imply a complete caller-to-provider Action system.
|
|
44
|
+
The sibling Gateway integration is currently Query-only. Provider-side Action and Session
|
|
45
|
+
handling therefore does not imply a complete caller-to-provider Action or Session system.
|
|
47
46
|
|
|
48
47
|
## Installation
|
|
49
48
|
|
|
50
|
-
Python 3.12 or newer is required. Install Tool
|
|
49
|
+
Python 3.12 or newer is required. Install the current Tool release from PyPI:
|
|
51
50
|
|
|
52
51
|
```bash
|
|
53
52
|
pip install forge-tool
|
|
@@ -149,12 +148,13 @@ Use `ToolEndpointError(ToolError(...))` only to reject a request **before** exec
|
|
|
149
148
|
accepted or side effects begin. Once execution has begun, represent a Query failure as a
|
|
150
149
|
terminal `ToolResult(status="failed", error=...)`.
|
|
151
150
|
|
|
152
|
-
## Action endpoints
|
|
151
|
+
## Action and Session endpoints
|
|
153
152
|
|
|
154
|
-
An Action normally admits work with `ToolAccepted`, then exposes authoritative
|
|
155
|
-
result,
|
|
156
|
-
|
|
157
|
-
`
|
|
153
|
+
An Action or Session normally admits work with `ToolAccepted`, then exposes authoritative
|
|
154
|
+
status, result, semantics-scoped control, and low-rate events. Action uses optional
|
|
155
|
+
cancellation; Session uses optional stopping. Either may instead return an initial terminal
|
|
156
|
+
`ToolResult` when completion was established during `start()`, including terminal `unknown`
|
|
157
|
+
when dispatch may have begun but acceptance cannot be established.
|
|
158
158
|
|
|
159
159
|
```python
|
|
160
160
|
from forge_tool import (
|
|
@@ -250,12 +250,12 @@ acknowledged publication barrier.
|
|
|
250
250
|
|
|
251
251
|
The provider remains authoritative for business status, result, and control decisions.
|
|
252
252
|
|
|
253
|
-
### Action handler guarantees
|
|
253
|
+
### Action and Session handler guarantees
|
|
254
254
|
|
|
255
255
|
The current Python handler provides provider-side lifecycle and logical-ordering guarantees:
|
|
256
256
|
|
|
257
257
|
- descriptor operation names and implementation mapping must match exactly;
|
|
258
|
-
- `max_concurrency` is enforced per Action operation;
|
|
258
|
+
- `max_concurrency` is enforced per Action or Session operation;
|
|
259
259
|
- the invoke response is first in the returned tuple, before events buffered during
|
|
260
260
|
`start()`;
|
|
261
261
|
- an asynchronous event sink preserves sequence order, while its transport integration
|
|
@@ -274,22 +274,22 @@ process-local and bounded; eviction or restart ends duplicate protection. Duplic
|
|
|
274
274
|
requests are keyed by `invocation_id + attempt_id` and are not compared by arguments or
|
|
275
275
|
context fingerprint.
|
|
276
276
|
|
|
277
|
-
The handler
|
|
278
|
-
It
|
|
277
|
+
The handler enforces descriptor `max_concurrency` for Action and Session admission.
|
|
278
|
+
It validates but does not enforce `ToolContext.deadline_ms`; timeout ownership
|
|
279
279
|
belongs to the provider or future Runtime/Gateway policy.
|
|
280
280
|
|
|
281
281
|
## Handler entry points
|
|
282
282
|
|
|
283
283
|
| API | Supported behavior |
|
|
284
284
|
| --- | --- |
|
|
285
|
-
| `handle_invoke(request)` | Legacy single-response Query invoke only. Rejects Action without starting it. |
|
|
286
|
-
| `dispatch(request, event_sink=...)` | Query invoke
|
|
287
|
-
| `handle_status(request)` | Convenience wrapper for Action status dispatch. |
|
|
288
|
-
| `handle_result(request)` | Convenience wrapper for Action result dispatch. |
|
|
289
|
-
| `handle_control(request)` | Convenience wrapper for Action control dispatch. |
|
|
285
|
+
| `handle_invoke(request)` | Legacy single-response Query invoke only. Rejects Action or Session without starting it. |
|
|
286
|
+
| `dispatch(request, event_sink=...)` | Query invoke plus Action/Session invoke, status, result, and control. Response is first in the returned tuple. |
|
|
287
|
+
| `handle_status(request)` | Convenience wrapper for Action/Session status dispatch. |
|
|
288
|
+
| `handle_result(request)` | Convenience wrapper for Action/Session result dispatch. |
|
|
289
|
+
| `handle_control(request)` | Convenience wrapper for Action/Session control dispatch. |
|
|
290
290
|
|
|
291
|
-
Action
|
|
292
|
-
|
|
291
|
+
Action admits `cancel`, and Session admits `stop`; a control command that does not match
|
|
292
|
+
the operation semantics returns `unsupported`.
|
|
293
293
|
|
|
294
294
|
## Optional Arrow/Dora binding
|
|
295
295
|
|
|
@@ -325,16 +325,16 @@ async def handle_query_input(input_arrow_value):
|
|
|
325
325
|
```
|
|
326
326
|
|
|
327
327
|
`handle_input()` preserves the Query-only single-response API and returns one
|
|
328
|
-
`RecordBatch`. It rejects an Action before calling `start()`.
|
|
328
|
+
`RecordBatch`. It rejects an Action or Session before calling `start()`.
|
|
329
329
|
|
|
330
|
-
### Action
|
|
330
|
+
### Action and Session
|
|
331
331
|
|
|
332
332
|
```python
|
|
333
|
-
async def
|
|
334
|
-
await binding.dispatch_input(
|
|
333
|
+
async def handle_stateful_input(input_arrow_value) -> None:
|
|
334
|
+
await binding.dispatch_input(input_arrow_value)
|
|
335
335
|
```
|
|
336
336
|
|
|
337
|
-
For an Action invoke, the configured async `event_sink` is the acknowledged publisher
|
|
337
|
+
For an Action or Session invoke, the configured async `event_sink` is the acknowledged publisher
|
|
338
338
|
for **both** the invoke response and subsequent events. The binding waits for physical
|
|
339
339
|
response publication before opening the event gate, serializes events in sequence order,
|
|
340
340
|
and returns `()` after publication.
|
|
@@ -361,7 +361,7 @@ A common source of integration bugs is assuming one layer validates everything.
|
|
|
361
361
|
| `forge_msgs.ToolMessage` | Exact Arrow schema, one row, generic identity/nullability rules, strict object-valued `payload_json`. |
|
|
362
362
|
| `ToolEnvelope` | Protocol/message type and generic logical header matrix; JSON-compatible payload object. |
|
|
363
363
|
| `validate_message_envelope`, codec, and factories | Message-specific closed payload schema and complete logical construction. |
|
|
364
|
-
| `ToolEndpointHandler` | Concrete provider route, descriptor operation semantics, SPI dispatch, and Action lifecycle. |
|
|
364
|
+
| `ToolEndpointHandler` | Concrete provider route, descriptor operation semantics, SPI dispatch, and Action/Session lifecycle. |
|
|
365
365
|
| `DoraToolEndpointBinding` | Carrier/raw payload/logical size boundaries and bounded correlated error conversion after route trust. |
|
|
366
366
|
|
|
367
367
|
Outbound conversion validates the typed payload. Inbound carrier conversion first
|
|
@@ -382,8 +382,8 @@ These are implementation defaults, not cross-language Wire constants.
|
|
|
382
382
|
| Logical encoded message | 1 MiB (`1_048_576` bytes) |
|
|
383
383
|
| Accepted binding request | logical maximum minus 512 bytes of correlated-error headroom |
|
|
384
384
|
| In-memory Arrow carrier | logical maximum plus 64 KiB of framing overhead |
|
|
385
|
-
| Early Action events | 32 events |
|
|
386
|
-
| Retained Action execution records | 1,024 records |
|
|
385
|
+
| Early Action/Session events | 32 events |
|
|
386
|
+
| Retained Action/Session execution records | 1,024 records |
|
|
387
387
|
| JSON nesting | 64 levels |
|
|
388
388
|
| Interoperable JSON integer | `±(2^53-1)` |
|
|
389
389
|
|
|
@@ -425,10 +425,10 @@ Explicitly import from `forge_tool.dora`:
|
|
|
425
425
|
|
|
426
426
|
## Protocol documentation
|
|
427
427
|
|
|
428
|
-
- [Tool documentation index](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-
|
|
429
|
-
- [Architecture](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-
|
|
430
|
-
- [ToolEndpoint Wire protocol](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-
|
|
431
|
-
- [Canonical `ToolMessage` Arrow schema](https://github.com/Forgelab-Robotics/forge/blob/forge-msgs-
|
|
428
|
+
- [Tool documentation index](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/README.md)
|
|
429
|
+
- [Architecture](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/ARCHITECTURE.md)
|
|
430
|
+
- [ToolEndpoint Wire protocol](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/PROTOCOL.md)
|
|
431
|
+
- [Canonical `ToolMessage` Arrow schema](https://github.com/Forgelab-Robotics/forge/blob/forge-msgs-v2.0.0/interfaces/forge_msgs/tool.v1.yaml)
|
|
432
432
|
|
|
433
433
|
## Development
|
|
434
434
|
|
|
@@ -440,4 +440,4 @@ uv run pytest packages/tool/tests
|
|
|
440
440
|
|
|
441
441
|
## License
|
|
442
442
|
|
|
443
|
-
Apache-2.0. See the release [LICENSE](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-
|
|
443
|
+
Apache-2.0. See the release [LICENSE](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/LICENSE).
|
|
@@ -10,7 +10,7 @@ It provides:
|
|
|
10
10
|
- async Query, Action, and Session ToolEndpoint SPI;
|
|
11
11
|
- strict logical envelopes, typed payload codecs, complete factories, and correlation
|
|
12
12
|
validators;
|
|
13
|
-
- a transport-independent Query/Action `ToolEndpointHandler`; and
|
|
13
|
+
- a transport-independent Query/Action/Session `ToolEndpointHandler`; and
|
|
14
14
|
- an optional in-memory Arrow binding for embedding the handler in a Dora Operator or
|
|
15
15
|
Adapter node.
|
|
16
16
|
|
|
@@ -23,19 +23,18 @@ persistent execution service.
|
|
|
23
23
|
| --- | --- | --- | --- |
|
|
24
24
|
| Models, descriptor, and SPI | Implemented | Implemented | Implemented |
|
|
25
25
|
| Logical Wire messages | Implemented | Implemented | Implemented |
|
|
26
|
-
| `ToolEndpointHandler` execution | Implemented | Implemented |
|
|
27
|
-
| Optional Arrow/Dora binding | Implemented | Implemented |
|
|
26
|
+
| `ToolEndpointHandler` execution | Implemented | Implemented | Implemented |
|
|
27
|
+
| Optional Arrow/Dora binding | Implemented | Implemented | Implemented |
|
|
28
28
|
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
Session operation yet.
|
|
29
|
+
Action and Session operations share the handler's bounded execution lifecycle. Their
|
|
30
|
+
control semantics remain distinct: Action admits `cancel`, while Session admits `stop`.
|
|
32
31
|
|
|
33
|
-
The sibling Gateway integration is currently Query-only. Provider-side Action
|
|
34
|
-
therefore does not imply a complete caller-to-provider Action system.
|
|
32
|
+
The sibling Gateway integration is currently Query-only. Provider-side Action and Session
|
|
33
|
+
handling therefore does not imply a complete caller-to-provider Action or Session system.
|
|
35
34
|
|
|
36
35
|
## Installation
|
|
37
36
|
|
|
38
|
-
Python 3.12 or newer is required. Install Tool
|
|
37
|
+
Python 3.12 or newer is required. Install the current Tool release from PyPI:
|
|
39
38
|
|
|
40
39
|
```bash
|
|
41
40
|
pip install forge-tool
|
|
@@ -137,12 +136,13 @@ Use `ToolEndpointError(ToolError(...))` only to reject a request **before** exec
|
|
|
137
136
|
accepted or side effects begin. Once execution has begun, represent a Query failure as a
|
|
138
137
|
terminal `ToolResult(status="failed", error=...)`.
|
|
139
138
|
|
|
140
|
-
## Action endpoints
|
|
139
|
+
## Action and Session endpoints
|
|
141
140
|
|
|
142
|
-
An Action normally admits work with `ToolAccepted`, then exposes authoritative
|
|
143
|
-
result,
|
|
144
|
-
|
|
145
|
-
`
|
|
141
|
+
An Action or Session normally admits work with `ToolAccepted`, then exposes authoritative
|
|
142
|
+
status, result, semantics-scoped control, and low-rate events. Action uses optional
|
|
143
|
+
cancellation; Session uses optional stopping. Either may instead return an initial terminal
|
|
144
|
+
`ToolResult` when completion was established during `start()`, including terminal `unknown`
|
|
145
|
+
when dispatch may have begun but acceptance cannot be established.
|
|
146
146
|
|
|
147
147
|
```python
|
|
148
148
|
from forge_tool import (
|
|
@@ -238,12 +238,12 @@ acknowledged publication barrier.
|
|
|
238
238
|
|
|
239
239
|
The provider remains authoritative for business status, result, and control decisions.
|
|
240
240
|
|
|
241
|
-
### Action handler guarantees
|
|
241
|
+
### Action and Session handler guarantees
|
|
242
242
|
|
|
243
243
|
The current Python handler provides provider-side lifecycle and logical-ordering guarantees:
|
|
244
244
|
|
|
245
245
|
- descriptor operation names and implementation mapping must match exactly;
|
|
246
|
-
- `max_concurrency` is enforced per Action operation;
|
|
246
|
+
- `max_concurrency` is enforced per Action or Session operation;
|
|
247
247
|
- the invoke response is first in the returned tuple, before events buffered during
|
|
248
248
|
`start()`;
|
|
249
249
|
- an asynchronous event sink preserves sequence order, while its transport integration
|
|
@@ -262,22 +262,22 @@ process-local and bounded; eviction or restart ends duplicate protection. Duplic
|
|
|
262
262
|
requests are keyed by `invocation_id + attempt_id` and are not compared by arguments or
|
|
263
263
|
context fingerprint.
|
|
264
264
|
|
|
265
|
-
The handler
|
|
266
|
-
It
|
|
265
|
+
The handler enforces descriptor `max_concurrency` for Action and Session admission.
|
|
266
|
+
It validates but does not enforce `ToolContext.deadline_ms`; timeout ownership
|
|
267
267
|
belongs to the provider or future Runtime/Gateway policy.
|
|
268
268
|
|
|
269
269
|
## Handler entry points
|
|
270
270
|
|
|
271
271
|
| API | Supported behavior |
|
|
272
272
|
| --- | --- |
|
|
273
|
-
| `handle_invoke(request)` | Legacy single-response Query invoke only. Rejects Action without starting it. |
|
|
274
|
-
| `dispatch(request, event_sink=...)` | Query invoke
|
|
275
|
-
| `handle_status(request)` | Convenience wrapper for Action status dispatch. |
|
|
276
|
-
| `handle_result(request)` | Convenience wrapper for Action result dispatch. |
|
|
277
|
-
| `handle_control(request)` | Convenience wrapper for Action control dispatch. |
|
|
273
|
+
| `handle_invoke(request)` | Legacy single-response Query invoke only. Rejects Action or Session without starting it. |
|
|
274
|
+
| `dispatch(request, event_sink=...)` | Query invoke plus Action/Session invoke, status, result, and control. Response is first in the returned tuple. |
|
|
275
|
+
| `handle_status(request)` | Convenience wrapper for Action/Session status dispatch. |
|
|
276
|
+
| `handle_result(request)` | Convenience wrapper for Action/Session result dispatch. |
|
|
277
|
+
| `handle_control(request)` | Convenience wrapper for Action/Session control dispatch. |
|
|
278
278
|
|
|
279
|
-
Action
|
|
280
|
-
|
|
279
|
+
Action admits `cancel`, and Session admits `stop`; a control command that does not match
|
|
280
|
+
the operation semantics returns `unsupported`.
|
|
281
281
|
|
|
282
282
|
## Optional Arrow/Dora binding
|
|
283
283
|
|
|
@@ -313,16 +313,16 @@ async def handle_query_input(input_arrow_value):
|
|
|
313
313
|
```
|
|
314
314
|
|
|
315
315
|
`handle_input()` preserves the Query-only single-response API and returns one
|
|
316
|
-
`RecordBatch`. It rejects an Action before calling `start()`.
|
|
316
|
+
`RecordBatch`. It rejects an Action or Session before calling `start()`.
|
|
317
317
|
|
|
318
|
-
### Action
|
|
318
|
+
### Action and Session
|
|
319
319
|
|
|
320
320
|
```python
|
|
321
|
-
async def
|
|
322
|
-
await binding.dispatch_input(
|
|
321
|
+
async def handle_stateful_input(input_arrow_value) -> None:
|
|
322
|
+
await binding.dispatch_input(input_arrow_value)
|
|
323
323
|
```
|
|
324
324
|
|
|
325
|
-
For an Action invoke, the configured async `event_sink` is the acknowledged publisher
|
|
325
|
+
For an Action or Session invoke, the configured async `event_sink` is the acknowledged publisher
|
|
326
326
|
for **both** the invoke response and subsequent events. The binding waits for physical
|
|
327
327
|
response publication before opening the event gate, serializes events in sequence order,
|
|
328
328
|
and returns `()` after publication.
|
|
@@ -349,7 +349,7 @@ A common source of integration bugs is assuming one layer validates everything.
|
|
|
349
349
|
| `forge_msgs.ToolMessage` | Exact Arrow schema, one row, generic identity/nullability rules, strict object-valued `payload_json`. |
|
|
350
350
|
| `ToolEnvelope` | Protocol/message type and generic logical header matrix; JSON-compatible payload object. |
|
|
351
351
|
| `validate_message_envelope`, codec, and factories | Message-specific closed payload schema and complete logical construction. |
|
|
352
|
-
| `ToolEndpointHandler` | Concrete provider route, descriptor operation semantics, SPI dispatch, and Action lifecycle. |
|
|
352
|
+
| `ToolEndpointHandler` | Concrete provider route, descriptor operation semantics, SPI dispatch, and Action/Session lifecycle. |
|
|
353
353
|
| `DoraToolEndpointBinding` | Carrier/raw payload/logical size boundaries and bounded correlated error conversion after route trust. |
|
|
354
354
|
|
|
355
355
|
Outbound conversion validates the typed payload. Inbound carrier conversion first
|
|
@@ -370,8 +370,8 @@ These are implementation defaults, not cross-language Wire constants.
|
|
|
370
370
|
| Logical encoded message | 1 MiB (`1_048_576` bytes) |
|
|
371
371
|
| Accepted binding request | logical maximum minus 512 bytes of correlated-error headroom |
|
|
372
372
|
| In-memory Arrow carrier | logical maximum plus 64 KiB of framing overhead |
|
|
373
|
-
| Early Action events | 32 events |
|
|
374
|
-
| Retained Action execution records | 1,024 records |
|
|
373
|
+
| Early Action/Session events | 32 events |
|
|
374
|
+
| Retained Action/Session execution records | 1,024 records |
|
|
375
375
|
| JSON nesting | 64 levels |
|
|
376
376
|
| Interoperable JSON integer | `±(2^53-1)` |
|
|
377
377
|
|
|
@@ -413,10 +413,10 @@ Explicitly import from `forge_tool.dora`:
|
|
|
413
413
|
|
|
414
414
|
## Protocol documentation
|
|
415
415
|
|
|
416
|
-
- [Tool documentation index](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-
|
|
417
|
-
- [Architecture](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-
|
|
418
|
-
- [ToolEndpoint Wire protocol](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-
|
|
419
|
-
- [Canonical `ToolMessage` Arrow schema](https://github.com/Forgelab-Robotics/forge/blob/forge-msgs-
|
|
416
|
+
- [Tool documentation index](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/README.md)
|
|
417
|
+
- [Architecture](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/ARCHITECTURE.md)
|
|
418
|
+
- [ToolEndpoint Wire protocol](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/interfaces/forge_tool/PROTOCOL.md)
|
|
419
|
+
- [Canonical `ToolMessage` Arrow schema](https://github.com/Forgelab-Robotics/forge/blob/forge-msgs-v2.0.0/interfaces/forge_msgs/tool.v1.yaml)
|
|
420
420
|
|
|
421
421
|
## Development
|
|
422
422
|
|
|
@@ -428,4 +428,4 @@ uv run pytest packages/tool/tests
|
|
|
428
428
|
|
|
429
429
|
## License
|
|
430
430
|
|
|
431
|
-
Apache-2.0. See the release [LICENSE](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-
|
|
431
|
+
Apache-2.0. See the release [LICENSE](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v2.0.0/LICENSE).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
[project]
|
|
2
2
|
name = "forge-tool"
|
|
3
|
-
version = "0.
|
|
3
|
+
version = "2.0.0"
|
|
4
4
|
description = "Typed endpoint contracts for Forge query, action, and session tools."
|
|
5
5
|
readme = "README.md"
|
|
6
6
|
requires-python = ">=3.12"
|
|
@@ -12,7 +12,7 @@ authors = [
|
|
|
12
12
|
dependencies = []
|
|
13
13
|
|
|
14
14
|
[project.optional-dependencies]
|
|
15
|
-
dora = ["forge-msgs>=
|
|
15
|
+
dora = ["forge-msgs>=2.0.0,<3"]
|
|
16
16
|
|
|
17
17
|
[tool.uv.sources]
|
|
18
18
|
forge-msgs = { workspace = true }
|
|
@@ -311,10 +311,10 @@ class DoraToolEndpointBinding:
|
|
|
311
311
|
) -> tuple[pa.RecordBatch, ...]:
|
|
312
312
|
"""Dispatch one execution request.
|
|
313
313
|
|
|
314
|
-
Action invoke requires ``event_sink``. The binding publishes its
|
|
315
|
-
buffered events through that same sink, awaiting the response
|
|
316
|
-
opening the late-event barrier, and returns an empty tuple.
|
|
317
|
-
retain the response-first returned-tuple API.
|
|
314
|
+
Action or Session invoke requires ``event_sink``. The binding publishes its
|
|
315
|
+
response and buffered events through that same sink, awaiting the response
|
|
316
|
+
publication before opening the late-event barrier, and returns an empty tuple.
|
|
317
|
+
Other request types retain the response-first returned-tuple API.
|
|
318
318
|
"""
|
|
319
319
|
request = self._request_from_arrow(value)
|
|
320
320
|
try:
|
|
@@ -333,13 +333,14 @@ class DoraToolEndpointBinding:
|
|
|
333
333
|
for operation in self._handler.descriptor.operations
|
|
334
334
|
if operation.name == request.operation
|
|
335
335
|
)
|
|
336
|
-
|
|
336
|
+
start_invoke = (
|
|
337
337
|
request.message_type == "tool.invoke.request"
|
|
338
|
-
and operation_descriptor.semantics
|
|
338
|
+
and operation_descriptor.semantics in ("action", "session")
|
|
339
339
|
)
|
|
340
|
-
if
|
|
340
|
+
if start_invoke and self._event_sink is None:
|
|
341
341
|
raise RuntimeError(
|
|
342
|
-
"Action dispatch requires an asynchronous event_sink
|
|
342
|
+
"Action or Session dispatch requires an asynchronous event_sink "
|
|
343
|
+
"publisher"
|
|
343
344
|
)
|
|
344
345
|
|
|
345
346
|
publish_ready = asyncio.Event()
|
|
@@ -350,17 +351,17 @@ class DoraToolEndpointBinding:
|
|
|
350
351
|
await publish_ready.wait()
|
|
351
352
|
if publish_failure:
|
|
352
353
|
raise RuntimeError(
|
|
353
|
-
"
|
|
354
|
+
"Response publication failed; event was not published"
|
|
354
355
|
) from publish_failure[0]
|
|
355
356
|
if self._event_sink is None:
|
|
356
|
-
raise RuntimeError("
|
|
357
|
+
raise RuntimeError("Event publisher is unavailable")
|
|
357
358
|
async with publish_lock:
|
|
358
359
|
await self._event_sink(self._event_to_arrow(event))
|
|
359
360
|
|
|
360
361
|
try:
|
|
361
362
|
messages = await self._handler.dispatch(
|
|
362
363
|
request,
|
|
363
|
-
event_sink=emit_event if
|
|
364
|
+
event_sink=emit_event if start_invoke else None,
|
|
364
365
|
)
|
|
365
366
|
except Exception: # noqa: BLE001 - trusted requests must receive a response.
|
|
366
367
|
logger.exception(
|
|
@@ -374,7 +375,7 @@ class DoraToolEndpointBinding:
|
|
|
374
375
|
request.operation,
|
|
375
376
|
)
|
|
376
377
|
messages = (_correlated_internal_error(request),)
|
|
377
|
-
if not
|
|
378
|
+
if not start_invoke:
|
|
378
379
|
return tuple(
|
|
379
380
|
self._event_to_arrow(message)
|
|
380
381
|
if message.message_type == "tool.event"
|
|
@@ -383,7 +384,7 @@ class DoraToolEndpointBinding:
|
|
|
383
384
|
)
|
|
384
385
|
|
|
385
386
|
if self._event_sink is None:
|
|
386
|
-
raise RuntimeError("
|
|
387
|
+
raise RuntimeError("Event publisher is unavailable")
|
|
387
388
|
response_batch = self._response_to_arrow(messages[0], request)
|
|
388
389
|
try:
|
|
389
390
|
async with publish_lock:
|
|
@@ -409,7 +410,8 @@ class DoraToolEndpointBinding:
|
|
|
409
410
|
)
|
|
410
411
|
if operation_descriptor.semantics != "query":
|
|
411
412
|
raise NotImplementedError(
|
|
412
|
-
"handle_input is Query-only; Action operations must use
|
|
413
|
+
"handle_input is Query-only; Action or Session operations must use "
|
|
414
|
+
"dispatch_input"
|
|
413
415
|
)
|
|
414
416
|
try:
|
|
415
417
|
_validate_envelope_size(request, self._max_request_bytes)
|
|
@@ -103,7 +103,7 @@ class _ActionEventEmitter:
|
|
|
103
103
|
self,
|
|
104
104
|
handler: ToolEndpointHandler,
|
|
105
105
|
record: _ExecutionRecord,
|
|
106
|
-
endpoint: ActionToolEndpoint,
|
|
106
|
+
endpoint: ActionToolEndpoint | SessionToolEndpoint,
|
|
107
107
|
*,
|
|
108
108
|
sink: ToolEventSink | None,
|
|
109
109
|
max_early_events: int,
|
|
@@ -121,7 +121,7 @@ class _ActionEventEmitter:
|
|
|
121
121
|
self._terminal_pending = False
|
|
122
122
|
|
|
123
123
|
async def emit(self, event: ToolEvent) -> None:
|
|
124
|
-
"""Validate, sequence, and expose one event for the bound
|
|
124
|
+
"""Validate, sequence, and expose one event for the bound execution attempt."""
|
|
125
125
|
if not isinstance(event, ToolEvent):
|
|
126
126
|
raise TypeError("event must be a ToolEvent")
|
|
127
127
|
|
|
@@ -130,7 +130,7 @@ class _ActionEventEmitter:
|
|
|
130
130
|
if self._closed or self._terminal_pending:
|
|
131
131
|
raise ToolProtocolError(
|
|
132
132
|
"FORGE_ENDPOINT_EVENT_AFTER_TERMINAL",
|
|
133
|
-
"an
|
|
133
|
+
"an event was emitted after terminal event progression closed",
|
|
134
134
|
)
|
|
135
135
|
if terminal_phase is not None:
|
|
136
136
|
self._terminal_pending = True
|
|
@@ -153,7 +153,7 @@ class _ActionEventEmitter:
|
|
|
153
153
|
raise ToolProtocolError(
|
|
154
154
|
"FORGE_ENDPOINT_EARLY_EVENT_BUFFER_OVERFLOW",
|
|
155
155
|
(
|
|
156
|
-
"
|
|
156
|
+
"Tool endpoint emitted more than "
|
|
157
157
|
f"{self._max_early_events} events before acceptance"
|
|
158
158
|
),
|
|
159
159
|
)
|
|
@@ -172,7 +172,8 @@ class _ActionEventEmitter:
|
|
|
172
172
|
return
|
|
173
173
|
if self._sink is None:
|
|
174
174
|
raise RuntimeError(
|
|
175
|
-
"
|
|
175
|
+
"Tool endpoint emitted after acceptance without an asynchronous "
|
|
176
|
+
"event sink"
|
|
176
177
|
)
|
|
177
178
|
# Keep the emitter lock across the asynchronous sink so concurrent emitters
|
|
178
179
|
# cannot physically publish a later sequence first.
|
|
@@ -220,11 +221,12 @@ def _validate_implementation(
|
|
|
220
221
|
|
|
221
222
|
|
|
222
223
|
class ToolEndpointHandler:
|
|
223
|
-
"""Bind endpoint implementations and dispatch Query/Action execution messages.
|
|
224
|
+
"""Bind endpoint implementations and dispatch Query/Action/Session execution messages.
|
|
224
225
|
|
|
225
|
-
Action transport state is deliberately module-private. Provider methods
|
|
226
|
-
authority for business status, result, and control decisions.
|
|
227
|
-
|
|
226
|
+
Action and Session transport state is deliberately module-private. Provider methods
|
|
227
|
+
remain the authority for business status, result, and control decisions. Control
|
|
228
|
+
dispatch is semantics-scoped: cancel is only admitted for Action operations and
|
|
229
|
+
stop only for Session operations.
|
|
228
230
|
"""
|
|
229
231
|
|
|
230
232
|
__slots__ = (
|
|
@@ -429,7 +431,7 @@ class ToolEndpointHandler:
|
|
|
429
431
|
record.permit_held = False
|
|
430
432
|
active = self._active_by_operation[record.operation]
|
|
431
433
|
if active <= 0:
|
|
432
|
-
raise RuntimeError("
|
|
434
|
+
raise RuntimeError("Execution admission permit count became negative")
|
|
433
435
|
self._active_by_operation[record.operation] = active - 1
|
|
434
436
|
|
|
435
437
|
@staticmethod
|
|
@@ -530,12 +532,12 @@ class ToolEndpointHandler:
|
|
|
530
532
|
self,
|
|
531
533
|
key: ToolExecutionKey,
|
|
532
534
|
operation: str,
|
|
533
|
-
endpoint: ActionToolEndpoint,
|
|
535
|
+
endpoint: ActionToolEndpoint | SessionToolEndpoint,
|
|
534
536
|
status: ToolExecutionStatus,
|
|
535
537
|
) -> ToolResult:
|
|
536
538
|
response = await endpoint.result(key)
|
|
537
539
|
if not isinstance(response, ToolResultResponse):
|
|
538
|
-
raise TypeError("
|
|
540
|
+
raise TypeError("Tool endpoint result() must return a ToolResultResponse")
|
|
539
541
|
if response.status != "available" or response.result is None:
|
|
540
542
|
raise ToolProtocolError(
|
|
541
543
|
"FORGE_ENDPOINT_TERMINAL_RESULT_UNAVAILABLE",
|
|
@@ -547,12 +549,12 @@ class ToolEndpointHandler:
|
|
|
547
549
|
async def _establish_terminal_from_event(
|
|
548
550
|
self,
|
|
549
551
|
key: ToolExecutionKey,
|
|
550
|
-
endpoint: ActionToolEndpoint,
|
|
552
|
+
endpoint: ActionToolEndpoint | SessionToolEndpoint,
|
|
551
553
|
phase: str,
|
|
552
554
|
) -> None:
|
|
553
555
|
response = await endpoint.result(key)
|
|
554
556
|
if not isinstance(response, ToolResultResponse):
|
|
555
|
-
raise TypeError("
|
|
557
|
+
raise TypeError("Tool endpoint result() must return a ToolResultResponse")
|
|
556
558
|
if response.status != "available" or response.result is None:
|
|
557
559
|
raise ToolProtocolError(
|
|
558
560
|
"FORGE_ENDPOINT_TERMINAL_RESULT_UNAVAILABLE",
|
|
@@ -566,7 +568,7 @@ class ToolEndpointHandler:
|
|
|
566
568
|
async with self._lock:
|
|
567
569
|
record = self._executions.get(key)
|
|
568
570
|
if record is None:
|
|
569
|
-
raise RuntimeError("
|
|
571
|
+
raise RuntimeError("Tool event has no execution record")
|
|
570
572
|
operation = record.operation
|
|
571
573
|
await self._record_terminal(
|
|
572
574
|
key,
|
|
@@ -591,7 +593,7 @@ class ToolEndpointHandler:
|
|
|
591
593
|
raise TypeError("QueryToolEndpoint.query() must return a ToolResult")
|
|
592
594
|
return (make_invoke_response_envelope(result, request),)
|
|
593
595
|
|
|
594
|
-
async def
|
|
596
|
+
async def _handle_start_invoke(
|
|
595
597
|
self,
|
|
596
598
|
request: ToolEnvelope,
|
|
597
599
|
operation_name: str,
|
|
@@ -599,7 +601,10 @@ class ToolEndpointHandler:
|
|
|
599
601
|
) -> tuple[ToolEnvelope, ...]:
|
|
600
602
|
endpoint_request, context = invoke_request_from_envelope(request)
|
|
601
603
|
key = context.execution_key
|
|
602
|
-
endpoint = cast(
|
|
604
|
+
endpoint = cast(
|
|
605
|
+
ActionToolEndpoint | SessionToolEndpoint,
|
|
606
|
+
self._implementations[operation_name],
|
|
607
|
+
)
|
|
603
608
|
|
|
604
609
|
async with self._lock:
|
|
605
610
|
record = self._executions.get(key)
|
|
@@ -661,7 +666,7 @@ class ToolEndpointHandler:
|
|
|
661
666
|
if duplicate:
|
|
662
667
|
await record.ready.wait()
|
|
663
668
|
if record.outcome is None:
|
|
664
|
-
raise RuntimeError("
|
|
669
|
+
raise RuntimeError("Execution record became ready without an outcome")
|
|
665
670
|
return (make_invoke_response_envelope(record.outcome, request),)
|
|
666
671
|
|
|
667
672
|
emitter = _ActionEventEmitter(
|
|
@@ -675,7 +680,7 @@ class ToolEndpointHandler:
|
|
|
675
680
|
try:
|
|
676
681
|
accepted = await endpoint.start(endpoint_request, context, emitter)
|
|
677
682
|
if not isinstance(accepted, ToolAccepted):
|
|
678
|
-
raise TypeError("
|
|
683
|
+
raise TypeError("Tool endpoint start() must return a ToolAccepted")
|
|
679
684
|
except ToolEndpointError as error:
|
|
680
685
|
await emitter.reject()
|
|
681
686
|
async with self._lock:
|
|
@@ -688,11 +693,11 @@ class ToolEndpointHandler:
|
|
|
688
693
|
record.ready.set()
|
|
689
694
|
return (make_invoke_response_envelope(outcome, request),)
|
|
690
695
|
except asyncio.CancelledError:
|
|
691
|
-
await asyncio.shield(self.
|
|
696
|
+
await asyncio.shield(self._finish_unknown(record, emitter))
|
|
692
697
|
raise
|
|
693
698
|
except Exception:
|
|
694
|
-
|
|
695
|
-
return (make_invoke_response_envelope(
|
|
699
|
+
unknown = await self._finish_unknown(record, emitter)
|
|
700
|
+
return (make_invoke_response_envelope(unknown, request),)
|
|
696
701
|
|
|
697
702
|
async with self._lock:
|
|
698
703
|
if record.result is not None:
|
|
@@ -709,7 +714,7 @@ class ToolEndpointHandler:
|
|
|
709
714
|
early_events = await emitter.accept()
|
|
710
715
|
return (make_invoke_response_envelope(outcome, request), *early_events)
|
|
711
716
|
|
|
712
|
-
async def
|
|
717
|
+
async def _finish_unknown(
|
|
713
718
|
self,
|
|
714
719
|
record: _ExecutionRecord,
|
|
715
720
|
emitter: _ActionEventEmitter,
|
|
@@ -720,13 +725,12 @@ class ToolEndpointHandler:
|
|
|
720
725
|
record.outcome = record.result
|
|
721
726
|
record.ready.set()
|
|
722
727
|
return record.result
|
|
723
|
-
|
|
724
728
|
unknown = ToolResult(
|
|
725
729
|
status="unknown",
|
|
726
730
|
error=ToolError(
|
|
727
731
|
code="FORGE_ENDPOINT_OUTCOME_UNKNOWN",
|
|
728
732
|
message=(
|
|
729
|
-
"
|
|
733
|
+
"Start failed after dispatch; the execution outcome "
|
|
730
734
|
"cannot be recovered"
|
|
731
735
|
),
|
|
732
736
|
retryable=False,
|
|
@@ -740,7 +744,7 @@ class ToolEndpointHandler:
|
|
|
740
744
|
record.result = unknown
|
|
741
745
|
self._release_permit_locked(record)
|
|
742
746
|
record.ready.set()
|
|
743
|
-
|
|
747
|
+
return unknown
|
|
744
748
|
|
|
745
749
|
async def handle_invoke(
|
|
746
750
|
self,
|
|
@@ -751,30 +755,31 @@ class ToolEndpointHandler:
|
|
|
751
755
|
operation_name = cast(str, request.operation)
|
|
752
756
|
if self._operation_descriptors[operation_name].semantics != "query":
|
|
753
757
|
raise NotImplementedError(
|
|
754
|
-
"handle_invoke is Query-only; Action operations must use
|
|
758
|
+
"handle_invoke is Query-only; Action or Session operations must use "
|
|
759
|
+
"dispatch"
|
|
755
760
|
)
|
|
756
761
|
messages = await self.dispatch(request)
|
|
757
762
|
return messages[0]
|
|
758
763
|
|
|
759
764
|
async def handle_status(self, request: ToolEnvelope) -> ToolEnvelope:
|
|
760
|
-
"""Dispatch one Action status lookup to the authoritative provider."""
|
|
765
|
+
"""Dispatch one Action/Session status lookup to the authoritative provider."""
|
|
761
766
|
messages = await self.dispatch(request)
|
|
762
767
|
return messages[0]
|
|
763
768
|
|
|
764
769
|
async def handle_result(self, request: ToolEnvelope) -> ToolEnvelope:
|
|
765
|
-
"""Dispatch one Action result lookup to the authoritative provider."""
|
|
770
|
+
"""Dispatch one Action/Session result lookup to the authoritative provider."""
|
|
766
771
|
messages = await self.dispatch(request)
|
|
767
772
|
return messages[0]
|
|
768
773
|
|
|
769
774
|
async def handle_control(self, request: ToolEnvelope) -> ToolEnvelope:
|
|
770
|
-
"""Dispatch one Action control request to the authoritative provider."""
|
|
775
|
+
"""Dispatch one Action/Session control request to the authoritative provider."""
|
|
771
776
|
messages = await self.dispatch(request)
|
|
772
777
|
return messages[0]
|
|
773
778
|
|
|
774
779
|
async def _handle_status(
|
|
775
780
|
self,
|
|
776
781
|
request: ToolEnvelope,
|
|
777
|
-
endpoint: ActionToolEndpoint,
|
|
782
|
+
endpoint: ActionToolEndpoint | SessionToolEndpoint,
|
|
778
783
|
key: ToolExecutionKey,
|
|
779
784
|
) -> ToolEnvelope:
|
|
780
785
|
record = self._executions.get(key)
|
|
@@ -786,7 +791,7 @@ class ToolEndpointHandler:
|
|
|
786
791
|
return make_status_response_envelope(record.status, request)
|
|
787
792
|
status = await endpoint.status(key)
|
|
788
793
|
if not isinstance(status, ToolExecutionStatus):
|
|
789
|
-
raise TypeError("
|
|
794
|
+
raise TypeError("Tool endpoint status() must return a ToolExecutionStatus")
|
|
790
795
|
if status.phase in _TERMINAL_PHASES:
|
|
791
796
|
await self._require_terminal_result(
|
|
792
797
|
key,
|
|
@@ -801,7 +806,7 @@ class ToolEndpointHandler:
|
|
|
801
806
|
async def _handle_result(
|
|
802
807
|
self,
|
|
803
808
|
request: ToolEnvelope,
|
|
804
|
-
endpoint: ActionToolEndpoint,
|
|
809
|
+
endpoint: ActionToolEndpoint | SessionToolEndpoint,
|
|
805
810
|
key: ToolExecutionKey,
|
|
806
811
|
) -> ToolEnvelope:
|
|
807
812
|
record = self._executions.get(key)
|
|
@@ -812,12 +817,12 @@ class ToolEndpointHandler:
|
|
|
812
817
|
)
|
|
813
818
|
response = await endpoint.result(key)
|
|
814
819
|
if not isinstance(response, ToolResultResponse):
|
|
815
|
-
raise TypeError("
|
|
820
|
+
raise TypeError("Tool endpoint result() must return a ToolResultResponse")
|
|
816
821
|
if response.status == "available":
|
|
817
822
|
status = await endpoint.status(key)
|
|
818
823
|
if not isinstance(status, ToolExecutionStatus):
|
|
819
824
|
raise TypeError(
|
|
820
|
-
"
|
|
825
|
+
"Tool endpoint status() must return a ToolExecutionStatus"
|
|
821
826
|
)
|
|
822
827
|
await self._record_terminal(
|
|
823
828
|
key,
|
|
@@ -830,24 +835,28 @@ class ToolEndpointHandler:
|
|
|
830
835
|
async def _handle_control(
|
|
831
836
|
self,
|
|
832
837
|
request: ToolEnvelope,
|
|
833
|
-
endpoint: ActionToolEndpoint,
|
|
838
|
+
endpoint: ActionToolEndpoint | SessionToolEndpoint,
|
|
834
839
|
key: ToolExecutionKey,
|
|
835
840
|
) -> ToolEnvelope:
|
|
836
841
|
command, reason = control_request_from_payload(request.payload)
|
|
837
|
-
|
|
838
|
-
|
|
842
|
+
semantics = self._operation_descriptors[cast(str, request.operation)].semantics
|
|
843
|
+
if command == "cancel" and semantics == "action":
|
|
844
|
+
response = await cast(ActionToolEndpoint, endpoint).cancel(key, reason)
|
|
845
|
+
elif command == "stop" and semantics == "session":
|
|
846
|
+
response = await cast(SessionToolEndpoint, endpoint).stop(key, reason)
|
|
839
847
|
else:
|
|
840
|
-
response =
|
|
841
|
-
|
|
842
|
-
|
|
843
|
-
|
|
844
|
-
)
|
|
845
|
-
|
|
846
|
-
|
|
847
|
-
|
|
848
|
-
|
|
849
|
-
|
|
850
|
-
|
|
848
|
+
response = ToolControlResponse(command=command, status="unsupported")
|
|
849
|
+
return make_control_response_envelope(response, request)
|
|
850
|
+
if not isinstance(response, ToolControlResponse):
|
|
851
|
+
raise TypeError(
|
|
852
|
+
f"Tool endpoint {command}() must return a ToolControlResponse"
|
|
853
|
+
)
|
|
854
|
+
if response.command != command:
|
|
855
|
+
raise ToolProtocolError(
|
|
856
|
+
"FORGE_PROTOCOL_CORRELATION_MISMATCH",
|
|
857
|
+
"provider control response command does not match request",
|
|
858
|
+
path="payload.response.command",
|
|
859
|
+
)
|
|
851
860
|
return make_control_response_envelope(response, request)
|
|
852
861
|
|
|
853
862
|
async def dispatch(
|
|
@@ -861,11 +870,6 @@ class ToolEndpointHandler:
|
|
|
861
870
|
|
|
862
871
|
operation_name = cast(str, request.operation)
|
|
863
872
|
operation_descriptor = self._operation_descriptors[operation_name]
|
|
864
|
-
if operation_descriptor.semantics == "session":
|
|
865
|
-
raise NotImplementedError(
|
|
866
|
-
f"ToolEndpointHandler does not yet handle session operation "
|
|
867
|
-
f"{operation_name!r}"
|
|
868
|
-
)
|
|
869
873
|
|
|
870
874
|
try:
|
|
871
875
|
validate_message_envelope(request)
|
|
@@ -875,19 +879,22 @@ class ToolEndpointHandler:
|
|
|
875
879
|
if request.message_type == "tool.invoke.request":
|
|
876
880
|
if operation_descriptor.semantics == "query":
|
|
877
881
|
return await self._handle_query_invoke(request, operation_name)
|
|
878
|
-
return await self.
|
|
882
|
+
return await self._handle_start_invoke(
|
|
879
883
|
request,
|
|
880
884
|
operation_name,
|
|
881
885
|
event_sink,
|
|
882
886
|
)
|
|
883
|
-
if operation_descriptor.semantics
|
|
887
|
+
if operation_descriptor.semantics not in ("action", "session"):
|
|
884
888
|
raise ToolProtocolError(
|
|
885
889
|
"FORGE_PROTOCOL_UNSUPPORTED_OPERATION",
|
|
886
890
|
"Query operations do not support status, result, or control requests",
|
|
887
891
|
path="operation",
|
|
888
892
|
)
|
|
889
893
|
|
|
890
|
-
endpoint = cast(
|
|
894
|
+
endpoint = cast(
|
|
895
|
+
ActionToolEndpoint | SessionToolEndpoint,
|
|
896
|
+
self._implementations[operation_name],
|
|
897
|
+
)
|
|
891
898
|
key = self._execution_key(request)
|
|
892
899
|
try:
|
|
893
900
|
if request.message_type == "tool.status.request":
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|
|
File without changes
|