dirigent-client 0.27.0__tar.gz → 0.28.0__tar.gz

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/PKG-INFO

@@ -1,12 +1,12 @@
 Metadata-Version: 2.4
 Name: dirigent-client
-Version: 0.27.0
+Version: 0.28.0
 Summary: The dirigent API contract: typed wire schemas and an async Python client.
 License-Expression: LicenseRef-Proprietary
 License-File: LICENSE
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: dirigent-common==0.27.0
+Requires-Dist: dirigent-common==0.28.0
 Requires-Dist: httpx2>=2.12.0
 Requires-Dist: pydantic>=2.13.5
 Requires-Dist: pyyaml>=6.0.3

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-client"
-version = "0.27.0"
+version = "0.28.0"
 description = "The dirigent API contract: typed wire schemas and an async Python client."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.27.0",
+    "dirigent-common==0.28.0",
     "httpx2>=2.12.0",
     "pydantic>=2.13.5",
     "pyyaml>=6.0.3",

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "dirigent-client"
-version = "0.27.0"
+version = "0.28.0"
 description = "The dirigent API contract: typed wire schemas and an async Python client."
 readme = "README.md"
 requires-python = ">=3.13"
@@ -11,7 +11,7 @@ classifiers = [
     "Programming Language :: Python :: 3.13",
 ]
 dependencies = [
-    "dirigent-common==0.27.0",
+    "dirigent-common==0.28.0",
     "httpx2>=2.12.0",
     "pydantic>=2.13.5",
     "pyyaml>=6.0.3",

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/__init__.py

@@ -61,6 +61,7 @@ from dirigent_client.schemas import (
     Catalog,
     CheckResult,
     CheckStatus,
+    ConnectionDetail,
     ConnectionHealth,
     ConnectionIn,
     ConnectionOut,
@@ -93,11 +94,13 @@ from dirigent_client.schemas import (
     Readiness,
     RequestFacts,
     Requirements,
+    RerunRequest,
     RunAccepted,
     RunDetail,
     RunOut,
     RunReport,
     RunRequest,
+    RunStats,
     ScheduleIn,
     ScheduleOut,
     SchedulePreview,
@@ -115,6 +118,7 @@ from dirigent_client.schemas import (
     SystemInfo,
     TestQueued,
     TestRequest,
+    TokenLifetime,
     TokenOut,
     TokenRequest,
     TriggerDocumentDetail,
@@ -165,6 +169,7 @@ __all__ = [
     "CheckResult",
     "CheckStatus",
     "Conflict",
+    "ConnectionDetail",
     "ConnectionHealth",
     "ConnectionIn",
     "ConnectionOut",
@@ -219,6 +224,7 @@ __all__ = [
     "ProvenanceSource",
     "RateLimited",
     "Readiness",
+    "RerunRequest",
     "Requirements",
     "RunAccepted",
     "RunDetail",
@@ -227,6 +233,7 @@ __all__ = [
     "RunPriority",
     "RunReport",
     "RunRequest",
+    "RunStats",
     "RunStatus",
     "ScheduleIn",
     "ScheduleKind",
@@ -242,6 +249,7 @@ __all__ = [
     "TestRequest",
     "TokenKind",
     "TokenOut",
+    "TokenLifetime",
     "TokenRequest",
     "TriggerDocumentDetail",
     "TriggerDocumentOut",

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/enums.py

@@ -8,6 +8,9 @@ class RunStatus(StrEnum):
 
     QUEUED = "queued"
     RUNNING = "running"
+    PAUSED = "paused"
+    """Held by an operator: nothing new is claimed and its deadlines stand still until it resumes."""
+
     SUCCEEDED = "succeeded"
     COMPLETED_WITH_ERRORS = "completed_with_errors"
     FAILED = "failed"
@@ -114,6 +117,9 @@ class TriggerKind(StrEnum):
     SOURCE = "source"
     """An input arrived at a source node, and ``triggered_by_id`` names the source."""
 
+    RERUN = "rerun"
+    """An operator reran a settled run, and ``triggered_by_id`` names that run."""
+
 
 class ScheduleKind(StrEnum):
     """How a schedule computes its next firing."""

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/resources/alerts.py

@@ -4,7 +4,7 @@ from datetime import timedelta
 from uuid import UUID
 
 from dirigent_client.enums import AlertEvent, AlertScope, Importance
-from dirigent_client.resources.base import Resource, query, request_body
+from dirigent_client.resources.base import Resource, query, request_body, segment
 from dirigent_client.schemas import (
     AlertRuleIn,
     AlertRuleOut,
@@ -76,11 +76,11 @@ class Alerts(Resource):
         """
         named = query(paused=paused, template=template, body=body, importance=importance, connection=connection)
         body_json = AlertRuleUpdate.model_validate(named).model_dump(mode="json", exclude_unset=True)
-        return await self._one(AlertRuleOut, "PATCH", f"/alert-rules/{code}", json=body_json)
+        return await self._one(AlertRuleOut, "PATCH", f"/alert-rules/{segment(code)}", json=body_json)
 
     async def delete_rule(self, code: str) -> None:
         """Remove an alert rule; the notifications it already raised are kept."""
-        await self._transport.request("DELETE", f"/alert-rules/{code}")
+        await self._transport.request("DELETE", f"/alert-rules/{segment(code)}")
 
     async def test(
         self,
@@ -98,11 +98,11 @@ class Alerts(Resource):
 
     async def notification(self, notification_id: UUID | str) -> NotificationOut:
         """Read one notification, which is how a caller watches a delivery it just queued."""
-        return await self._one(NotificationOut, "GET", f"/notifications/{notification_id}")
+        return await self._one(NotificationOut, "GET", f"/notifications/{segment(notification_id)}")
 
     async def retry(self, notification_id: UUID | str) -> NotificationOut:
         """Put one notification back on the queue, due now."""
-        return await self._one(NotificationOut, "POST", f"/notifications/{notification_id}/$retry")
+        return await self._one(NotificationOut, "POST", f"/notifications/{segment(notification_id)}/$retry")
 
     async def notifications(
         self, *, run_id: UUID | str | None = None, after: str | None = None, limit: int | None = None

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/resources/auth.py

@@ -1,9 +1,12 @@
 """Logging in, logging out, asking who you are, and the accounts and tokens an admin manages."""
 
+from datetime import timedelta
+from uuid import UUID
+
 from pydantic import SecretStr
 
 from dirigent_client.enums import UserRole
-from dirigent_client.resources.base import Resource, query, request_body
+from dirigent_client.resources.base import Resource, query, request_body, segment
 from dirigent_client.schemas import (
     Identity,
     IssuedTokenOut,
@@ -100,33 +103,31 @@ class Users(Resource):
         if role is not None:
             named["role"] = role
         body = UserUpdate.model_validate(named).model_dump(mode="json", exclude_unset=True)
-        return await self._one(UserOut, "PATCH", f"/users/{username}", json=body)
+        return await self._one(UserOut, "PATCH", f"/users/{segment(username)}", json=body)
 
     async def deactivate(self, username: str) -> UserOut:
         """Bar an account from logging in and revoke the sessions it already holds."""
-        return await self._one(UserOut, "POST", f"/users/{username}/$deactivate")
+        return await self._one(UserOut, "POST", f"/users/{segment(username)}/$deactivate")
 
     async def activate(self, username: str) -> UserOut:
         """Let an account log in again; the sessions it lost are not restored."""
-        return await self._one(UserOut, "POST", f"/users/{username}/$activate")
+        return await self._one(UserOut, "POST", f"/users/{segment(username)}/$activate")
 
     async def reset_password(self, username: str, password: str) -> None:
         """Set an account's password without its old one, ending every session it holds."""
         payload = PasswordResetRequest(password=SecretStr(password))
-        await self._transport.request("POST", f"/users/{username}/$reset-password", json=request_body(payload))
+        await self._transport.request("POST", f"/users/{segment(username)}/$reset-password", json=request_body(payload))
 
     async def tokens(self, username: str, *, after: str | None = None, limit: int | None = None) -> Page[TokenOut]:
         """List the API tokens one account holds, without their secrets."""
-        return await self._many(TokenOut, "GET", f"/users/{username}/tokens", params=query(after=after, limit=limit))
+        return await self._many(
+            TokenOut, "GET", f"/users/{segment(username)}/tokens", params=query(after=after, limit=limit)
+        )
 
-    async def create_token(self, username: str, name: str) -> IssuedTokenOut:
+    async def create_token(self, username: str, name: str, *, expires_in: timedelta | None = None) -> IssuedTokenOut:
         """Mint a bearer token for another account; its secret is returned exactly once."""
-        payload = TokenRequest(name=name)
-        return await self._one(IssuedTokenOut, "POST", f"/users/{username}/tokens", json=request_body(payload))
-
-    async def revoke_token(self, username: str, name: str) -> None:
-        """Revoke that account's live tokens of the given name."""
-        await self._transport.request("DELETE", f"/users/{username}/tokens/{name}")
+        payload = TokenRequest(name=name, expires_in=expires_in)
+        return await self._one(IssuedTokenOut, "POST", f"/users/{segment(username)}/tokens", json=request_body(payload))
 
 
 class Tokens(Resource):
@@ -136,14 +137,14 @@ class Tokens(Resource):
         """List every account's API tokens, without their secrets; sessions are not listed."""
         return await self._many(TokenOut, "GET", "/tokens", params=query(after=after, limit=limit))
 
-    async def create(self, name: str) -> IssuedTokenOut:
+    async def create(self, name: str, *, expires_in: timedelta | None = None) -> IssuedTokenOut:
         """Mint a bearer token for this account; its secret is returned exactly once."""
-        payload = TokenRequest(name=name)
+        payload = TokenRequest(name=name, expires_in=expires_in)
         return await self._one(IssuedTokenOut, "POST", "/tokens", json=request_body(payload))
 
-    async def revoke(self, name: str) -> None:
-        """Revoke this account's own live tokens of the given name."""
-        await self._transport.request("DELETE", f"/tokens/{name}")
+    async def revoke(self, token_id: UUID | str) -> None:
+        """Revoke the one live token with this id, whichever account holds it."""
+        await self._transport.request("DELETE", f"/tokens/{segment(str(token_id))}")
 
 
 class Admin:

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/resources/base.py

@@ -2,9 +2,11 @@
 
 from enum import Enum
 from typing import Any, Final
+from urllib.parse import quote
 
 from pydantic import BaseModel, SecretStr
 
+from dirigent_client.errors import DirigentError
 from dirigent_client.schemas import Page
 from dirigent_client.transport import Transport
 
@@ -40,6 +42,18 @@ class Resource:
         return Page(items=[model.model_validate(row) for row in payload["items"]], next=payload.get("next"))
 
 
+def segment(value: object) -> str:
+    """Percent-encode an identifier as exactly one path segment of a request.
+
+    A value that cannot be one is refused: an empty one or a dot segment is collapsed out of the
+    path, and a slash is decoded back into a separator by the server that routes the request.
+    """
+    text = str(value)
+    if text in ("", ".", "..") or "/" in text:
+        raise DirigentError(f"{text!r} is not an identifier this instance could hold")
+    return quote(text, safe="")
+
+
 def query(**values: object) -> dict[str, Any]:
     """Build a query string from the arguments a caller actually supplied."""
     return {name: value for name, value in values.items() if value is not None}

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/resources/blocks.py

@@ -1,6 +1,6 @@
 """The block catalog: what this instance can run, and the schemas a form is built from."""
 
-from dirigent_client.resources.base import Resource, query
+from dirigent_client.resources.base import Resource, query, segment
 from dirigent_client.schemas import BlockEntry, BlockKind, Catalog
 
 
@@ -13,4 +13,4 @@ class Blocks(Resource):
 
     async def get(self, block_id: str) -> BlockEntry:
         """Read one catalog entry, which is what a step's configuration form is built from."""
-        return await self._one(BlockEntry, "GET", f"/blocks/{block_id}")
+        return await self._one(BlockEntry, "GET", f"/blocks/{segment(block_id)}")

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/resources/connections.py

@@ -1,7 +1,7 @@
 """Connections: coded credential records of a contributed kind, redacted in every response."""
 
-from dirigent_client.resources.base import Resource, edit_body, query, request_body
-from dirigent_client.schemas import ConnectionIn, ConnectionOut, ConnectionUpdate, Page
+from dirigent_client.resources.base import Resource, edit_body, query, request_body, segment
+from dirigent_client.schemas import ConnectionDetail, ConnectionIn, ConnectionOut, ConnectionUpdate, Page
 from dirigent_common import HealthReport, JsonMap
 
 
@@ -12,9 +12,9 @@ class Connections(Resource):
         """List every stored credential record, with its secrets redacted."""
         return await self._many(ConnectionOut, "GET", "/connections", params=query(after=after, limit=limit))
 
-    async def get(self, code: str) -> ConnectionOut:
-        """Read one credential record, with its secrets redacted."""
-        return await self._one(ConnectionOut, "GET", f"/connections/{code}")
+    async def get(self, code: str) -> ConnectionDetail:
+        """Read one credential record, with its secrets redacted and what uses it."""
+        return await self._one(ConnectionDetail, "GET", f"/connections/{segment(code)}")
 
     async def create(
         self,
@@ -43,12 +43,12 @@ class Connections(Resource):
         their own keep the name and the description the credential was created with.
         """
         sent = edit_body(ConnectionUpdate, name=name, description=description, config=config)
-        return await self._one(ConnectionOut, "PATCH", f"/connections/{code}", json=sent)
+        return await self._one(ConnectionOut, "PATCH", f"/connections/{segment(code)}", json=sent)
 
     async def delete(self, code: str) -> None:
-        """Remove a credential record."""
-        await self._transport.request("DELETE", f"/connections/{code}")
+        """Remove a credential record, which the server refuses while anything still uses it."""
+        await self._transport.request("DELETE", f"/connections/{segment(code)}")
 
     async def check(self, code: str) -> HealthReport:
         """Open the credential and ask its kind whether the external system answers."""
-        return await self._one(HealthReport, "POST", f"/connections/{code}/$check")
+        return await self._one(HealthReport, "POST", f"/connections/{segment(code)}/$check")

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/resources/examples.py

@@ -2,7 +2,7 @@
 
 from collections.abc import Sequence
 
-from dirigent_client.resources.base import Resource, query
+from dirigent_client.resources.base import Resource, query, segment
 from dirigent_client.schemas import ExampleDetail, ExampleOut, Page
 
 
@@ -25,4 +25,4 @@ class Examples(Resource):
 
     async def get(self, code: str) -> ExampleDetail:
         """Read one example by its code, with the text a copy of it copies."""
-        return await self._one(ExampleDetail, "GET", f"/examples/{code}")
+        return await self._one(ExampleDetail, "GET", f"/examples/{segment(code)}")

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/resources/pipelines.py

@@ -11,7 +11,7 @@ from pydantic import JsonValue
 
 from dirigent_client.enums import LogLevel, ProvenanceSource, RunPriority
 from dirigent_client.errors import DirigentError
-from dirigent_client.resources.base import Resource, query, request_body
+from dirigent_client.resources.base import Resource, query, request_body, segment
 from dirigent_client.schemas import (
     ApplyRequest,
     ApplyResult,
@@ -28,6 +28,7 @@ from dirigent_client.schemas import (
     RunRequest,
     ValidationIssue,
 )
+from dirigent_common import bounded_load
 
 type DocumentSource = JsonMap | str | Path
 
@@ -48,7 +49,7 @@ class Pipelines(Resource):
 
     async def get(self, code: str) -> PipelineDetail:
         """Read a pipeline and the document its current version holds."""
-        return await self._one(PipelineDetail, "GET", f"/pipelines/{code}")
+        return await self._one(PipelineDetail, "GET", f"/pipelines/{segment(code)}")
 
     async def apply(
         self,
@@ -58,13 +59,14 @@ class Pipelines(Resource):
         source: ProvenanceSource | None = None,
         source_ref: str | None = None,
         dry_run: bool = False,
-        pause_schedules: bool = False,
+        paused: bool = False,
     ) -> ApplyResult:
         """Validate a document against this instance and commit a new version, or plan one.
 
         A document this instance cannot run arrives as a 200 with ``action`` of ``invalid``
-        and the issues on the plan, not as a refusal. ``pause_schedules`` creates the
-        schedules this apply brings into being paused, and leaves existing ones alone.
+        and the issues on the plan, not as a refusal. ``paused`` creates the schedules and the
+        polled or held sources this apply brings into being paused, and leaves a received source
+        and everything the instance already holds alone.
         """
         parsed, provenance, ref = read_document(document)
         payload = ApplyRequest(
@@ -72,7 +74,7 @@ class Pipelines(Resource):
             code=code,
             source=source if source is not None else provenance,
             source_ref=source_ref if source_ref is not None else ref,
-            pause_schedules=pause_schedules,
+            paused=paused,
         )
         return await self._one(
             ApplyResult,
@@ -102,12 +104,12 @@ class Pipelines(Resource):
     ) -> Page[PipelineVersionOut]:
         """List every immutable version, newest first, with its provenance."""
         return await self._many(
-            PipelineVersionOut, "GET", f"/pipelines/{code}/versions", params=query(after=after, limit=limit)
+            PipelineVersionOut, "GET", f"/pipelines/{segment(code)}/versions", params=query(after=after, limit=limit)
         )
 
     async def export(self, code: str, *, version: int | None = None) -> str:
         """Render a stored pipeline as the canonical YAML a git repository holds."""
-        return await self._transport.text(f"/pipelines/{code}/$export", params=query(version=version))
+        return await self._transport.text(f"/pipelines/{segment(code)}/$export", params=query(version=version))
 
     async def validate(self, code: str, *, version: int | None = None) -> builtins.list[ValidationIssue]:
         """Report what a stored version would fail on if it ran now, against this instance.
@@ -115,20 +117,22 @@ class Pipelines(Resource):
         The issues are bounded by the document, so this one answers a bare array, not a page.
         builtins names the type because this class has a method called ``list``.
         """
-        rows = await self._transport.json("POST", f"/pipelines/{code}/$validate", params=query(version=version))
+        rows = await self._transport.json(
+            "POST", f"/pipelines/{segment(code)}/$validate", params=query(version=version)
+        )
         return [ValidationIssue.model_validate(row) for row in rows]
 
     async def activate(self, code: str) -> PipelineOut:
         """Make a pipeline runnable again, and let its schedules fire."""
-        return await self._one(PipelineOut, "POST", f"/pipelines/{code}/$activate")
+        return await self._one(PipelineOut, "POST", f"/pipelines/{segment(code)}/$activate")
 
     async def deactivate(self, code: str) -> PipelineOut:
         """Deregister a pipeline: schedules pause, it stops being runnable, history is kept."""
-        return await self._one(PipelineOut, "POST", f"/pipelines/{code}/$deactivate")
+        return await self._one(PipelineOut, "POST", f"/pipelines/{segment(code)}/$deactivate")
 
     async def delete(self, code: str) -> None:
         """Delete a pipeline and every run ever attributed to it, refusing while any is in flight."""
-        await self._transport.request("DELETE", f"/pipelines/{code}")
+        await self._transport.request("DELETE", f"/pipelines/{segment(code)}")
 
     async def run(
         self,
@@ -167,7 +171,7 @@ class Pipelines(Resource):
             log_levels=log_levels,
             priority=priority,
         )
-        return await self._one(RunAccepted, "POST", f"/pipelines/{code}/$run", json=request_body(payload))
+        return await self._one(RunAccepted, "POST", f"/pipelines/{segment(code)}/$run", json=request_body(payload))
 
     async def backfill(
         self,
@@ -191,7 +195,9 @@ class Pipelines(Resource):
             params=params,
             dry_run=dry_run,
         )
-        return await self._one(BackfillAccepted, "POST", f"/pipelines/{code}/$backfill", json=request_body(payload))
+        return await self._one(
+            BackfillAccepted, "POST", f"/pipelines/{segment(code)}/$backfill", json=request_body(payload)
+        )
 
 
 def read_document(document: DocumentSource) -> tuple[JsonMap, ProvenanceSource, str | None]:
@@ -199,17 +205,17 @@ def read_document(document: DocumentSource) -> tuple[JsonMap, ProvenanceSource,
     if isinstance(document, dict):
         return dict(document), ProvenanceSource.API, None
     if isinstance(document, Path):
-        return _parse(document.read_text()), ProvenanceSource.FILE, str(document)
+        return parse_document(document.read_text()), ProvenanceSource.FILE, str(document)
     path = Path(document)
     if len(document) < 4096 and "\n" not in document and path.is_file():
-        return _parse(path.read_text()), ProvenanceSource.FILE, document
-    return _parse(document), ProvenanceSource.API, None
+        return parse_document(path.read_text()), ProvenanceSource.FILE, document
+    return parse_document(document), ProvenanceSource.API, None
 
 
-def _parse(text: str) -> JsonMap:
+def parse_document(text: str) -> JsonMap:
     """Read a document's text as YAML, which accepts its JSON form verbatim."""
     try:
-        loaded: object = yaml.safe_load(text)
+        loaded: object = bounded_load(text)
     except yaml.YAMLError as error:
         raise DirigentError(f"the document is not valid YAML or JSON: {error}") from error
     if not isinstance(loaded, dict):

{dirigent_client-0.27.0 → dirigent_client-0.28.0}/src/dirigent_client/resources/runs.py

@@ -12,7 +12,7 @@ import httpx2
 
 from dirigent_client.enums import AttemptStatus, RunStatus
 from dirigent_client.errors import TransportError, WaitTimeout
-from dirigent_client.resources.base import Resource, query
+from dirigent_client.resources.base import Resource, query, request_body, segment
 from dirigent_client.schemas import (
     ArtifactOut,
     AttemptEvent,
@@ -20,9 +20,12 @@ from dirigent_client.schemas import (
     ItemOut,
     LogEntryOut,
     Page,
+    RerunRequest,
+    RunAccepted,
     RunDetail,
     RunOut,
     RunReport,
+    RunStats,
 )
 
 #: What a run's own report document is stored as, which is how it is told from a step's output.
@@ -67,9 +70,25 @@ class Runs(Resource):
             ),
         )
 
+    async def stats(
+        self,
+        *,
+        since: str | None = None,
+        pipeline: str | None = None,
+        tags: Sequence[str] = (),
+    ) -> RunStats:
+        """Summarise the runs that settled within a window, ``7d`` when none is named.
+
+        Per day by status, per pipeline how long they took, and the errors and steps that
+        failed most. Naming more than one tag narrows, as it does on the listing.
+        """
+        return await self._one(
+            RunStats, "GET", "/runs/$stats", params=query(since=since, pipeline=pipeline, tag=[*tags] or None)
+        )
+
     async def get(self, run_id: UUID | str) -> RunDetail:
         """Read a run with the DAG view model, and how many items and attempts it has."""
-        return await self._one(RunDetail, "GET", f"/runs/{run_id}")
+        return await self._one(RunDetail, "GET", f"/runs/{segment(run_id)}")
 
     async def items(
         self,
@@ -79,7 +98,9 @@ class Runs(Resource):
         limit: int | None = None,
     ) -> Page[ItemOut]:
         """List a run's fan-out items in the order they were created, which is grid order."""
-        return await self._many(ItemOut, "GET", f"/runs/{run_id}/items", params=query(after=after, limit=limit))
+        return await self._many(
+            ItemOut, "GET", f"/runs/{segment(run_id)}/items", params=query(after=after, limit=limit)
+        )
 
     async def attempts(
         self,
@@ -94,7 +115,7 @@ class Runs(Resource):
         return await self._many(
             AttemptOut,
             "GET",
-            f"/runs/{run_id}/attempts",
+            f"/runs/{segment(run_id)}/attempts",
             params=query(step=step, status=status.value if status else None, after=after, limit=limit),
         )
 
@@ -106,11 +127,13 @@ class Runs(Resource):
         limit: int | None = None,
     ) -> Page[ArtifactOut]:
         """List what a run wrote down: each step's stored output, and its report document."""
-        return await self._many(ArtifactOut, "GET", f"/runs/{run_id}/artifacts", params=query(after=after, limit=limit))
+        return await self._many(
+            ArtifactOut, "GET", f"/runs/{segment(run_id)}/artifacts", params=query(after=after, limit=limit)
+        )
 
     async def artifact_text(self, artifact_id: UUID | str) -> str:
         """Read one artifact's content as the text it was stored as."""
-        return await self._transport.text(f"/artifacts/{artifact_id}")
+        return await self._transport.text(f"/artifacts/{segment(artifact_id)}")
 
     async def report_document(self, run_id: UUID | str) -> str | None:
         """Read the markdown document this run rendered when it settled, if it rendered one."""
@@ -123,12 +146,31 @@ class Runs(Resource):
 
     async def cancel(self, run_id: UUID | str) -> RunOut:
         """Stop what has not started, and tell the remote about what has."""
-        return await self._one(RunOut, "POST", f"/runs/{run_id}/$cancel")
+        return await self._one(RunOut, "POST", f"/runs/{segment(run_id)}/$cancel")
+
+    async def rerun(self, run_id: UUID | str, *, current: bool = False) -> RunAccepted:
+        """Run a settled run again, with its parameters and, at a source, its input.
+
+        The new run pins the version the original ran, or the pipeline's current one with
+        ``current``. Its ``triggered_by_id`` names the original.
+        """
+        body = RerunRequest(version="current" if current else "pinned")
+        return await self._one(RunAccepted, "POST", f"/runs/{segment(run_id)}/$rerun", json=request_body(body))
+
+    async def pause(self, run_id: UUID | str) -> RunOut:
+        """Hold a queued or running run: nothing more of it starts, and its deadlines stand still."""
+        return await self._one(RunOut, "POST", f"/runs/{segment(run_id)}/$pause")
+
+    async def resume(self, run_id: UUID | str) -> RunOut:
+        """Let a paused run go on, its open deadlines moved on by as long as it was paused."""
+        return await self._one(RunOut, "POST", f"/runs/{segment(run_id)}/$resume")
 
     async def retry(self, attempt_id: UUID | str, *, idempotency_key: str | None = None) -> AttemptOut:
         """Create one manual attempt of a failed step, reading its upstream stored outputs."""
         key = idempotency_key or str(uuid.uuid4())
-        return await self._one(AttemptOut, "POST", f"/attempts/{attempt_id}/$retry", headers={"Idempotency-Key": key})
+        return await self._one(
+            AttemptOut, "POST", f"/attempts/{segment(attempt_id)}/$retry", headers={"Idempotency-Key": key}
+        )
 
     async def logs(
         self,
@@ -140,12 +182,12 @@ class Runs(Resource):
     ) -> Page[LogEntryOut]:
         """Read one page of a run's log entries, in write order."""
         return await self._many(
-            LogEntryOut, "GET", f"/runs/{run_id}/$logs", params=query(after=after, limit=limit, step=step)
+            LogEntryOut, "GET", f"/runs/{segment(run_id)}/$logs", params=query(after=after, limit=limit, step=step)
         )
 
     async def report(self, run_id: UUID | str) -> RunReport:
         """Summarise a run: what each step amounted to, and how long the whole thing took."""
-        return await self._one(RunReport, "GET", f"/runs/{run_id}/$report")
+        return await self._one(RunReport, "GET", f"/runs/{segment(run_id)}/$report")
 
     async def wait(
         self,
@@ -164,7 +206,7 @@ class Runs(Resource):
             if time.monotonic() + interval > deadline:
                 raise WaitTimeout(
                     f"run {run_id} was still {run.status.value} after {timeout}",
-                    url=self._transport.endpoint(f"/runs/{run_id}"),
+                    url=self._transport.endpoint(f"/runs/{segment(run_id)}"),
                 )
             await asyncio.sleep(interval)
             interval = min(interval * POLL_BACKOFF, POLL_MAX_SECONDS)
@@ -194,7 +236,9 @@ class Runs(Resource):
             expired = False
             advanced = False
             try:
-                async with self._transport.stream(f"/runs/{run_id}/$events", params=query(after=cursor)) as response:
+                async with self._transport.stream(
+                    f"/runs/{segment(run_id)}/$events", params=query(after=cursor)
+                ) as response:
                     async for event in httpx2.EventSource(response):
                         if event.event == "end":
                             ended = True
@@ -254,7 +298,7 @@ class Runs(Resource):
             advanced = False
             try:
                 params = query(follow="sse", after=cursor, step=step)
-                async with self._transport.stream(f"/runs/{run_id}/$logs", params=params) as response:
+                async with self._transport.stream(f"/runs/{segment(run_id)}/$logs", params=params) as response:
                     async for event in httpx2.EventSource(response):
                         if event.event == "end":
                             ended = True