Refine actor modals and help prompt delivery

Author: ChesterRa

docs/guide/best-practices.md

@@ -73,7 +73,9 @@ You can show different content to different roles using conditional markers:
 - `## @role: foreman` - Only foreman sees this section
 - `## @role: peer` - Only peers see this section
 - `## @actor: <actor_id>` - Only the specific actor sees this section
-- Sections without markers are visible to all roles
+- Sections without markers are the shared/common content visible to everyone
+
+In the Web structured Help editor, these untagged sections are surfaced as `Common Notes`, while the tagged blocks are surfaced as role/actor notes.
 
 #### How Agents Consume Help
 

src/cccc/daemon/messaging/delivery.py

@@ -30,9 +30,11 @@
 
 logger = logging.getLogger("cccc.delivery")
 
+from ...contracts.v1 import SystemNotifyData
 from ...kernel.actors import find_actor, list_actors
 from ...kernel.group import Group, get_group_state, set_group_state
 from ...kernel.inbox import is_message_for_actor, set_cursor
+from ...kernel.ledger import append_event
 from ...kernel.system_prompt import render_system_prompt
 from ...paths import ensure_home
 from ...runners import pty as pty_runner
@@ -748,6 +750,65 @@ def queue_system_notify(
     )
 
 
+def emit_system_notify(
+    group: Group,
+    *,
+    by: str,
+    notify: SystemNotifyData,
+) -> Dict[str, Any]:
+    """Append a system.notify event and dispatch it to running PTY targets."""
+    event = append_event(
+        group.ledger_path,
+        kind="system.notify",
+        group_id=group.group_id,
+        scope_key="",
+        by=str(by or "system").strip() or "system",
+        data=notify.model_dump(),
+    )
+
+    target_actor_id = str(notify.target_actor_id or "").strip()
+    if target_actor_id:
+        target_actor_ids = [target_actor_id]
+    else:
+        target_actor_ids: List[str] = []
+        seen: set[str] = set()
+        for actor in list_actors(group):
+            if not isinstance(actor, dict):
+                continue
+            aid = str(actor.get("id") or "").strip()
+            if not aid or aid == "user" or aid in seen:
+                continue
+            seen.add(aid)
+            target_actor_ids.append(aid)
+
+    event_id = str(event.get("id") or "").strip()
+    event_ts = str(event.get("ts") or "").strip()
+    if not event_id:
+        return event
+
+    for aid in target_actor_ids:
+        actor = find_actor(group, aid)
+        if not isinstance(actor, dict):
+            continue
+        runner_kind = str(actor.get("runner") or "pty").strip()
+        if runner_kind != "pty":
+            continue
+        if not pty_runner.SUPERVISOR.actor_running(group.group_id, aid):
+            continue
+        queue_system_notify(
+            group,
+            actor_id=aid,
+            event_id=event_id,
+            notify_kind=str(notify.kind),
+            title=str(notify.title),
+            message=str(notify.message),
+            ts=event_ts,
+        )
+        flush_pending_messages(group, actor_id=aid)
+
+    return event
+
+
 def flush_pending_messages(group: Group, *, actor_id: str) -> bool:
     """Flush pending messages for an actor if ready.
 

src/cccc/daemon/messaging/system_notify_ops.py

@@ -4,11 +4,11 @@
 
 from typing import Any, Callable, Dict, Optional
 
-from ...contracts.v1 import DaemonError, DaemonResponse
-from ...kernel.actors import list_actors
+from ...contracts.v1 import DaemonError, DaemonResponse, SystemNotifyData
 from ...kernel.group import load_group
 from ...kernel.inbox import find_event
 from ...kernel.ledger import append_event
+from .delivery import emit_system_notify
 
 
 def _error(code: str, message: str, *, details: Optional[Dict[str, Any]] = None) -> DaemonResponse:
@@ -19,7 +19,6 @@ def handle_system_notify(
     args: Dict[str, Any],
     *,
     coerce_bool: Callable[[Any], bool],
-    queue_system_notify: Callable[..., None],
 ) -> DaemonResponse:
     group_id = str(args.get("group_id") or "").strip()
     by = str(args.get("by") or "system").strip()
@@ -44,47 +43,16 @@ def handle_system_notify(
     if priority not in valid_priorities:
         priority = "normal"
 
-    event = append_event(
-        group.ledger_path,
-        kind="system.notify",
-        group_id=group.group_id,
-        scope_key="",
-        by=by,
-        data={
-            "kind": kind,
-            "priority": priority,
-            "title": title,
-            "message": message,
-            "target_actor_id": target_actor_id,
-            "requires_ack": requires_ack,
-            "context": context,
-        },
+    notify = SystemNotifyData(
+        kind=kind,
+        priority=priority,
+        title=title,
+        message=message,
+        target_actor_id=target_actor_id,
+        requires_ack=requires_ack,
+        context=context,
     )
-
-    if priority in ("high", "urgent"):
-        event_id = str(event.get("id") or "").strip()
-        event_ts = str(event.get("ts") or "").strip()
-        for actor in list_actors(group):
-            if not isinstance(actor, dict):
-                continue
-            aid = str(actor.get("id") or "").strip()
-            if not aid or aid == "user":
-                continue
-            if target_actor_id and aid != target_actor_id:
-                continue
-            runner_kind = str(actor.get("runner") or "pty").strip()
-            if runner_kind != "pty":
-                continue
-            queue_system_notify(
-                group,
-                actor_id=aid,
-                event_id=event_id,
-                notify_kind=kind,
-                title=title,
-                message=message,
-                ts=event_ts,
-            )
-
+    event = emit_system_notify(group, by=by, notify=notify)
     return DaemonResponse(ok=True, result={"event": event})
 
 
@@ -131,10 +99,9 @@ def try_handle_system_notify_op(
     args: Dict[str, Any],
     *,
     coerce_bool: Callable[[Any], bool],
-    queue_system_notify: Callable[..., None],
 ) -> Optional[DaemonResponse]:
     if op == "system_notify":
-        return handle_system_notify(args, coerce_bool=coerce_bool, queue_system_notify=queue_system_notify)
+        return handle_system_notify(args, coerce_bool=coerce_bool)
     if op == "notify_ack":
         return handle_notify_ack(args)
     return None

src/cccc/daemon/request_dispatch_ops.py

@@ -91,7 +91,6 @@ class RequestDispatchDeps:
     auto_wake_recipients: Callable[..., None]
     automation_on_new_message: Callable[[Any], None]
     clear_pending_system_notifies_chat: Callable[[str, set[str]], None]
-    queue_system_notify: Callable[..., None]
     error_factory: Callable[[str, str], DaemonResponse]
 
 
@@ -365,7 +364,6 @@ def dispatch_request(
         op,
         args,
         coerce_bool=deps.coerce_bool_default_false,
-        queue_system_notify=deps.queue_system_notify,
     )
     if system_notify_resp is not None:
         return system_notify_resp, False

src/cccc/daemon/server.py

@@ -79,7 +79,6 @@
     pty_submit_text,
     render_delivery_text,
     deliver_message_with_preamble,
-    queue_system_notify,
     flush_pending_messages,
     tick_delivery,
     clear_preamble_sent,
@@ -292,6 +291,7 @@ def _inject_actor_context_env(env: Dict[str, Any], *, group_id: str, actor_id: s
     This is runtime-only (not persisted to group docs).
     """
     out: Dict[str, Any] = dict(env or {})
+    out["CCCC_HOME"] = str(ensure_home())
     out["CCCC_GROUP_ID"] = str(group_id or "").strip()
     out["CCCC_ACTOR_ID"] = str(actor_id or "").strip()
     return out
@@ -730,7 +730,6 @@ def _request_dispatch_deps() -> RequestDispatchDeps:
             group_id,
             notify_kinds=notify_kinds,
         ),
-        queue_system_notify=queue_system_notify,
         error_factory=_error,
     )
     return _REQUEST_DISPATCH_DEPS

src/cccc/daemon/space/group_space_ops.py

@@ -12,7 +12,7 @@
 import threading
 from typing import Any, Deque, Dict, Optional, Tuple
 
-from ...contracts.v1 import DaemonError, DaemonResponse, SpaceBinding, SpaceLane
+from ...contracts.v1 import DaemonError, DaemonResponse, SpaceBinding, SpaceLane, SystemNotifyData
 from ...kernel.group import load_group
 from ...kernel.ledger import append_event
 from ...kernel.permissions import require_group_permission
@@ -32,6 +32,7 @@
 )
 from ...providers.notebooklm.errors import NotebookLMProviderError
 from ...providers.notebooklm.health import notebooklm_health_check, parse_notebooklm_auth_json
+from ..messaging.delivery import emit_system_notify
 from .notebooklm_auth_flow import (
     cancel_notebooklm_auth_flow,
     get_notebooklm_auth_flow_status,
@@ -764,22 +765,16 @@ def _emit_artifact_async_notify(
             "output_path": str(output_path or ""),
             "error": {"code": str(error_code or ""), "message": str(error_message or "")},
         }
-        _ = append_event(
-            group.ledger_path,
-            kind="system.notify",
-            group_id=group.group_id,
-            scope_key="",
-            by="system",
-            data={
-                "kind": ("info" if ok else "error"),
-                "priority": ("normal" if ok else "high"),
-                "title": title,
-                "message": message,
-                "target_actor_id": _notify_target_from_by(by),
-                "requires_ack": False,
-                "context": context,
-            },
+        notify = SystemNotifyData(
+            kind=("info" if ok else "error"),
+            priority=("normal" if ok else "high"),
+            title=title,
+            message=message,
+            target_actor_id=_notify_target_from_by(by),
+            requires_ack=False,
+            context=context,
         )
+        emit_system_notify(group, by="system", notify=notify)
     except Exception as e:
         _LOG.warning("group-space async artifact notify failed group=%s: %s", group_id, e)
 

src/cccc/daemon/space/group_space_sync.py

@@ -8,10 +8,12 @@
 from typing import Any, Dict, Iterable, List, Optional, Tuple
 from urllib.parse import urlparse
 
+from ...contracts.v1 import SystemNotifyData
 from ...kernel.actors import find_actor, find_foreman
 from ...kernel.group import load_group
 from ...kernel.ledger import append_event
 from ...util.fs import atomic_write_json, read_json
+from ..messaging.delivery import emit_system_notify
 from .group_space_paths import (
     resolve_space_root_from_group,
     resolve_space_root,
@@ -816,22 +818,16 @@ def _emit_sync_notification(
     }
     for actor_id in targets:
         try:
-            append_event(
-                group.ledger_path,
-                kind="system.notify",
-                group_id=str(group.group_id),
-                scope_key="",
-                by=notify_by,
-                data={
-                    "kind": kind,
-                    "priority": priority,
-                    "title": title,
-                    "message": message,
-                    "target_actor_id": actor_id,
-                    "requires_ack": False,
-                    "context": context,
-                },
+            notify = SystemNotifyData(
+                kind=kind,
+                priority=priority,
+                title=title,
+                message=message,
+                target_actor_id=actor_id,
+                requires_ack=False,
+                context=context,
             )
+            emit_system_notify(group, by=notify_by, notify=notify)
         except Exception:
             continue