grctl-sdk-python 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

grctl/client/client.py

@@ -4,6 +4,8 @@ Provides a simple interface for interacting with workflows.
 """
 
 import logging
+import secrets
+import socket
 from datetime import UTC, datetime, timedelta
 from typing import Any, TypeVar, overload
 
@@ -12,7 +14,12 @@ from ulid import ULID
 
 from grctl.models import DescribeCmd, GrctlAPIResponse, HistoryEvent, RunInfo
 from grctl.models.command import CmdKind, Command
-from grctl.models.errors import WorkflowAlreadyRunningError, WorkflowError, WorkflowNotFoundError
+from grctl.models.errors import (
+    WorkflowAlreadyRunningError,
+    WorkflowError,
+    WorkflowNotFoundError,
+    WorkflowTypeNotRegisteredError,
+)
 from grctl.nats.connection import Connection
 from grctl.nats.history_fetch import fetch_run_history
 from grctl.worker.codec import CodecRegistry
@@ -24,6 +31,7 @@ _T = TypeVar("_T")
 
 ErrWorkflowAlreadyRunningCode = 4001
 ErrWorkflowRunNotFoundCode = 4002
+ErrWorkflowTypeNotRegisteredCode = 4004
 
 
 class Client:
@@ -32,6 +40,7 @@ class Client:
     def __init__(self, connection: Connection, codec: CodecRegistry | None = None) -> None:
         self._connection = connection
         self._codec = codec or CodecRegistry()
+        self.id = f"c_{secrets.token_hex(4)}@{socket.gethostname()}"
 
     async def describe(self, wf_id: str) -> RunInfo:
         """Describe the latest run for a workflow ID."""
@@ -40,6 +49,7 @@ class Client:
             kind=CmdKind.run_describe,
             timestamp=datetime.now(UTC),
             msg=DescribeCmd(wf_id=wf_id),
+            sender_id=self.id,
         )
         # Use a routing-only RunInfo — publish_cmd only needs wf_id for subject routing.
         routing_info = RunInfo(id="", wf_type="", wf_id=wf_id)
@@ -103,6 +113,7 @@ class Client:
             payload=None,
             connection=self._connection,
             codec=self._codec,
+            sender_id=self.id,
         )
         await handle.attach()
         return handle
@@ -145,6 +156,7 @@ class Client:
             connection=self._connection,
             codec=self._codec,
             return_type=return_type,
+            sender_id=self.id,
         )
 
         # Start the workflow future (subscribe to events and publish run command)
@@ -156,6 +168,8 @@ class Client:
             error_code = response.error.code if response.error else 0
             if error_code == ErrWorkflowAlreadyRunningCode:
                 raise WorkflowAlreadyRunningError(f"workflow '{id}' already has an active run: {error_msg}")
+            if error_code == ErrWorkflowTypeNotRegisteredCode:
+                raise WorkflowTypeNotRegisteredError(f"no worker registered for workflow type '{type}': {error_msg}")
             raise WorkflowError(f"start_workflow failed (code={error_code}): {error_msg}")
 
         return handle

grctl/models/__init__.py

@@ -11,7 +11,11 @@ from grctl.models.command import (
     Command,
     DescribeCmd,
     EventCmd,
+    EventDef,
+    RegisterCmd,
     StartCmd,
+    TerminateCmd,
+    WorkflowTypeDef,
     command_decoder,
     command_encoder,
 )
@@ -26,6 +30,7 @@ from grctl.models.directive import (
     FailStep,
     Start,
     Step,
+    StepPickedUp,
     StepResult,
     Wait,
     directive_decoder,
@@ -40,11 +45,13 @@ from grctl.models.history import (
     ParentEventSent,
     RandomRecorded,
     RunCancelled,
+    RunCancelReceived,
     RunCompleted,
     RunEvents,
     RunFailed,
     RunScheduled,
     RunStarted,
+    RunTerminated,
     RunTimeout,
     SleepRecorded,
     StepCancelled,
@@ -79,6 +86,10 @@ __all__ = [  # noqa: RUF022
     "CancelCmd",
     "DescribeCmd",
     "EventCmd",
+    "RegisterCmd",
+    "TerminateCmd",
+    "WorkflowTypeDef",
+    "EventDef",
     "CmdKind",
     "command_decoder",
     "command_encoder",
@@ -93,6 +104,7 @@ __all__ = [  # noqa: RUF022
     "Fail",
     "FailStep",
     "Step",
+    "StepPickedUp",
     "StepResult",
     "Wait",
     "directive_decoder",
@@ -105,7 +117,9 @@ __all__ = [  # noqa: RUF022
     "RunCompleted",
     "RunEvents",
     "RunFailed",
+    "RunCancelReceived",
     "RunCancelled",
+    "RunTerminated",
     "RunTimeout",
     "StepEvents",
     "StepStarted",

grctl/models/command.py

@@ -13,6 +13,8 @@ class CmdKind(StrEnum):
     run_describe = "run.describe"
     run_terminate = "run.terminate"
     run_event = "run.event"
+    worker_register = "worker.register"
+    worker_terminate_run = "worker.terminate_run"
 
 
 class StartCmd(msgspec.Struct):
@@ -50,7 +52,41 @@ class TerminateCmd(msgspec.Struct):
     reason: str | None
 
 
-type CommandMessage = StartCmd | EventCmd | CancelCmd | DescribeCmd | TerminateCmd
+class WorkerTerminateRunCmd(msgspec.Struct):
+    """Server→worker signal to cancel a specific in-flight run."""
+
+    run_id: str
+
+
+class EventDef(msgspec.Struct, kw_only=True):
+    """Per-event timeout config carried through registration."""
+
+    name: str
+    timeout_ms: int = 0
+
+
+class WorkflowTypeDef(msgspec.Struct):
+    """Structural definition of one workflow type reported at registration.
+
+    Field names and order mirror the Go WorkflowTypeDef msgpack tags.
+    """
+
+    type: str
+    start_step: str
+    steps: list[str]
+    events: list[EventDef]
+    queries: list[str]
+    start_step_timeout_ms: int = 0
+
+
+class RegisterCmd(msgspec.Struct):
+    """Worker startup sync of its workflow type catalog to the server."""
+
+    worker_id: str
+    types: list[WorkflowTypeDef]
+
+
+type CommandMessage = StartCmd | EventCmd | CancelCmd | DescribeCmd | TerminateCmd | RegisterCmd | WorkerTerminateRunCmd
 
 
 class Command(msgspec.Struct):
@@ -58,6 +94,7 @@ class Command(msgspec.Struct):
     kind: CmdKind
     timestamp: datetime
     msg: CommandMessage
+    sender_id: str = ""
 
 
 # Factory map for kind-based deserialization
@@ -67,6 +104,8 @@ command_factories: dict[str, type] = {
     "run.describe": DescribeCmd,
     "run.terminate": TerminateCmd,
     "run.event": EventCmd,
+    "worker.register": RegisterCmd,
+    "worker.terminate_run": WorkerTerminateRunCmd,
 }
 
 
@@ -80,12 +119,15 @@ class CommandWire(msgspec.Struct):
     k: CmdKind
     m: bytes
     t: datetime
+    s: str = ""
 
 
 def command_encoder(cmd: Command) -> bytes:
     """Encode command to msgpack with compact wire format."""
     if cmd.msg is None:
         raise ValueError("Command message cannot be None")
+    if cmd.sender_id == "":
+        raise ValueError("Command sender ID cannot be empty")
 
     msg_bytes = msgspec.msgpack.encode(cmd.msg)
 
@@ -94,6 +136,7 @@ def command_encoder(cmd: Command) -> bytes:
         k=cmd.kind,
         m=msg_bytes,
         t=cmd.timestamp,
+        s=cmd.sender_id,
     )
 
     return msgspec.msgpack.encode(wire)
@@ -114,4 +157,5 @@ def command_decoder(data: bytes) -> Command:
         kind=wire.k,
         msg=msg,  # ty:ignore[invalid-argument-type]
         timestamp=wire.t,
+        sender_id=wire.s,
     )

grctl/models/directive.py

@@ -92,6 +92,15 @@ class DirectiveKind(StrEnum):
     wait_timeout = "wait_timeout"
     step_result = "step_result"
     fail_step = "fail_step"
+    step_picked_up = "step_picked_up"
+
+
+class StepPickedUp(msgspec.Struct):
+    """Worker directive notifying the server that a step has been picked up for execution."""
+
+    step_name: str
+    worker_id: str
+    timestamp: datetime
 
 
 class StepResult(msgspec.Struct):
@@ -108,7 +117,7 @@ class StepResult(msgspec.Struct):
     duration_ms: int = 0
 
 
-DirectiveMessage = Start | Cancel | Event | Complete | Fail | Step | Wait | StepResult
+DirectiveMessage = Start | Cancel | Event | Complete | Fail | Step | Wait | StepResult | StepPickedUp
 
 
 # Factory map for kind-based deserialization
@@ -121,6 +130,7 @@ directive_factories: dict[str, type[DirectiveMessage]] = {
     "step": Step,
     "wait": Wait,
     "step_result": StepResult,
+    "step_picked_up": StepPickedUp,
 }
 
 

grctl/models/errors.py

@@ -8,3 +8,7 @@ class WorkflowNotFoundError(WorkflowError):
 
 class WorkflowAlreadyRunningError(WorkflowError):
     """Raised when a workflow ID already has an active run."""
+
+
+class WorkflowTypeNotRegisteredError(WorkflowError):
+    """Raised when the server has no registered worker for the requested workflow type."""

grctl/models/history.py

@@ -12,8 +12,9 @@ class HistoryKind(StrEnum):
     run_started = "run.started"
     run_completed = "run.completed"
     run_failed = "run.failed"
-    run_cancel_scheduled = "run.cancel_scheduled"
+    run_cancel_received = "run.cancel_received"
     run_cancelled = "run.cancelled"
+    run_terminated = "run.terminated"
     run_timeout = "run.timeout"
     wait_started = "wait.started"
     wait_timed_out = "wait.timed_out"
@@ -60,8 +61,8 @@ class RunFailed(msgspec.Struct):
     duration_ms: int
 
 
-class RunCancelScheduled(msgspec.Struct):
-    """Workflow cancellation has been scheduled."""
+class RunCancelReceived(msgspec.Struct):
+    """Workflow cancellation received while a step is in-flight; deferred until step completes."""
 
 
 class RunCancelled(msgspec.Struct):
@@ -71,6 +72,13 @@ class RunCancelled(msgspec.Struct):
     duration_ms: int
 
 
+class RunTerminated(msgspec.Struct):
+    """Workflow execution was forcefully terminated."""
+
+    reason: str
+    duration_ms: int
+
+
 class RunTimeout(msgspec.Struct):
     """Workflow execution timed out."""
 
@@ -226,18 +234,21 @@ class ParentEventSent(msgspec.Struct):
     parent_wf_id: str
 
 
-RunEvents = RunCancelScheduled | RunCancelled | RunCompleted | RunFailed | RunScheduled | RunStarted | RunTimeout
+RunEvents = (
+    RunCancelReceived | RunCancelled | RunCompleted | RunFailed | RunScheduled | RunStarted | RunTerminated | RunTimeout
+)
 WaitEvents = WaitStarted | WaitTimedOut | EventReceived
 StepEvents = StepStarted | StepCompleted | StepFailed | StepCancelled | StepTimeout
 TaskEvents = TaskStarted | TaskCompleted | TaskFailed | TaskAttemptFailed | TaskCancelled
 DeterministicEvents = TimestampRecorded | RandomRecorded | UuidRecorded | SleepRecorded
 HistoryEvents = (
-    RunCancelScheduled
+    RunCancelReceived
     | RunCancelled
     | RunCompleted
     | RunFailed
     | RunScheduled
     | RunStarted
+    | RunTerminated
     | RunTimeout
     | StepStarted
     | StepCompleted
@@ -279,8 +290,9 @@ history_factories: dict[str, type] = {
     "run.started": RunStarted,
     "run.completed": RunCompleted,
     "run.failed": RunFailed,
-    "run.cancel_scheduled": RunCancelScheduled,
+    "run.cancel_received": RunCancelReceived,
     "run.cancelled": RunCancelled,
+    "run.terminated": RunTerminated,
     "run.timeout": RunTimeout,
     "wait.started": WaitStarted,
     "wait.timed_out": WaitTimedOut,

grctl/models/run_info.py

@@ -42,6 +42,9 @@ class RunInfo(msgspec.Struct, dict=True, omit_defaults=True):
     parent_wf_id: str | None = None
     parent_wf_type: str | None = None
     parent_run_id: str | None = None
+    # Name of the parent step to trigger when this run reaches a terminal state.
+    # Set only for child runs started with a completion callback.
+    parent_callback_step: str | None = None
 
     # Timing fields
     timeout: int | None = None

grctl/nats/manifest.py

@@ -142,6 +142,13 @@ class NatsManifest:
     def api_listener_pattern(self) -> str:
         return self._subject_pattern("api", "listen")
 
+    def worker_command_subject(self) -> str:
+        return self._subject_pattern("api", "worker")
+
+    def worker_cmd_subject(self, worker_id: str) -> str:
+        pattern = self._subject_pattern("worker_cmd", "publish")
+        return self._substitute_params(pattern, worker_id=worker_id)
+
     def worker_task_filter_subject(self, wf_type: str) -> str:
         pattern = self._subject_pattern("worker_task", "filter")
         return self._substitute_params(pattern, wf_type=wf_type)

grctl/nats/nats_manifest.yaml

@@ -85,6 +85,7 @@ subjects:
     subject_patterns:
       publish: grctl_api.workflow.{wf_id} # Server
       listen: grctl_api.> # Server
+      worker: grctl_api.worker # Worker -> Server commands
 
   worker_task:
     stream: grctl_state
@@ -93,3 +94,10 @@ subjects:
       listen: grctl_worker_task.>
       queue_group: grctl_worker_{wf_type}
       filter: grctl_worker_task.{wf_type}.>
+
+  worker_cmd:
+    # Server -> Worker out-of-band signals. Core NATS request-reply, no stream.
+    stream: null
+    subject_patterns:
+      publish: grctl_worker_cmd.{worker_id}
+      listen: grctl_worker_cmd.{worker_id}

grctl/nats/subscriber.py

@@ -107,6 +107,7 @@ class Subscriber:
             await msg.ack()
         except asyncio.CancelledError:
             logger.info("Task cancelled directive_id=%s", directive.id)
+            await msg.ack()
         except Exception:
             # Fail directive already published by workflow_error_handler inside the runner
             logger.debug("Runner task raised exception directive_id=%s", directive.id)

grctl/worker/__init__.py

@@ -1,8 +1,9 @@
 """Worker module."""
 
+from grctl.worker.child import ChildOutcome
 from grctl.worker.context import Context
 from grctl.worker.store import StoreKeyNotFoundError
 from grctl.worker.task import task
 from grctl.worker.worker import Worker
 
-__all__ = ["Context", "StoreKeyNotFoundError", "Worker", "task"]
+__all__ = ["ChildOutcome", "Context", "StoreKeyNotFoundError", "Worker", "task"]

grctl/worker/child.py

@@ -0,0 +1,40 @@
+from typing import Any
+
+import msgspec
+
+from grctl.models.common import ErrorDetails
+from grctl.models.errors import WorkflowError
+from grctl.models.run_info import RunStatus
+
+
+class ChildOutcome[T](msgspec.Struct):
+    """Terminal outcome of a child workflow, delivered to the parent's on_completed_step.
+
+    A single callback handles both success and failure: check `ok` (or `status`),
+    then read `result` for a completed child or `error` for a failed/cancelled one.
+
+    Parameterize the type to have the result decoded back into the child's return type,
+    e.g. `outcome: ChildOutcome[OrderResult]`. Left bare (`ChildOutcome`), the result
+    stays the raw msgpack builtins the child returned.
+    """
+
+    status: RunStatus
+    result: T | None = None
+    error: ErrorDetails | None = None
+
+    @property
+    def ok(self) -> bool:
+        """True when the child completed successfully."""
+        return self.status == RunStatus.completed
+
+    def unwrap(self) -> Any:
+        """Return the result if the child completed, else raise WorkflowError.
+
+        Lets a parent that only cares about the happy path propagate child failures
+        without inspecting status explicitly.
+        """
+        if self.ok:
+            return self.result
+        message = self.error.message if self.error else f"child workflow {self.status}"
+        error_type = self.error.type if self.error else "WorkflowError"
+        raise WorkflowError(f"{error_type}: {message}")

grctl/worker/context.py

@@ -84,9 +84,6 @@ class NextBuilder:
         )
 
     def wait(self, timeout: timedelta | None = None, on_timeout: StepHandler | None = None) -> Directive:
-        if (timeout is None) != (on_timeout is None):
-            raise ValueError("timeout and on_timeout must both be provided or both omitted")
-
         timeout_step_name = getattr(on_timeout, "__name__", "") if on_timeout is not None else ""
         res = StepResult(
             processed_msg_kind=self._current_directive.kind,
@@ -184,6 +181,10 @@ class Context:
         self._next_builder = NextBuilder(run_info, worker_id, store, directive, step_configs)
         self._parent_run = parent_run
         self._workflow_logger = workflow_logger
+        # Child handles started during this step. They are single-step-scoped: cross-step
+        # coordination uses events/callbacks, not in-memory futures, so any handle still
+        # open when the step returns is abandoned and gets discarded.
+        self._started_handles: list[WorkflowHandle] = []
 
     @property
     def store(self) -> Store:
@@ -215,6 +216,7 @@ class Context:
                 id=str(ULID()),
                 kind=CmdKind.run_event,
                 timestamp=datetime.now(UTC),
+                sender_id=self._worker_id,
                 msg=EventCmd(
                     wf_id=self._parent_run.wf_id,
                     event_name=event_name,
@@ -233,14 +235,23 @@ class Context:
             operation_id,
         )
 
-    async def start(
+    async def start_child(
         self,
         workflow_type: str,
         workflow_id: str,
         workflow_input: dict[str, Any] | None = None,
         workflow_timeout: timedelta | None = None,
+        on_completed_step: StepHandler | None = None,
     ) -> WorkflowHandle:
-        """Start a child workflow and return its handle."""
+        """Start a child workflow and return its handle.
+
+        When on_completed_step is given, the server triggers that parent step once the
+        child reaches any terminal state, passing a ChildOutcome describing the result
+        (on success) or the error (on failure/cancellation). The parent typically parks
+        with ctx.next.wait() so the callback can wake it.
+        """
+        callback_step_name = self._callback_step_name(on_completed_step)
+
         runtime = get_step_runtime()
         operation_id = runtime.generate_operation_id(
             "start",
@@ -263,13 +274,16 @@ class Context:
             parent_wf_id=self.run.wf_id,
             parent_wf_type=self.run.wf_type,
             parent_run_id=self.run.id,
+            parent_callback_step=callback_step_name,
             created_at=datetime.now(UTC),
         )
         handle = WorkflowHandle(
             run_info=run_info,
             payload=workflow_input,
             connection=runtime.connection,
+            sender_id=self._worker_id,
         )
+        self._started_handles.append(handle)
 
         if future is None:
             await handle.start()
@@ -280,6 +294,45 @@ class Context:
             )
         return handle
 
+    async def run_child(
+        self,
+        workflow_type: str,
+        workflow_id: str,
+        workflow_input: dict[str, Any] | None = None,
+        workflow_timeout: timedelta | None = None,
+        timeout: float | None = None,  # noqa: ASYNC109
+    ) -> Any:
+        """Start a child workflow and block until it completes, returning its result.
+
+        Raises WorkflowError on failure, asyncio.CancelledError on cancellation/termination,
+        and TimeoutError if the client-side timeout elapses.
+        timeout: client-side wait in seconds, independent of the server-side workflow_timeout.
+        """
+        handle = await self.start_child(workflow_type, workflow_id, workflow_input, workflow_timeout)
+        if not handle.future.is_started:
+            await handle.future.start()
+        return await handle.result(timeout=timeout)
+
+    async def discard_started_handles(self) -> None:
+        """Silently release child handles started during this step but not awaited.
+
+        Called by the runner once the step returns its directive, on both the success
+        and failure paths. Stops each handle's history subscription and swallows any
+        pending child outcome so an unawaited future does not warn or leak a subscription.
+        """
+        for handle in self._started_handles:
+            await handle.future.discard()
+        self._started_handles.clear()
+
+    @staticmethod
+    def _callback_step_name(on_completed_step: StepHandler | None) -> str | None:
+        if on_completed_step is None:
+            return None
+        step_name = getattr(on_completed_step, "__name__", None)
+        if not step_name:
+            raise ValueError("on_completed_step must be a named handler function.")
+        return step_name
+
     async def now(self) -> datetime:
         runtime = get_step_runtime()
         operation_id = runtime.generate_operation_id("now", {})

grctl/worker/errors.py

@@ -5,6 +5,14 @@ class WorkflowNotRegisteredError(Exception):
         super().__init__(f"Workflow type '{workflow_type}' is not registered with the worker.")
 
 
+class RegistrationError(Exception):
+    """Raised when a worker cannot sync its workflow type catalog to the server.
+
+    A worker that fails to register must not begin processing work, so this
+    error propagates out of Worker.start() to fail the process fast.
+    """
+
+
 class WorkflowRunnerNotFoundError(Exception):
     """Exception raised when a WorkflowRunner is not found for a given workflow run ID."""