Skip to content

protocol

protocol

PEP 544 protocol defining the Notifier interface.

Notifier

Bases: Protocol

Structural type for desktop notification backends.

Implementations must provide notify, on_action, close, and disconnect. DbusNotifier talks to a real session bus; NullNotifier silently discards everything for headless environments.

notify(summary, body='', *, actions=(), timeout_ms=-1, hints=None, replaces_id=0, app_icon='', container_id='', container_name='', project='', task_id='', task_name='') async

Send a desktop notification.

Parameters:

Name Type Description Default
summary str

Notification title.

 required
body str

Optional body text.

 ''
actions Sequence[tuple[str, str]]

(action_id, label) pairs rendered as buttons.

 ()
timeout_ms int

Expiration hint in milliseconds (-1 = server default).

 -1
hints Mapping[str, Any] | None

Freedesktop hint dict (values are dbus_fast.Variant for DbusNotifier, ignored by NullNotifier).

 None
replaces_id int

Replace an existing notification in-place.

 0
app_icon str

Icon name or file:/// URI.

 ''
container_id str

Presentation-layer hint: the 12-char podman container ID the event refers to. The desktop DbusNotifier ignores it; CallbackNotifier attaches it to the Notification so rich consumers can render it alongside the user-facing name.

 ''
container_name str

Podman --name matching the ID. Same propagation rules as container_id.

 ''
project str

Terok project slug when the container is orchestrator- managed (from the ai.terok.project annotation). Empty for standalone containers.

 ''
task_id str

Terok task ID (ai.terok.task annotation); empty for standalone containers.

 ''
task_name str

Human-readable task label from terok's metadata — mutable at any point in the task's life, so resolved live by callers, not snapshotted. Empty when unknown.

 ''

Returns:

Type Description
int

Server-assigned notification ID (0 for null implementations).
Source code in src/terok_clearance/notifications/protocol.py 
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
async def notify(
    self,
    summary: str,
    body: str = "",
    *,
    actions: Sequence[tuple[str, str]] = (),
    timeout_ms: int = -1,
    hints: Mapping[str, Any] | None = None,
    replaces_id: int = 0,
    app_icon: str = "",
    container_id: str = "",
    container_name: str = "",
    project: str = "",
    task_id: str = "",
    task_name: str = "",
) -> int:
    """Send a desktop notification.

    Args:
        summary: Notification title.
        body: Optional body text.
        actions: ``(action_id, label)`` pairs rendered as buttons.
        timeout_ms: Expiration hint in milliseconds (``-1`` = server default).
        hints: Freedesktop hint dict (values are ``dbus_fast.Variant`` for
            ``DbusNotifier``, ignored by ``NullNotifier``).
        replaces_id: Replace an existing notification in-place.
        app_icon: Icon name or ``file:///`` URI.
        container_id: Presentation-layer hint: the 12-char podman
            container ID the event refers to.  The desktop
            ``DbusNotifier`` ignores it; ``CallbackNotifier`` attaches
            it to the [`Notification`][terok_clearance.notifications.callback.Notification] so
            rich consumers can render it alongside the user-facing name.
        container_name: Podman ``--name`` matching the ID.  Same
            propagation rules as ``container_id``.
        project: Terok project slug when the container is orchestrator-
            managed (from the ``ai.terok.project`` annotation).  Empty
            for standalone containers.
        task_id: Terok task ID (``ai.terok.task`` annotation); empty
            for standalone containers.
        task_name: Human-readable task label from terok's metadata —
            mutable at any point in the task's life, so resolved live
            by callers, not snapshotted.  Empty when unknown.

    Returns:
        Server-assigned notification ID (``0`` for null implementations).
    """
    ...

on_action(notification_id, callback) async

Register a callback for when the user clicks an action button.

Parameters:

Name Type Description Default
notification_id int

ID returned by notify.

 required
callback Callable[[str], None]

Called with the action_id string when invoked.

 required
Source code in src/terok_clearance/notifications/protocol.py 
67
68
69
70
71
72
73
74
75
76
77
78
async def on_action(
    self,
    notification_id: int,
    callback: Callable[[str], None],
) -> None:
    """Register a callback for when the user clicks an action button.

    Args:
        notification_id: ID returned by ``notify``.
        callback: Called with the ``action_id`` string when invoked.
    """
    ...

close(notification_id) async

Close an active notification.

Parameters:

Name Type Description Default
notification_id int

ID returned by notify.

 required
Source code in src/terok_clearance/notifications/protocol.py 
80
81
82
83
84
85
86
async def close(self, notification_id: int) -> None:
    """Close an active notification.

    Args:
        notification_id: ID returned by ``notify``.
    """
    ...

disconnect() async

Release backend resources (no-op for null backends).

Source code in src/terok_clearance/notifications/protocol.py 
88
89
90
async def disconnect(self) -> None:
    """Release backend resources (no-op for null backends)."""
    ...