dirigent-plugin 0.20.0__tar.gz → 0.22.0__tar.gz

{dirigent_plugin-0.20.0 → dirigent_plugin-0.22.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: dirigent-plugin
-Version: 0.20.0
+Version: 0.22.0
 Summary: The dirigent plugin contract: block specs, protocols, and markers.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-common==0.20.0
+Requires-Dist: dirigent-common==0.22.0
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: pluginkit>=0.5.0
 Requires-Dist: pydantic>=2.13.5

{dirigent_plugin-0.20.0 → dirigent_plugin-0.22.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.20.0"
+version = "0.22.0"
 description = "The dirigent plugin contract: block specs, protocols, and markers."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.20.0",
+    "dirigent-common==0.22.0",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.20.0 → dirigent_plugin-0.22.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-plugin"
-version = "0.20.0"
+version = "0.22.0"
 description = "The dirigent plugin contract: block specs, protocols, and markers."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.20.0",
+    "dirigent-common==0.22.0",
     "httpx2>=2.12.0",
     "pluginkit>=0.5.0",
     "pydantic>=2.13.5",

{dirigent_plugin-0.20.0 → dirigent_plugin-0.22.0}/src/dirigent_plugin/blocks.py

@@ -16,7 +16,16 @@ from pydantic import BaseModel, ConfigDict, Field, GetJsonSchemaHandler, JsonVal
 from pydantic.json_schema import JsonSchemaValue, SkipJsonSchema
 from pydantic_core import CoreSchema
 
-from dirigent_common import API_VERSION, SHELL_MEDIA_TYPE, BlockModel, HealthReport, Issue, JsonMap, Message
+from dirigent_common import (
+    API_VERSION,
+    SHELL_MEDIA_TYPE,
+    BlockModel,
+    Catalogue,
+    HealthReport,
+    Issue,
+    JsonMap,
+    Message,
+)
 from dirigent_plugin.messages import (
     DUPLICATE_ID,
     INVALID_MARK,
@@ -280,8 +289,9 @@ class NotYet(BaseModel):
     worker that dies before that commit leaves the older cursor for the next poke to read
     from again. So a poke must tolerate reading the same ground twice.
 
-    The cursor's life is the waiting attempt. A poke that succeeds ends the step, and
-    nothing carries the cursor past it.
+    The cursor's life is the waiting attempt. A poke that succeeds ends the step, and only
+    :meth:`Sensor.resume_cursor` carries a cursor past it: a watch hands what that returns to
+    the first poke of the run it arms next.
     """
 
 
@@ -363,7 +373,13 @@ class ContainerResult(BaseModel):
 
 
 class AlertMessage(BaseModel):
-    """What an alert rule hands a notifier: the event, a rendered summary, and links back."""
+    """What an alert rule hands a notifier: the event, a rendered summary, and links back.
+
+    The subject and the body are the rule author's own template rendered over the run, so they
+    are that author's words in that author's language and carry no code. What dirigent itself
+    said is ``error_code`` and ``error_params``: the refusal the run ended with, which a
+    notifier with a catalogue can render in the language of wherever it delivers.
+    """
 
     event: str = Field(min_length=1)
     subject: str = Field(min_length=1)
@@ -371,6 +387,10 @@ class AlertMessage(BaseModel):
     run_id: RunId | None = None
     pipeline: str | None = None
     url: str | None = None
+    error_code: str | None = None
+    """The dotted code of the refusal the alerted run ended with, when it ended with one."""
+    error_params: dict[str, JsonValue] = Field(default_factory=dict)
+    """The specifics that refusal rendered, for a re-render in another language."""
     context: dict[str, JsonValue] = Field(default_factory=dict)
 
 
@@ -492,6 +512,10 @@ class RunSnapshot(BaseModel):
     total_steps: int = Field(default=0, ge=0)
     finished_steps: int = Field(default=0, ge=0)
     error: str | None = None
+    error_code: str | None = None
+    """The dotted code of the refusal this run ended with, when it ended with one."""
+    error_params: JsonMap = Field(default_factory=dict)
+    """The specifics that refusal rendered, for a re-render in another language."""
 
     @property
     def progress(self) -> float | None:
@@ -523,8 +547,12 @@ class Runs(Protocol):
         """Describe a run this instance holds, or return None when it holds no such run."""
         ...
 
-    async def cancel(self, run_id: RunId, *, reason: str) -> bool:
-        """Cancel a run; False means it had already settled and there was nothing to stop."""
+    async def cancel(self, run_id: RunId, reason: Message, /, **params: Any) -> bool:
+        """Cancel a run; False means it had already settled and there was nothing to stop.
+
+        The reason is a catalogued message, so the cancelled run carries a code and whoever
+        reads it renders their own sentence rather than this block's English.
+        """
         ...
 
 
@@ -551,7 +579,9 @@ class StepContext(Protocol):
     cursor: JsonMap | None
     """The cursor the last committed :class:`NotYet` returned, and None on the first poke.
 
-    Only a sensor's poke reads it; every other call sees None.
+    The first poke of a run a watch armed is handed where the watch's last success left off
+    instead, which is what :meth:`Sensor.resume_cursor` returned. Only a sensor's poke reads
+    it; every other call sees None.
     """
 
     def connection[C: BaseModel](self, ref: ConnectionRef, model: type[C]) -> C:
@@ -682,6 +712,16 @@ class Sensor[ConfigT: BaseModel, OutputT: BaseModel](ABC):
         """Observe the world once, read-only and briefly; NotYet is not a failure."""
         ...
 
+    def resume_cursor(self, output: OutputT) -> JsonMap | None:
+        """Say where a poke that succeeded left off, read from the output it succeeded with.
+
+        A watch stores what this returns and hands it to the first poke of the next run it
+        arms as ``ctx.cursor``. None, the default, starts every run fresh. It is stored in the
+        transaction that settles the step, so it is only as far along as the last success that
+        committed, and the next poke may read that ground again.
+        """
+        return None
+
     def check_config(self, config: BaseModel) -> list[Issue]:
         """List the extra refusals this block makes at apply, beyond what its schema says.
 
@@ -824,7 +864,7 @@ type AnySensor = Sensor[Any, Any]
 
 
 class Contribution(BaseModel):
-    """Everything one plugin adds, across all six surfaces, gathered by the host at startup."""
+    """Everything one plugin adds, across all seven surfaces, gathered by the host at startup."""
 
     model_config = ConfigDict(arbitrary_types_allowed=True, frozen=True)
 
@@ -839,6 +879,14 @@ class Contribution(BaseModel):
     ``format: <name>`` then asserts wherever the contributing pack is installed, and stays a
     passing annotation on an instance without it."""
 
+    labels: list[Catalogue] = Field(default_factory=list[Catalogue])
+    """The message catalogues this plugin refuses out of, so a surface can render its codes.
+
+    A pack's refusal reaches a browser under the pack's own code, and the browser holds no table
+    for it. Contributing the catalogue is what puts one there: the host serves every code and its
+    template, and a renderer that knows the code says its own sentence rather than repeating the
+    English this process happened to mint."""
+
     @field_validator("api_version")
     @classmethod
     def _check_api_version(cls, value: int) -> int:
@@ -855,6 +903,7 @@ class Contribution(BaseModel):
         _require_unique("notifier id", [notifier.id for notifier in self.notifiers])
         _require_unique("connection kind id", [connection.id for connection in self.connection_kinds])
         _require_unique("format", list(self.formats))
+        _require_unique("label prefix", [catalogue.prefix for catalogue in self.labels])
         return self
 
     @model_validator(mode="after")
@@ -888,6 +937,7 @@ def merge_contributions(contributions: list[Contribution]) -> Contribution:
         "storage_backends": [],
         "notifiers": [],
         "connection_kinds": [],
+        "labels": [],
     }
     for contribution in contributions:
         for surface, collected in merged.items():