@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/channel_event_identity.py

@@ -0,0 +1,212 @@
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+import time
+from typing import Any
+
+
+_EVENT_IDENTITY_META_KEYS = (
+    "stream_id",
+    "message_id",
+    "source_message_id",
+    "event_id",
+    "sse_id",
+    "cursor",
+    "sequence",
+    "seq",
+)
+
+_STABLE_META_KEYS = (
+    "cursor",
+    "stream_id",
+    "sse_id",
+    "event_id",
+    "message_id",
+    "source_message_id",
+    "sequence",
+    "seq",
+    "rpc_id",
+)
+
+
+def payload_hash(value: Any) -> str:
+    text = re.sub(r"\s+", " ", str(value or "")).strip()
+    return hashlib.sha256(text.encode("utf-8", errors="replace")).hexdigest()
+
+
+def message_time_seconds(value: Any) -> float:
+    text = str(value or "").strip()
+    if not text:
+        return 0.0
+    try:
+        return time.mktime(time.strptime(text[:19], "%Y-%m-%dT%H:%M:%S"))
+    except (OverflowError, ValueError):
+        return 0.0
+
+
+def _room_key(message: dict[str, Any], sources: list[dict[str, Any]]) -> str:
+    room_ids: list[str] = []
+    for source in sources:
+        rooms = source.get("rooms")
+        if not isinstance(rooms, str) or not rooms.strip():
+            continue
+        try:
+            parsed_rooms = json.loads(rooms)
+        except (json.JSONDecodeError, TypeError):
+            continue
+        if not isinstance(parsed_rooms, list):
+            continue
+        for room in parsed_rooms:
+            if not isinstance(room, dict):
+                continue
+            room_id = str(room.get("room_id") or room.get("room") or "").strip()
+            if room_id and room_id not in room_ids:
+                room_ids.append(room_id)
+    if room_ids:
+        return ",".join(sorted(room_ids))
+    for source in sources:
+        room = str(source.get("room_id") or source.get("room") or source.get("channel") or "").strip()
+        if room:
+            return room
+    return str(message.get("channel") or "").strip()
+
+
+def message_event_identity_key(message: dict[str, Any]) -> tuple[str, ...] | None:
+    meta = message.get("meta") if isinstance(message.get("meta"), dict) else {}
+    envelopes = [meta[key] for key in ("sse_json", "mcp_json") if isinstance(meta.get(key), dict)]
+    raw_message = message.get("message")
+    if isinstance(raw_message, str) and raw_message.strip().startswith("{"):
+        try:
+            parsed = json.loads(raw_message.strip())
+        except (json.JSONDecodeError, TypeError):
+            parsed = None
+        if isinstance(parsed, dict):
+            envelopes.append(parsed)
+
+    sources: list[dict[str, Any]] = [meta]
+    method = str(meta.get("mcp_method") or meta.get("sse_event") or "").strip()
+    content: Any = message.get("message")
+    for envelope in envelopes:
+        envelope_method = str(envelope.get("method") or "").strip()
+        if envelope_method:
+            method = envelope_method
+        params = envelope.get("params") if isinstance(envelope.get("params"), dict) else {}
+        if not params:
+            continue
+        sources.append(params)
+        params_meta = params.get("meta")
+        if isinstance(params_meta, dict):
+            sources.append(params_meta)
+        if params.get("content") is not None:
+            content = params.get("content")
+    if method and not method.startswith("notifications/"):
+        return None
+
+    kind = ""
+    for source in sources:
+        if not kind:
+            kind = str(
+                source.get("kind")
+                or source.get("type")
+                or source.get("event_type")
+                or source.get("eventType")
+                or ""
+            ).strip()
+    room = _room_key(message, sources)
+    for key in _EVENT_IDENTITY_META_KEYS:
+        for source in sources:
+            value = source.get(key)
+            stable_value = str(value).strip() if value is not None else ""
+            if stable_value:
+                return ("event", method, room, kind, key, stable_value, payload_hash(content))
+    return None
+
+
+def stable_dedupe_key(message: dict[str, Any]) -> tuple[str, ...] | None:
+    event_identity = message_event_identity_key(message)
+    if event_identity:
+        return ("stable",) + event_identity
+    meta = message.get("meta") if isinstance(message.get("meta"), dict) else {}
+    source = str(
+        meta.get("mcp_server")
+        or meta.get("sse_source")
+        or meta.get("source")
+        or message.get("sender_id")
+        or ""
+    ).strip()
+    method = str(meta.get("mcp_method") or "").strip()
+    channel = str(
+        message.get("channel")
+        or meta.get("room_id")
+        or meta.get("room")
+        or meta.get("channel")
+        or ""
+    ).strip()
+    kind = str(
+        message.get("kind")
+        or meta.get("kind")
+        or meta.get("type")
+        or meta.get("event_type")
+        or meta.get("eventType")
+        or ""
+    ).strip()
+    body_hash = payload_hash(message.get("message"))
+    for key in _STABLE_META_KEYS:
+        value = meta.get(key)
+        stable_value = str(value).strip() if value is not None else ""
+        if stable_value:
+            return ("stable", source, method, channel, kind, key, stable_value, body_hash)
+    mcp_json = meta.get("mcp_json")
+    if method.startswith("notifications/") and isinstance(mcp_json, dict):
+        try:
+            normalized = json.dumps(
+                mcp_json,
+                ensure_ascii=False,
+                sort_keys=True,
+                separators=(",", ":"),
+                default=str,
+            )
+        except (TypeError, ValueError, OverflowError):
+            normalized = ""
+        if normalized:
+            digest = hashlib.sha256(normalized.encode("utf-8", errors="replace")).hexdigest()
+            return ("stable", source, method, channel, kind, "mcp_json", digest, body_hash)
+    return None
+
+
+def fallback_dedupe_key(message: dict[str, Any]) -> tuple[str, ...] | None:
+    meta = message.get("meta") if isinstance(message.get("meta"), dict) else {}
+    method = str(meta.get("mcp_method") or "").strip()
+    if not method.startswith("notifications/"):
+        return None
+    body = re.sub(r"\s+", " ", str(message.get("message") or "")).strip()
+    if not body:
+        return None
+    source = str(
+        meta.get("mcp_server")
+        or meta.get("sse_source")
+        or meta.get("source")
+        or message.get("sender_id")
+        or ""
+    ).strip()
+    channel = str(
+        message.get("channel")
+        or meta.get("room_id")
+        or meta.get("room")
+        or meta.get("channel")
+        or ""
+    ).strip()
+    sender = str(
+        message.get("sender_id") or meta.get("sender_id") or meta.get("agent_id") or ""
+    ).strip()
+    kind = str(
+        message.get("kind")
+        or meta.get("kind")
+        or meta.get("type")
+        or meta.get("event_type")
+        or meta.get("eventType")
+        or ""
+    ).strip()
+    return ("fallback", source, method, channel, sender, kind, payload_hash(body))

package/ciel_runtime_support/channel_event_projection.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+CHANNEL_CONTROL_KINDS = {
+    "agent_presence",
+    "check-in",
+    "checkin",
+    "checkins",
+    "checked_in",
+    "colleague_presence",
+    "connection",
+    "connected",
+    "disconnect",
+    "disconnected",
+    "endpoint",
+    "heartbeat",
+    "initialized",
+    "init",
+    "keepalive",
+    "ping",
+    "pong",
+    "presence",
+    "ready",
+    "status",
+    "system",
+    "user_presence",
+}
+
+
+def first_present_dict_value(*sources: Any, keys: tuple[str, ...]) -> Any:
+    for source in sources:
+        if not isinstance(source, dict):
+            continue
+        for key in keys:
+            value = source.get(key)
+            if value is not None:
+                return value
+    return None
+
+
+def event_payload_text(value: Any, depth: int = 0) -> str | None:
+    if value is None or depth > 5:
+        return None
+    if isinstance(value, str):
+        return value.strip() or None
+    if not isinstance(value, dict):
+        return str(value)
+    direct = first_present_dict_value(value, keys=("content", "message", "text", "body", "summary"))
+    if isinstance(direct, str) and direct.strip():
+        return direct.strip()
+    if isinstance(direct, dict):
+        nested = event_payload_text(direct, depth + 1)
+        if nested:
+            return nested
+    for key in ("data", "event", "payload", "message", "notification", "item"):
+        nested = event_payload_text(value.get(key), depth + 1)
+        if nested:
+            return nested
+    event_type = value.get("type") or value.get("event_type") or value.get("kind")
+    if event_type:
+        payload = value.get("payload") if isinstance(value.get("payload"), dict) else value.get("data")
+        if payload is not None:
+            return f"{event_type}: {json.dumps(payload, ensure_ascii=False, separators=(',', ':'))}"
+        return str(event_type)
+    return None
+
+
+def pretty_json_text_or_raw(text: str) -> str:
+    try:
+        parsed = json.loads(text)
+    except Exception:
+        return text
+    return json.dumps(parsed, ensure_ascii=False, indent=2, default=str)
+
+
+def pretty_json_value(value: Any) -> str:
+    return json.dumps(value, ensure_ascii=False, indent=2, default=str)
+
+
+def notification_semantic_text_from_envelope(envelope: Any) -> str | None:
+    if not isinstance(envelope, dict):
+        return None
+    params = envelope.get("params") if isinstance(envelope.get("params"), dict) else {}
+    payload = envelope.get("payload") if isinstance(envelope.get("payload"), dict) else {}
+    data = params.get("data") if isinstance(params.get("data"), dict) else {}
+    event = params.get("event") if isinstance(params.get("event"), dict) else {}
+    nested_payload = (
+        data.get("payload")
+        if isinstance(data.get("payload"), dict)
+        else event.get("payload")
+        if isinstance(event.get("payload"), dict)
+        else {}
+    )
+    content = event_payload_text(nested_payload) or event_payload_text(payload)
+    for source in (data, event):
+        direct = first_present_dict_value(source, keys=("content", "message", "text", "body", "summary"))
+        content = content or event_payload_text(direct)
+    return content or event_payload_text(params) or event_payload_text(envelope)
+
+
+def event_meta_from_sources(*sources: Any) -> dict[str, Any]:
+    meta: dict[str, Any] = {}
+    keys = (
+        "room_id",
+        "room",
+        "channel",
+        "thread_id",
+        "parent_id",
+        "message_id",
+        "source_message_id",
+        "event_id",
+        "stream_id",
+        "sse_id",
+        "cursor",
+        "assignment_id",
+        "poll_id",
+        "task_id",
+        "sequence",
+        "seq",
+        "round_id",
+        "conversation_id",
+        "session_id",
+        "agent_id",
+        "agent_name",
+        "sender_id",
+        "sender",
+        "recipient_id",
+        "recipient",
+        "recipients",
+        "target_id",
+        "target",
+        "type",
+        "event_type",
+        "eventType",
+        "kind",
+        "timestamp",
+        "created_at",
+        "updated_at",
+        "status",
+        "priority",
+        "title",
+        "name",
+        "model",
+        "runtime",
+    )
+    for source in sources:
+        if not isinstance(source, dict):
+            continue
+        source_meta = source.get("meta")
+        if isinstance(source_meta, dict):
+            meta.update(source_meta)
+        for key in keys:
+            value = source.get(key)
+            if value is not None and key not in meta:
+                meta[key] = value
+    return meta
+
+
+def metadata_key_is_sensitive(key: str) -> bool:
+    return bool(re.search(r"(authorization|api[_-]?key|token|secret|password|credential|cookie)", key, re.I))
+
+
+def json_safe_metadata(value: Any, depth: int = 0) -> Any:
+    if depth > 8:
+        return "<max-depth>"
+    if value is None or isinstance(value, (bool, int, float)):
+        return value
+    if isinstance(value, str):
+        return value if len(value) <= 8000 else value[:8000] + "...<truncated>"
+    if isinstance(value, list):
+        out = [json_safe_metadata(item, depth + 1) for item in value[:200]]
+        if len(value) > 200:
+            out.append(f"...<{len(value) - 200} more>")
+        return out
+    if isinstance(value, dict):
+        out: dict[str, Any] = {}
+        items = list(value.items())
+        for key, item in items[:200]:
+            safe_key = str(key)
+            out[safe_key] = "[redacted]" if metadata_key_is_sensitive(safe_key) else json_safe_metadata(item, depth + 1)
+        if len(items) > 200:
+            out["..."] = f"<{len(items) - 200} more>"
+        return out
+    return str(value)
+
+
+def compact_json_for_prompt(value: Any, max_chars: int = 2400) -> str:
+    try:
+        text = json.dumps(value, ensure_ascii=False, separators=(",", ":"), default=str)
+    except Exception:
+        text = str(value)
+    if len(text) <= max_chars:
+        return text
+    return text[: max_chars - 16] + "...<truncated>"
+
+
+def channel_event_is_user_visible(
+    kind: str,
+    method: str,
+    event_name: str,
+    content: str,
+    meta: dict[str, Any],
+) -> bool:
+    normalized_kind = str(kind or "").strip().lower().replace("_", ".").replace("/", ".")
+    normalized_method = str(method or "").strip().lower()
+    normalized_event = str(event_name or "").strip().lower()
+    meta_type = str(
+        meta.get("type")
+        or meta.get("event_type")
+        or meta.get("eventType")
+        or meta.get("kind")
+        or meta.get("status")
+        or ""
+    ).strip().lower()
+    if normalized_kind in CHANNEL_CONTROL_KINDS or normalized_event in CHANNEL_CONTROL_KINDS:
+        return False
+    if meta_type in CHANNEL_CONTROL_KINDS:
+        return False
+    if meta.get("jsonrpc") is not None:
+        if normalized_method.startswith("notifications/claude/"):
+            return True
+        if normalized_method in {"notifications/message", "notifications/chat", "notifications/event"}:
+            return True
+        return False
+    return bool(content.strip())
+
+
+def sse_payload_to_chat_payload(
+    data_text: str,
+    event_name: str,
+    defaults: dict[str, Any],
+    event_id: str | None = None,
+) -> dict[str, Any] | None:
+    raw_text = data_text or ""
+    stripped_text = raw_text.strip()
+    if not stripped_text or stripped_text == "[DONE]":
+        return None
+    if (event_name or "").strip().lower() == "endpoint":
+        return None
+    try:
+        parsed: Any = json.loads(stripped_text)
+    except Exception:
+        parsed = None
+    meta: dict[str, Any] = {
+        "sse_event": event_name or "message",
+        "sse_source": defaults.get("name") or "",
+    }
+    if event_id:
+        meta["sse_id"] = event_id
+    content = raw_text
+    kind = "sse"
+    method = str(event_name or "message")
+    event_filter = defaults.get("event_filter")
+    allowed_events = (
+        {str(item).strip() for item in event_filter if str(item).strip()}
+        if isinstance(event_filter, list)
+        else set()
+    )
+    if isinstance(parsed, dict):
+        method = str(parsed.get("method") or event_name or "message")
+        meta["sse_json"] = json_safe_metadata(parsed)
+        if parsed.get("jsonrpc") is not None:
+            meta["jsonrpc"] = parsed.get("jsonrpc")
+        if parsed.get("id") is not None:
+            meta["rpc_id"] = parsed.get("id")
+        if parsed.get("method") is not None:
+            meta["mcp_method"] = parsed.get("method")
+        params = parsed.get("params") if isinstance(parsed.get("params"), dict) else {}
+        payload = parsed.get("payload") if isinstance(parsed.get("payload"), dict) else {}
+        data = params.get("data") if isinstance(params.get("data"), dict) else {}
+        event = params.get("event") if isinstance(params.get("event"), dict) else {}
+        nested_payload = (
+            data.get("payload")
+            if isinstance(data.get("payload"), dict)
+            else event.get("payload")
+            if isinstance(event.get("payload"), dict)
+            else {}
+        )
+        meta.update(event_meta_from_sources(parsed, params, payload, data, event, nested_payload))
+        nested_content = event_payload_text(nested_payload) or event_payload_text(payload)
+        for source in (data, event):
+            direct = first_present_dict_value(
+                source,
+                keys=("content", "message", "text", "body", "summary"),
+            )
+            nested_content = nested_content or event_payload_text(direct)
+        content = nested_content or event_payload_text(params) or event_payload_text(parsed) or content
+        kind = method.replace("notifications/claude/", "").replace("/", ".") if method else "sse"
+        if not parsed.get("method") and meta.get("kind"):
+            kind = str(meta.get("kind"))
+    if allowed_events and method not in allowed_events and (event_name or "message") not in allowed_events:
+        return None
+    if not channel_event_is_user_visible(kind, method, event_name, content, meta):
+        return None
+    channel = meta.get("channel") or meta.get("room_id") or meta.get("room") or defaults.get("channel") or "default"
+    return {
+        "channel": channel,
+        "sender_id": meta.get("sender_id") or meta.get("sender") or meta.get("agent_id") or defaults.get("sender_id") or "sse",
+        "recipients": meta.get("recipients")
+        or meta.get("recipient_id")
+        or meta.get("recipient")
+        or defaults.get("recipient")
+        or defaults.get("recipients")
+        or "all",
+        "thread_id": meta.get("thread_id"),
+        "parent_id": meta.get("parent_id"),
+        "kind": kind,
+        "message": pretty_json_text_or_raw(raw_text),
+        "meta": meta,
+        "visibility": "user",
+        "delivery": ["llm"],
+    }

package/ciel_runtime_support/channel_inflight.py

@@ -0,0 +1,127 @@
+"""State machine for channel wake prompts awaiting turn completion."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable, Literal
+
+
+InflightAction = Literal["none", "completed", "unseen_retry", "stale", "waiting"]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelInflightSnapshot:
+    message_id: int
+    cursor: int | None
+    wake_state: str
+    started_at: float
+    logged_at: float
+    now: float
+    last_id: int
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelInflightPolicy:
+    unseen_retry_seconds: float
+    waiting_log_interval: float
+    is_stale: Callable[[str, float, float], bool]
+    commit_cursor_on_stale: bool
+    log_namespace: str
+    stale_event: str
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelInflightEffects:
+    commit_cursor: Callable[[int], Any]
+    complete_wake: Callable[[int], Any]
+    release_wake: Callable[[int], Any]
+    ensure_cursor: Callable[[], int]
+    log: Callable[[str, str], Any]
+
+
+@dataclass(frozen=True, slots=True)
+class ChannelInflightUpdate:
+    action: InflightAction
+    message_id: int | None
+    cursor: int | None
+    started_at: float
+    logged_at: float
+    pending_recheck: bool
+    last_id: int
+
+
+def advance_channel_inflight(
+    snapshot: ChannelInflightSnapshot,
+    policy: ChannelInflightPolicy,
+    effects: ChannelInflightEffects,
+) -> ChannelInflightUpdate:
+    message_id = snapshot.message_id
+    state = snapshot.wake_state
+    age = snapshot.now - snapshot.started_at
+    if state == "completed":
+        if snapshot.cursor is not None:
+            effects.commit_cursor(snapshot.cursor)
+        effects.complete_wake(message_id)
+        effects.log(
+            "INFO",
+            f"{policy.log_namespace}_confirmed message_id={message_id} cursor={snapshot.cursor or '-'}",
+        )
+        return _reset("completed", snapshot)
+    if state == "missing" and snapshot.started_at > 0 and age >= policy.unseen_retry_seconds:
+        effects.release_wake(message_id)
+        effects.log(
+            "WARN",
+            f"{policy.log_namespace}_unseen_retry message_id={message_id} age={age:.1f}s",
+        )
+        return _reset("unseen_retry", snapshot, last_id=effects.ensure_cursor(), logged_at=snapshot.now)
+    if policy.is_stale(state, snapshot.started_at, snapshot.now):
+        if policy.commit_cursor_on_stale and snapshot.cursor is not None:
+            effects.commit_cursor(snapshot.cursor)
+        effects.release_wake(message_id)
+        effects.log(
+            "WARN",
+            f"{policy.log_namespace}_{policy.stale_event} message_id={message_id} state={state} "
+            f"age={age:.1f}s cursor={snapshot.cursor or '-'}",
+        )
+        return _reset("stale", snapshot, last_id=effects.ensure_cursor(), logged_at=snapshot.now)
+    if snapshot.now - snapshot.logged_at >= policy.waiting_log_interval:
+        effects.log(
+            "INFO",
+            f"{policy.log_namespace}_waiting_for_turn_completion message_id={message_id} state={state}",
+        )
+        return ChannelInflightUpdate(
+            action="waiting",
+            message_id=message_id,
+            cursor=snapshot.cursor,
+            started_at=snapshot.started_at,
+            logged_at=snapshot.now,
+            pending_recheck=False,
+            last_id=snapshot.last_id,
+        )
+    return ChannelInflightUpdate(
+        action="none",
+        message_id=message_id,
+        cursor=snapshot.cursor,
+        started_at=snapshot.started_at,
+        logged_at=snapshot.logged_at,
+        pending_recheck=False,
+        last_id=snapshot.last_id,
+    )
+
+
+def _reset(
+    action: InflightAction,
+    snapshot: ChannelInflightSnapshot,
+    *,
+    last_id: int | None = None,
+    logged_at: float | None = None,
+) -> ChannelInflightUpdate:
+    return ChannelInflightUpdate(
+        action=action,
+        message_id=None,
+        cursor=None,
+        started_at=0.0,
+        logged_at=snapshot.logged_at if logged_at is None else logged_at,
+        pending_recheck=True,
+        last_id=snapshot.last_id if last_id is None else last_id,
+    )