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.
@@ -1,11 +1,11 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: forge-tool
3
- Version: 0.1.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>=1.2.0,<2 ; extra == 'dora'
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 | **Not implemented** |
39
- | Optional Arrow/Dora binding | Implemented | Implemented | **Not implemented** |
38
+ | `ToolEndpointHandler` execution | Implemented | Implemented | Implemented |
39
+ | Optional Arrow/Dora binding | Implemented | Implemented | Implemented |
40
40
 
41
- “Session implemented” currently means its model, descriptor semantics, structural SPI,
42
- and generic Wire shapes exist. `ToolEndpointHandler.dispatch()` does not execute a
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 handling
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 `0.1.0` from PyPI:
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 status and
155
- result, optional cancellation, and low-rate events. It may instead return an initial
156
- terminal `ToolResult` when completion was established during `start()`, including terminal
157
- `unknown` when dispatch may have begun but acceptance cannot be established.
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 currently enforces descriptor `max_concurrency` only for Action admission.
278
- It also validates but does not enforce `ToolContext.deadline_ms`; timeout ownership
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 and Action invoke/status/result/control. Response is first in the returned tuple. Session is not implemented. |
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 uses `cancel`; `stop` is returned as `unsupported`. Session will use `stop` when
292
- its handler path is implemented.
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 handle_action_input(action_input_arrow_value) -> None:
334
- await binding.dispatch_input(action_input_arrow_value)
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-v0.1.0/interfaces/forge_tool/README.md)
429
- - [Architecture](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v0.1.0/interfaces/forge_tool/ARCHITECTURE.md)
430
- - [ToolEndpoint Wire protocol](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v0.1.0/interfaces/forge_tool/PROTOCOL.md)
431
- - [Canonical `ToolMessage` Arrow schema](https://github.com/Forgelab-Robotics/forge/blob/forge-msgs-v1.2.0/interfaces/forge_msgs/tool.v1.yaml)
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-v0.1.0/LICENSE).
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 | **Not implemented** |
27
- | Optional Arrow/Dora binding | Implemented | Implemented | **Not implemented** |
26
+ | `ToolEndpointHandler` execution | Implemented | Implemented | Implemented |
27
+ | Optional Arrow/Dora binding | Implemented | Implemented | Implemented |
28
28
 
29
- “Session implemented” currently means its model, descriptor semantics, structural SPI,
30
- and generic Wire shapes exist. `ToolEndpointHandler.dispatch()` does not execute a
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 handling
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 `0.1.0` from PyPI:
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 status and
143
- result, optional cancellation, and low-rate events. It may instead return an initial
144
- terminal `ToolResult` when completion was established during `start()`, including terminal
145
- `unknown` when dispatch may have begun but acceptance cannot be established.
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 currently enforces descriptor `max_concurrency` only for Action admission.
266
- It also validates but does not enforce `ToolContext.deadline_ms`; timeout ownership
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 and Action invoke/status/result/control. Response is first in the returned tuple. Session is not implemented. |
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 uses `cancel`; `stop` is returned as `unsupported`. Session will use `stop` when
280
- its handler path is implemented.
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 handle_action_input(action_input_arrow_value) -> None:
322
- await binding.dispatch_input(action_input_arrow_value)
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-v0.1.0/interfaces/forge_tool/README.md)
417
- - [Architecture](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v0.1.0/interfaces/forge_tool/ARCHITECTURE.md)
418
- - [ToolEndpoint Wire protocol](https://github.com/Forgelab-Robotics/forge/blob/forge-tool-v0.1.0/interfaces/forge_tool/PROTOCOL.md)
419
- - [Canonical `ToolMessage` Arrow schema](https://github.com/Forgelab-Robotics/forge/blob/forge-msgs-v1.2.0/interfaces/forge_msgs/tool.v1.yaml)
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-v0.1.0/LICENSE).
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.1.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>=1.2.0,<2"]
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 response and
315
- buffered events through that same sink, awaiting the response publication before
316
- opening the late-event barrier, and returns an empty tuple. Other request types
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
- action_invoke = (
336
+ start_invoke = (
337
337
  request.message_type == "tool.invoke.request"
338
- and operation_descriptor.semantics == "action"
338
+ and operation_descriptor.semantics in ("action", "session")
339
339
  )
340
- if action_invoke and self._event_sink is None:
340
+ if start_invoke and self._event_sink is None:
341
341
  raise RuntimeError(
342
- "Action dispatch requires an asynchronous event_sink publisher"
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
- "Action response publication failed; event was not published"
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("Action event publisher is unavailable")
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 action_invoke else None,
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 action_invoke:
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("Action event publisher is unavailable")
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 dispatch_input"
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 Action attempt."""
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 Action event was emitted after terminal event progression closed",
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
- "Action emitted more than "
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
- "Action emitted after acceptance without an asynchronous event sink"
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 remain the
226
- authority for business status, result, and control decisions. Session execution is
227
- intentionally deferred.
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("Action admission permit count became negative")
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("ActionToolEndpoint.result() must return a ToolResultResponse")
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("ActionToolEndpoint.result() must return a ToolResultResponse")
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("Action event has no execution record")
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 _handle_action_invoke(
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(ActionToolEndpoint, self._implementations[operation_name])
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("Action execution record became ready without an outcome")
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("ActionToolEndpoint.start() must return a ToolAccepted")
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._resolve_failed_action_start(record, emitter))
696
+ await asyncio.shield(self._finish_unknown(record, emitter))
692
697
  raise
693
698
  except Exception:
694
- outcome = await self._resolve_failed_action_start(record, emitter)
695
- return (make_invoke_response_envelope(outcome, request),)
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 _resolve_failed_action_start(
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
- "Action start failed after dispatch; the execution outcome "
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
- return unknown
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 dispatch"
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("ActionToolEndpoint.status() must return a ToolExecutionStatus")
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("ActionToolEndpoint.result() must return a ToolResultResponse")
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
- "ActionToolEndpoint.status() must return a ToolExecutionStatus"
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
- if command != "cancel":
838
- response = ToolControlResponse(command=command, status="unsupported")
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 = await endpoint.cancel(key, reason)
841
- if not isinstance(response, ToolControlResponse):
842
- raise TypeError(
843
- "ActionToolEndpoint.cancel() must return a ToolControlResponse"
844
- )
845
- if response.command != command:
846
- raise ToolProtocolError(
847
- "FORGE_PROTOCOL_CORRELATION_MISMATCH",
848
- "provider control response command does not match request",
849
- path="payload.response.command",
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._handle_action_invoke(
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 != "action":
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(ActionToolEndpoint, self._implementations[operation_name])
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