continuum-task-server-sdk 0.0.9__tar.gz → 0.1.0__tar.gz

{continuum_task_server_sdk-0.0.9 → continuum_task_server_sdk-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: continuum-task-server-sdk
-Version: 0.0.9
+Version: 0.1.0
 Summary: Python SDK for the Continuum Task Server
 Project-URL: Homepage, https://github.com/ContinuumWorkflow/continuum-task-server-sdk-python
 Project-URL: Issues, https://github.com/ContinuumWorkflow/continuum-task-server-sdk-python/issues
@@ -19,6 +19,7 @@ Classifier: Topic :: Software Development :: Libraries
 Requires-Python: >=3.10
 Requires-Dist: httpx<1.0,>=0.27
 Requires-Dist: pydantic<3.0,>=2.6
+Requires-Dist: websocket-client<2.0,>=1.8
 Provides-Extra: dev
 Requires-Dist: pytest-cov>=5.0; extra == 'dev'
 Requires-Dist: pytest>=8.0; extra == 'dev'
@@ -30,8 +31,9 @@ Description-Content-Type: text/markdown
 
 Python client for the [Continuum](https://github.com/ContinuumWorkflow) task server. Designed so a 20-line script can stand up a worker that claims queue items, runs your code, and reports results.
 
-- **`TaskServer`** — decorator-based worker loop: claim, heartbeat **while the handler runs**, status updates, backoff, graceful shutdown. Long-running claims (`auto_complete=False`) need **your** heartbeat loop (documented below).
+- **`TaskServer`** — decorator-based worker loop: claim, heartbeat **while the handler runs**, status updates, backoff, graceful shutdown. Defaults to HTTP polling; set ``transport="websocket"`` (or ``CONTINUUM_TRANSPORT=websocket`` in the example) to claim from STOMP ``work.available`` hints instead.
 - **`ContinuumClient`** — thin pythonic client over the management + queue REST APIs (task types, task items, versions, queue, content store).
+- **`ContinuumWebSocketClient`** — synchronous STOMP-over-WebSocket client for the worker hot path (enqueue, claim, heartbeat, status, ``subscribeWork``, durable ``subscribeWait`` / ``ackEvent``).
 
 Requires Python 3.10+.
 
@@ -63,19 +65,24 @@ server = TaskServer(
     api_key=os.environ["CONTINUUM_API_KEY"],
 )
 
+
 @server.task("echo")
 def echo(item):
     return {"echoed": item.input_data_json}
 
+
 @server.task("greet")
 def greet(item):
     name = (item.input_data_json or {}).get("name", "world")
     return {"message": f"hello, {name}"}
 
+
 if __name__ == "__main__":
     server.run()
 ```
 
+Set `CONTINUUM_TRANSPORT=websocket` (and enable Queue API WebSockets) to replace polling with STOMP wake-ups. HTTP polling remains the default.
+
 Run it. The server polls `/api/queue/claim` for `echo` and `greet`, claims items as they become available, runs your handler in a thread, heartbeats while it runs, and:
 
 - **Handler returns** a value → queue item marked `ENDED`, return value JSON-encoded as `outputData` (default `auto_complete=True`).
@@ -95,6 +102,7 @@ def wait_for_mail(item):
     db.insert_outstanding(queue_item_id=str(item.id), payload=item.input_data_json)
     # Returns without ENDED — no background heartbeat from TaskServer
 
+
 # Elsewhere: each time you poll your DB for outstanding work (including after restart):
 for row in db.outstanding_rows():
     server.client.queue.heartbeat(row.queue_item_id)
@@ -110,11 +118,12 @@ Standalone process (no `TaskServer`): build a `ContinuumClient` with the worker
 TaskServer(
     base_url="http://localhost:8080",
     api_key="...",
-    max_workers=4,            # thread pool size across all tasks
-    poll_interval=1.0,        # initial poll delay (backs off when idle)
-    max_poll_interval=5.0,    # max idle poll delay
+    max_workers=4,  # thread pool size across all tasks
+    poll_interval=1.0,  # initial poll delay (backs off when idle)
+    max_poll_interval=5.0,  # max idle poll delay
     heartbeat_interval=15.0,  # how often to call /heartbeat per running task
-    shutdown_timeout=30.0,    # how long to wait for handlers during shutdown
+    shutdown_timeout=30.0,  # how long to wait for handlers during shutdown
+    transport="http",  # "websocket" uses STOMP; httpx transports still accepted
 )
 ```
 
@@ -122,8 +131,7 @@ Per-task concurrency limit:
 
 ```python
 @server.task("docker-run", concurrency=2)
-def run_docker(item):
-    ...
+def run_docker(item): ...
 ```
 
 Handler signature: `def handler(item: QueueItem) -> dict | list | str | None`. Inside, you have:
@@ -163,9 +171,44 @@ with ContinuumClient(base_url="http://localhost:8080", api_key="...") as client:
 
 `input_data` / `output_data` accept `dict` / `list` / `str` / `None`; non-string values are JSON-encoded for you.
 
+## WebSocket / STOMP
+
+The Queue API worker socket is native STOMP at `/ws/queue` (API-key handshake, no SockJS/JWT). `http://` base URLs become `ws://`; `https://` becomes `wss://`.
+
+```python
+from continuum_task_server import ContinuumWebSocketClient, TaskStatus, WaitMode
+
+with ContinuumWebSocketClient(base_url, api_key) as queue:
+    queue.subscribe_work("echo")
+    hint = queue.next_event(timeout=30)  # work.available is a hint, not a reservation
+    item = queue.claim("echo")  # None if another worker won
+    queue.heartbeat(item.id)
+    wait = queue.subscribe_wait(
+        "run-42",
+        mode=WaitMode.EACH,
+        queue_item_ids=[item.id],
+    )
+    # Or create the child and wait in one transaction:
+    # created = queue.enqueue_and_subscribe_wait(
+    #     task_name="echo", subscriber_id="run-42", mode=WaitMode.EACH, input_data={"hello": "world"},
+    # )
+    queue.update_status(item.id, TaskStatus.ENDED, output_data={"ok": True})
+    completed = queue.next_event(timeout=30)  # queue.completed; dedupe by event_id
+    queue.ack_event("run-42", completed.event_id)
+    queue.unsubscribe_work("echo")
+```
+
+- **TaskServer WebSocket mode** uses this client for subscribe / claim / heartbeat / status. There is no HTTP fallback poll; recovery is reconnect + resubscribe. The API also checks PostgreSQL at subscribe time and periodically for connected sessions.
+- **Reconnect** restores `/user/queue/replies` and `/user/queue/events`, every `subscribeWork` task name, and every durable `subscriberId` via bind-only `subscribeWait` (replays unacked completions from PostgreSQL).
+- **Acks are explicit.** Do not assume the SDK acked a delivery. Completions are at-least-once; ignore duplicate `eventId`s.
+- **Claim and enqueue are not retried** if the socket drops after the frame is written. The reply may have been lost; check queue state instead of sending the same command again. Heartbeat and status wait for reconnect and retry.
+- **Durable waits** use a client-chosen `subscriberId` scoped to the API-key owner. `EACH` delivers per terminal item; `ALL` delivers one summary. Bind with only `subscriberId` after reconnect.
+
+See `examples/websocket_bindings.py` and `examples/wait_subscriber.py`.
+
 ### Errors
 
-All API failures raise `ContinuumError` or a specific subclass: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ServerError`. Each carries `status_code` and `body`.
+All API failures raise `ContinuumError` or a specific subclass: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `ServerError`, plus WebSocket `TransportError`, `ProtocolError`, `CommandTimeoutError`, and `AmbiguousCommandError`. Each carries `status_code` and `body` when they come from the API.
 
 ```python
 from continuum_task_server import ContinuumClient, NotFoundError
@@ -202,7 +245,7 @@ ruff format --check .
 pytest
 ```
 
-Tests use [`respx`](https://lundberg.github.io/respx/) to mock the httpx transport — no live server required.
+Tests use [`respx`](https://lundberg.github.io/respx/) to mock the httpx transport and an in-memory WebSocket for STOMP tests — no live server required.
 
 ## Versioning
 

{continuum_task_server_sdk-0.0.9 → continuum_task_server_sdk-0.1.0}/README.md

@@ -2,8 +2,9 @@
 
 Python client for the [Continuum](https://github.com/ContinuumWorkflow) task server. Designed so a 20-line script can stand up a worker that claims queue items, runs your code, and reports results.
 
-- **`TaskServer`** — decorator-based worker loop: claim, heartbeat **while the handler runs**, status updates, backoff, graceful shutdown. Long-running claims (`auto_complete=False`) need **your** heartbeat loop (documented below).
+- **`TaskServer`** — decorator-based worker loop: claim, heartbeat **while the handler runs**, status updates, backoff, graceful shutdown. Defaults to HTTP polling; set ``transport="websocket"`` (or ``CONTINUUM_TRANSPORT=websocket`` in the example) to claim from STOMP ``work.available`` hints instead.
 - **`ContinuumClient`** — thin pythonic client over the management + queue REST APIs (task types, task items, versions, queue, content store).
+- **`ContinuumWebSocketClient`** — synchronous STOMP-over-WebSocket client for the worker hot path (enqueue, claim, heartbeat, status, ``subscribeWork``, durable ``subscribeWait`` / ``ackEvent``).
 
 Requires Python 3.10+.
 
@@ -35,19 +36,24 @@ server = TaskServer(
     api_key=os.environ["CONTINUUM_API_KEY"],
 )
 
+
 @server.task("echo")
 def echo(item):
     return {"echoed": item.input_data_json}
 
+
 @server.task("greet")
 def greet(item):
     name = (item.input_data_json or {}).get("name", "world")
     return {"message": f"hello, {name}"}
 
+
 if __name__ == "__main__":
     server.run()
 ```
 
+Set `CONTINUUM_TRANSPORT=websocket` (and enable Queue API WebSockets) to replace polling with STOMP wake-ups. HTTP polling remains the default.
+
 Run it. The server polls `/api/queue/claim` for `echo` and `greet`, claims items as they become available, runs your handler in a thread, heartbeats while it runs, and:
 
 - **Handler returns** a value → queue item marked `ENDED`, return value JSON-encoded as `outputData` (default `auto_complete=True`).
@@ -67,6 +73,7 @@ def wait_for_mail(item):
     db.insert_outstanding(queue_item_id=str(item.id), payload=item.input_data_json)
     # Returns without ENDED — no background heartbeat from TaskServer
 
+
 # Elsewhere: each time you poll your DB for outstanding work (including after restart):
 for row in db.outstanding_rows():
     server.client.queue.heartbeat(row.queue_item_id)
@@ -82,11 +89,12 @@ Standalone process (no `TaskServer`): build a `ContinuumClient` with the worker
 TaskServer(
     base_url="http://localhost:8080",
     api_key="...",
-    max_workers=4,            # thread pool size across all tasks
-    poll_interval=1.0,        # initial poll delay (backs off when idle)
-    max_poll_interval=5.0,    # max idle poll delay
+    max_workers=4,  # thread pool size across all tasks
+    poll_interval=1.0,  # initial poll delay (backs off when idle)
+    max_poll_interval=5.0,  # max idle poll delay
     heartbeat_interval=15.0,  # how often to call /heartbeat per running task
-    shutdown_timeout=30.0,    # how long to wait for handlers during shutdown
+    shutdown_timeout=30.0,  # how long to wait for handlers during shutdown
+    transport="http",  # "websocket" uses STOMP; httpx transports still accepted
 )
 ```
 
@@ -94,8 +102,7 @@ Per-task concurrency limit:
 
 ```python
 @server.task("docker-run", concurrency=2)
-def run_docker(item):
-    ...
+def run_docker(item): ...
 ```
 
 Handler signature: `def handler(item: QueueItem) -> dict | list | str | None`. Inside, you have:
@@ -135,9 +142,44 @@ with ContinuumClient(base_url="http://localhost:8080", api_key="...") as client:
 
 `input_data` / `output_data` accept `dict` / `list` / `str` / `None`; non-string values are JSON-encoded for you.
 
+## WebSocket / STOMP
+
+The Queue API worker socket is native STOMP at `/ws/queue` (API-key handshake, no SockJS/JWT). `http://` base URLs become `ws://`; `https://` becomes `wss://`.
+
+```python
+from continuum_task_server import ContinuumWebSocketClient, TaskStatus, WaitMode
+
+with ContinuumWebSocketClient(base_url, api_key) as queue:
+    queue.subscribe_work("echo")
+    hint = queue.next_event(timeout=30)  # work.available is a hint, not a reservation
+    item = queue.claim("echo")  # None if another worker won
+    queue.heartbeat(item.id)
+    wait = queue.subscribe_wait(
+        "run-42",
+        mode=WaitMode.EACH,
+        queue_item_ids=[item.id],
+    )
+    # Or create the child and wait in one transaction:
+    # created = queue.enqueue_and_subscribe_wait(
+    #     task_name="echo", subscriber_id="run-42", mode=WaitMode.EACH, input_data={"hello": "world"},
+    # )
+    queue.update_status(item.id, TaskStatus.ENDED, output_data={"ok": True})
+    completed = queue.next_event(timeout=30)  # queue.completed; dedupe by event_id
+    queue.ack_event("run-42", completed.event_id)
+    queue.unsubscribe_work("echo")
+```
+
+- **TaskServer WebSocket mode** uses this client for subscribe / claim / heartbeat / status. There is no HTTP fallback poll; recovery is reconnect + resubscribe. The API also checks PostgreSQL at subscribe time and periodically for connected sessions.
+- **Reconnect** restores `/user/queue/replies` and `/user/queue/events`, every `subscribeWork` task name, and every durable `subscriberId` via bind-only `subscribeWait` (replays unacked completions from PostgreSQL).
+- **Acks are explicit.** Do not assume the SDK acked a delivery. Completions are at-least-once; ignore duplicate `eventId`s.
+- **Claim and enqueue are not retried** if the socket drops after the frame is written. The reply may have been lost; check queue state instead of sending the same command again. Heartbeat and status wait for reconnect and retry.
+- **Durable waits** use a client-chosen `subscriberId` scoped to the API-key owner. `EACH` delivers per terminal item; `ALL` delivers one summary. Bind with only `subscriberId` after reconnect.
+
+See `examples/websocket_bindings.py` and `examples/wait_subscriber.py`.
+
 ### Errors
 
-All API failures raise `ContinuumError` or a specific subclass: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `ServerError`. Each carries `status_code` and `body`.
+All API failures raise `ContinuumError` or a specific subclass: `BadRequestError`, `UnauthorizedError`, `ForbiddenError`, `NotFoundError`, `ConflictError`, `RateLimitError`, `ServerError`, plus WebSocket `TransportError`, `ProtocolError`, `CommandTimeoutError`, and `AmbiguousCommandError`. Each carries `status_code` and `body` when they come from the API.
 
 ```python
 from continuum_task_server import ContinuumClient, NotFoundError
@@ -174,7 +216,7 @@ ruff format --check .
 pytest
 ```
 
-Tests use [`respx`](https://lundberg.github.io/respx/) to mock the httpx transport — no live server required.
+Tests use [`respx`](https://lundberg.github.io/respx/) to mock the httpx transport and an in-memory WebSocket for STOMP tests — no live server required.
 
 ## Versioning
 

continuum_task_server_sdk-0.1.0/continuum_task_server/__init__.py

@@ -0,0 +1,74 @@
+"""Continuum Task Server SDK for Python."""
+
+from __future__ import annotations
+
+from .client import ContinuumClient
+from .exceptions import (
+    AmbiguousCommandError,
+    BadRequestError,
+    CommandTimeoutError,
+    ConflictError,
+    ContinuumError,
+    ForbiddenError,
+    NotFoundError,
+    ProtocolError,
+    RateLimitError,
+    ServerError,
+    TransportError,
+    UnauthorizedError,
+)
+from .models import (
+    Content,
+    EnqueueAndSubscribeWaitResult,
+    EventAckResult,
+    QueueEvent,
+    QueueEventType,
+    QueueItem,
+    TaskItem,
+    TaskItemVersion,
+    TaskStatus,
+    TaskType,
+    TransportMode,
+    WaitMode,
+    WaitSubscriptionResult,
+    WaitTargetStatus,
+    WorkSubscriptionResult,
+)
+from .server import TaskServer
+from .websocket import ContinuumWebSocketClient, WebSocketOptions
+
+__all__ = [
+    "AmbiguousCommandError",
+    "BadRequestError",
+    "CommandTimeoutError",
+    "ConflictError",
+    "Content",
+    "ContinuumClient",
+    "ContinuumError",
+    "ContinuumWebSocketClient",
+    "EnqueueAndSubscribeWaitResult",
+    "EventAckResult",
+    "ForbiddenError",
+    "NotFoundError",
+    "ProtocolError",
+    "QueueEvent",
+    "QueueEventType",
+    "QueueItem",
+    "RateLimitError",
+    "ServerError",
+    "TaskItem",
+    "TaskItemVersion",
+    "TaskServer",
+    "TaskStatus",
+    "TaskType",
+    "TransportError",
+    "TransportMode",
+    "UnauthorizedError",
+    "WaitMode",
+    "WaitSubscriptionResult",
+    "WaitTargetStatus",
+    "WebSocketOptions",
+    "WorkSubscriptionResult",
+]
+
+__version__ = "0.1.0"

continuum_task_server_sdk-0.1.0/continuum_task_server/_stomp.py

@@ -0,0 +1,137 @@
+"""STOMP 1.2 frame codec. Internal."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+NULL = "\x00"
+LF = "\n"
+
+_ESCAPE = {
+    "\\": "\\\\",
+    "\r": "\\r",
+    "\n": "\\n",
+    ":": "\\c",
+}
+_UNESCAPE = {
+    "\\\\": "\\",
+    "\\r": "\r",
+    "\\n": "\n",
+    "\\c": ":",
+}
+
+
+@dataclass
+class StompFrame:
+    command: str
+    headers: dict[str, str] = field(default_factory=dict)
+    body: str = ""
+
+
+def encode_frame(frame: StompFrame) -> str:
+    """Serialize a STOMP frame including the terminating NUL."""
+    lines = [frame.command]
+    headers = dict(frame.headers)
+    body = frame.body or ""
+    if body and "content-length" not in {k.lower() for k in headers}:
+        headers["content-length"] = str(len(body.encode("utf-8")))
+    for key, value in headers.items():
+        lines.append(f"{_escape(key)}:{_escape(value)}")
+    return LF.join(lines) + LF + LF + body + NULL
+
+
+def encode_heartbeat() -> str:
+    return LF
+
+
+def _escape(text: str) -> str:
+    out: list[str] = []
+    for ch in text:
+        out.append(_ESCAPE.get(ch, ch))
+    return "".join(out)
+
+
+def _unescape(text: str) -> str:
+    out: list[str] = []
+    i = 0
+    while i < len(text):
+        if text[i] == "\\" and i + 1 < len(text):
+            pair = text[i : i + 2]
+            if pair in _UNESCAPE:
+                out.append(_UNESCAPE[pair])
+                i += 2
+                continue
+        out.append(text[i])
+        i += 1
+    return "".join(out)
+
+
+class StompDecoder:
+    """Incremental decoder for one or more STOMP frames, including heartbeats."""
+
+    def __init__(self) -> None:
+        self._buffer = ""
+
+    def feed(self, data: str | bytes) -> list[StompFrame | None]:
+        """Return complete frames. ``None`` entries are heartbeat newlines."""
+        if isinstance(data, bytes):
+            chunk = data.decode("utf-8")
+        else:
+            chunk = data
+        self._buffer += chunk
+        frames: list[StompFrame | None] = []
+        while self._buffer:
+            if self._buffer[0] in "\r\n":
+                if self._buffer.startswith("\r\n"):
+                    self._buffer = self._buffer[2:]
+                else:
+                    self._buffer = self._buffer[1:]
+                frames.append(None)
+                continue
+            nul = self._buffer.find(NULL)
+            if nul < 0:
+                break
+            raw = self._buffer[:nul]
+            self._buffer = self._buffer[nul + 1 :]
+            if raw.startswith("\r\n"):
+                raw = raw[2:]
+            elif raw.startswith("\n"):
+                raw = raw[1:]
+            if raw == "":
+                frames.append(None)
+                continue
+            frames.append(_parse_frame(raw))
+        return frames
+
+
+def _parse_frame(raw: str) -> StompFrame:
+    header_end = raw.find("\n\n")
+    if header_end < 0:
+        header_block = raw
+        body = ""
+    else:
+        header_block = raw[:header_end]
+        body = raw[header_end + 2 :]
+    lines = header_block.split("\n")
+    command = lines[0].strip()
+    headers: dict[str, str] = {}
+    content_length: int | None = None
+    for line in lines[1:]:
+        if not line:
+            continue
+        idx = line.find(":")
+        if idx < 0:
+            continue
+        key = _unescape(line[:idx])
+        value = _unescape(line[idx + 1 :])
+        if key.lower() == "content-length":
+            try:
+                content_length = int(value)
+            except ValueError:
+                content_length = None
+        if key not in headers:
+            headers[key] = value
+    if content_length is not None:
+        encoded = body.encode("utf-8")
+        body = encoded[:content_length].decode("utf-8")
+    return StompFrame(command=command, headers=headers, body=body)

{continuum_task_server_sdk-0.0.9 → continuum_task_server_sdk-0.1.0}/continuum_task_server/client.py

@@ -145,7 +145,7 @@ class TaskItemVersionsApi:
             }
         )
         return TaskItemVersion.model_validate(
-            self._http.patch_json(f"{self._PATH}/{task_item_id}/versions/{version_id}", body)
+            self._http.post_json(f"{self._PATH}/versions/{version_id}", body)
         )
 
     def deactivate(self, task_item_id: UUID | str, version_id: UUID | str) -> TaskItemVersion:

{continuum_task_server_sdk-0.0.9 → continuum_task_server_sdk-0.1.0}/continuum_task_server/exceptions.py

@@ -25,7 +25,7 @@ class ContinuumError(Exception):
 
 
 class BadRequestError(ContinuumError):
-    """HTTP 400."""
+    """HTTP / command 400."""
 
 
 class UnauthorizedError(ContinuumError):
@@ -44,21 +44,46 @@ class ConflictError(ContinuumError):
     """HTTP 409."""
 
 
+class RateLimitError(ContinuumError):
+    """HTTP / command 429."""
+
+
 class ServerError(ContinuumError):
     """HTTP 5xx."""
 
 
+class TransportError(ContinuumError):
+    """WebSocket / STOMP connection failed or dropped."""
+
+
+class ProtocolError(ContinuumError):
+    """Malformed STOMP frame or unexpected protocol response."""
+
+
+class CommandTimeoutError(ContinuumError):
+    """Timed out waiting for a correlated command reply."""
+
+
+class AmbiguousCommandError(TransportError):
+    """A non-idempotent command was sent but its reply was lost.
+
+    The server may or may not have applied the mutation (claim / enqueue).
+    Do not retry with the same intent without checking queue state.
+    """
+
+
 _STATUS_TO_EXC: dict[int, type[ContinuumError]] = {
     400: BadRequestError,
     401: UnauthorizedError,
     403: ForbiddenError,
     404: NotFoundError,
     409: ConflictError,
+    429: RateLimitError,
 }
 
 
 def error_for_status(status_code: int, body: str) -> ContinuumError:
-    """Build the appropriate exception for a non-2xx HTTP response."""
+    """Build the appropriate exception for a non-2xx HTTP or command status."""
     exc_cls = _STATUS_TO_EXC.get(status_code)
     if exc_cls is None:
         if 500 <= status_code < 600:

{continuum_task_server_sdk-0.0.9 → continuum_task_server_sdk-0.1.0}/continuum_task_server/models.py

@@ -111,3 +111,87 @@ class Content(_Base):
 
     def as_text(self, encoding: str = "utf-8") -> str:
         return self.data.decode(encoding)
+
+
+class TransportMode(str, Enum):
+    """How ``TaskServer`` obtains work."""
+
+    HTTP = "http"
+    WEBSOCKET = "websocket"
+
+
+class WaitMode(str, Enum):
+    """Durable completion-wait mode."""
+
+    EACH = "EACH"
+    ALL = "ALL"
+
+
+class QueueEventType(str, Enum):
+    """Wire ``eventType`` values on ``/user/queue/events``."""
+
+    WORK_AVAILABLE = "work.available"
+    COMPLETED = "queue.completed"
+
+
+class WaitTargetStatus(_Base):
+    """Per-item outcome on an ALL-mode completion summary."""
+
+    queue_item_id: UUID = Field(alias="queueItemId")
+    status: TaskStatus | str | None = None
+
+
+class QueueEvent(_Base):
+    """Compact ``work.available`` hint or durable ``queue.completed`` delivery."""
+
+    event_id: UUID = Field(alias="eventId")
+    event_version: int = Field(default=1, alias="eventVersion")
+    event_type: QueueEventType = Field(alias="eventType")
+    occurred_at: datetime | None = Field(default=None, alias="occurredAt")
+    queue_item_id: UUID | None = Field(default=None, alias="queueItemId")
+    organization_id: UUID | None = Field(default=None, alias="organizationId")
+    task_type_id: UUID | None = Field(default=None, alias="taskTypeId")
+    task_name: str | None = Field(default=None, alias="taskName")
+    status: TaskStatus | None = None
+    subscription_id: UUID | None = Field(default=None, alias="subscriptionId")
+    correlation: str | None = None
+    wait_mode: WaitMode | None = Field(default=None, alias="waitMode")
+    targets: list[WaitTargetStatus] | None = None
+
+
+class WorkSubscriptionResult(_Base):
+    """Result of ``subscribeWork`` / ``unsubscribeWork``."""
+
+    task_name: str | None = Field(default=None, alias="taskName")
+    subscribed: bool | None = None
+
+
+class WaitSubscriptionResult(_Base):
+    """Result of ``subscribeWait`` / bind-only replay."""
+
+    subscription_id: UUID | None = Field(default=None, alias="subscriptionId")
+    subscriber_id: str | None = Field(default=None, alias="subscriberId")
+    wait_mode: WaitMode | None = Field(default=None, alias="waitMode")
+    pending_count: int = Field(default=0, alias="pendingCount")
+    closed: bool = False
+    subscribed: bool | None = None
+
+
+class EventAckResult(_Base):
+    """Result of ``ackEvent``."""
+
+    subscription_id: UUID | None = Field(default=None, alias="subscriptionId")
+    closed: bool = False
+    acked: bool = True
+
+
+class EnqueueAndSubscribeWaitResult(_Base):
+    """Combined result of ``enqueueAndSubscribeWait``."""
+
+    item: QueueItem
+    subscription_id: UUID | None = Field(default=None, alias="subscriptionId")
+    subscriber_id: str | None = Field(default=None, alias="subscriberId")
+    wait_mode: WaitMode | None = Field(default=None, alias="waitMode")
+    pending_count: int = Field(default=0, alias="pendingCount")
+    closed: bool = False
+    subscribed: bool | None = None