@oneciel-ai/ciel-runtime 0.1.1 → 0.2.0

package/ciel_runtime_support/channel_message_policy.py

@@ -0,0 +1,256 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+
+_EXTERNAL_PROVENANCE_META_KEYS = (
+    "mcp_server",
+    "mcp_method",
+    "mcp_json",
+    "sse_source",
+    "sse_event",
+    "sse_json",
+    "stream_id",
+    "sse_id",
+    "cursor",
+    "event_id",
+    "message_id",
+    "source_message_id",
+    "rpc_id",
+)
+
+_UNIQUE_REFERENCE_META_KEYS = (
+    "message_id",
+    "source_message_id",
+    "assignment_id",
+    "poll_id",
+    "task_id",
+    "job_id",
+    "schedule_id",
+    "reminder_id",
+)
+
+_EVENT_ORDER_META_KEYS = (
+    "stream_id",
+    "cursor",
+    "sse_id",
+    "event_id",
+    "sequence",
+    "seq",
+)
+
+
+def _metadata(message: dict[str, Any]) -> dict[str, Any]:
+    meta = message.get("meta")
+    return meta if isinstance(meta, dict) else {}
+
+
+def string_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        text = value.strip()
+        if not text:
+            return []
+        if text.startswith("[") and text.endswith("]"):
+            try:
+                parsed = json.loads(text)
+            except (json.JSONDecodeError, TypeError):
+                parsed = None
+            if isinstance(parsed, list):
+                return string_list(parsed)
+        if text.lower() in ("all", "*"):
+            return ["all"]
+        return [text]
+    if isinstance(value, (list, tuple, set)):
+        out: list[str] = []
+        for item in value:
+            out.extend(string_list(item))
+        return out
+    text = str(value).strip()
+    return [text] if text else []
+
+
+def message_meta_sources(message: dict[str, Any]) -> list[dict[str, Any]]:
+    meta = _metadata(message)
+    sources: list[dict[str, Any]] = []
+    if meta:
+        sources.append(meta)
+    for envelope_key in ("mcp_json", "sse_json"):
+        envelope = meta.get(envelope_key)
+        if not isinstance(envelope, dict):
+            continue
+        params = envelope.get("params")
+        if isinstance(params, dict):
+            nested_meta = params.get("meta")
+            if isinstance(nested_meta, dict):
+                sources.append(nested_meta)
+        nested_meta = envelope.get("meta")
+        if isinstance(nested_meta, dict):
+            sources.append(nested_meta)
+    return sources
+
+
+def message_delivery_targets(message: dict[str, Any]) -> set[str]:
+    return {item.strip().lower() for item in string_list(message.get("delivery")) if item.strip()}
+
+
+def message_is_web_chat_request(message: dict[str, Any]) -> bool:
+    meta = _metadata(message)
+    source = str(meta.get("source") or "").strip().lower()
+    kind = str(message.get("kind") or meta.get("kind") or "").strip().lower()
+    return bool(
+        source == "ciel-runtime-web-chat"
+        or kind == "web_chat"
+        or meta.get("reply_channel")
+        or meta.get("reply_recipient")
+    )
+
+
+def message_has_external_provenance(message: dict[str, Any]) -> bool:
+    meta = _metadata(message)
+    if message_is_web_chat_request(message):
+        return True
+    return any(
+        meta.get(key) is not None and str(meta[key]).strip()
+        for key in _EXTERNAL_PROVENANCE_META_KEYS
+    )
+
+
+def message_has_unique_reference(message: dict[str, Any]) -> bool:
+    meta_sources = message_meta_sources(message)
+    if any(
+        meta.get(key) is not None and str(meta[key]).strip()
+        for key in _UNIQUE_REFERENCE_META_KEYS
+        for meta in meta_sources
+    ):
+        return True
+    for meta in meta_sources:
+        message_ids = meta.get("message_ids")
+        if isinstance(message_ids, (list, tuple)) and any(str(item).strip() for item in message_ids):
+            return True
+        if isinstance(message_ids, str) and message_ids.strip():
+            return True
+        rooms = meta.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_message_ids = room.get("message_ids")
+            if isinstance(room_message_ids, (list, tuple)) and any(
+                str(item).strip() for item in room_message_ids
+            ):
+                return True
+    return False
+
+
+def message_source_key(message: dict[str, Any]) -> str:
+    meta = _metadata(message)
+    return str(meta.get("mcp_server") or meta.get("sse_source") or meta.get("source") or "").strip()
+
+
+def message_kind_key(message: dict[str, Any]) -> str:
+    meta = _metadata(message)
+    meta_kind = str(
+        meta.get("kind")
+        or meta.get("type")
+        or meta.get("event_type")
+        or meta.get("eventType")
+        or meta.get("event")
+        or ""
+    ).strip()
+    return meta_kind or str(message.get("kind") or "").strip()
+
+
+def message_topic_key(message: dict[str, Any]) -> str:
+    meta = _metadata(message)
+    return str(
+        meta.get("key")
+        or meta.get("topic")
+        or meta.get("resource")
+        or meta.get("target")
+        or ""
+    ).strip()
+
+
+def message_order_value(message: dict[str, Any]) -> tuple[int, int, int] | None:
+    meta = _metadata(message)
+    for key in _EVENT_ORDER_META_KEYS:
+        raw = meta.get(key)
+        if raw is None:
+            continue
+        text = str(raw).strip()
+        if not text:
+            continue
+        match = re.fullmatch(r"(\d+)-(\d+)", text)
+        if match:
+            return (2, int(match.group(1)), int(match.group(2)))
+        if text.isdigit():
+            return (1, int(text), 0)
+    if message_has_external_provenance(message):
+        try:
+            message_id = int(message.get("id") or 0)
+        except (TypeError, ValueError):
+            message_id = 0
+        if message_id > 0:
+            return (3, message_id, 0)
+    return None
+
+
+def message_coalesce_key(message: dict[str, Any]) -> tuple[str, str, str, str, str] | None:
+    if message_delivery_targets(message) and not message_has_external_provenance(message):
+        return None
+    if message_is_web_chat_request(message) or message_has_unique_reference(message):
+        return None
+    source = message_source_key(message)
+    if not source or message_order_value(message) is None:
+        return None
+    meta = _metadata(message)
+    method = str(meta.get("mcp_method") or meta.get("sse_event") or "").strip()
+    kind = message_kind_key(message)
+    if not method and not kind:
+        return None
+    channel = str(
+        message.get("channel")
+        or meta.get("room_id")
+        or meta.get("room")
+        or meta.get("channel")
+        or ""
+    ).strip()
+    return (source, channel, method, kind, message_topic_key(message))
+
+
+def superseded_message_ids(messages: list[dict[str, Any]]) -> set[int]:
+    latest: dict[tuple[str, str, str, str, str], tuple[tuple[int, int, int], int]] = {}
+    superseded: set[int] = set()
+    for message in messages:
+        try:
+            message_id = int(message.get("id") or 0)
+        except (TypeError, ValueError):
+            continue
+        if message_id <= 0:
+            continue
+        key = message_coalesce_key(message)
+        order = message_order_value(message) if key is not None else None
+        if key is None or order is None:
+            continue
+        previous = latest.get(key)
+        if previous is None:
+            latest[key] = (order, message_id)
+            continue
+        previous_order, previous_id = previous
+        if (order, message_id) >= (previous_order, previous_id):
+            superseded.add(previous_id)
+            latest[key] = (order, message_id)
+        else:
+            superseded.add(message_id)
+    return superseded

package/ciel_runtime_support/channel_message_prompt.py

@@ -0,0 +1,305 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from ciel_runtime_support.channel_event_projection import (
+    CHANNEL_CONTROL_KINDS,
+    metadata_key_is_sensitive,
+    pretty_json_value,
+)
+from ciel_runtime_support.channel_message_policy import (
+    message_has_external_provenance,
+    message_is_web_chat_request,
+    message_meta_sources,
+    string_list,
+)
+
+
+NATIVE_ROUTER_CHANNEL_NAMES = frozenset({"ciel-runtime-router", "mcp-ciel-runtime-router"})
+
+_PROMPT_META_KEYS = (
+    "kind",
+    "type",
+    "event_type",
+    "eventType",
+    "status",
+    "mcp_server",
+    "mcp_method",
+    "room_name",
+    "room_label",
+    "room_id",
+    "room",
+    "channel",
+    "thread_id",
+    "parent_id",
+    "message_id",
+    "source_message_id",
+    "event_id",
+    "stream_id",
+    "sse_id",
+    "cursor",
+    "sequence",
+    "seq",
+    "assignment_id",
+    "poll_id",
+    "task_id",
+    "round_id",
+    "conversation_id",
+    "session_id",
+    "agent_id",
+    "agent_name",
+    "sender_id",
+    "sender",
+    "sender_name",
+    "author_id",
+    "author_name",
+    "recipient_id",
+    "recipient",
+    "recipient_name",
+    "mentioned_by",
+    "key",
+    "path",
+)
+
+
+def _metadata(message: dict[str, Any]) -> dict[str, Any]:
+    meta = message.get("meta")
+    return meta if isinstance(meta, dict) else {}
+
+
+def prompt_scalar(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int, float)):
+        return value
+    if isinstance(value, str):
+        text = value.strip()
+        return text if text and len(text) <= 240 else None
+    if isinstance(value, list):
+        out = [scalar for item in value[:10] if (scalar := prompt_scalar(item)) is not None]
+        if not out:
+            return None
+        try:
+            encoded = json.dumps(out, ensure_ascii=False, separators=(",", ":"), default=str)
+        except (TypeError, ValueError, OverflowError):
+            return None
+        return out if len(encoded) <= 300 else None
+    return None
+
+
+def prompt_metadata(message: dict[str, Any]) -> str:
+    meta = _metadata(message)
+    if not meta:
+        return ""
+    values = {
+        key: value
+        for key in _PROMPT_META_KEYS
+        if key in meta
+        and not metadata_key_is_sensitive(key)
+        and (value := prompt_scalar(meta.get(key))) is not None
+    }
+    kept: dict[str, Any] = {}
+    for key, value in values.items():
+        candidate = {**kept, key: value}
+        text = json.dumps(candidate, ensure_ascii=False, separators=(",", ":"), default=str)
+        if len(text) <= 900:
+            kept = candidate
+    return json.dumps(kept, ensure_ascii=False, separators=(",", ":"), default=str) if kept else ""
+
+
+def format_wake_prompt(message: dict[str, Any]) -> str:
+    channel = str(message.get("channel") or "default")
+    sender = str(message.get("sender_id") or "channel")
+    message_id = str(message.get("id") or "")
+    meta = _metadata(message)
+    room = str(meta.get("room_id") or meta.get("room") or channel)
+    thread = str(message.get("thread_id") or meta.get("thread_id") or "")
+    body = re.sub(r"\s+", " ", str(message.get("message") or "")).strip()
+    fields = [f"channel={channel}", f"room={room}", f"from={sender}"]
+    if message_id:
+        fields.append(f"id={message_id}")
+    if thread:
+        fields.append(f"thread={thread}")
+    metadata = prompt_metadata(message)
+    if metadata:
+        fields.append(f"metadata={metadata}")
+    return (
+        "[ciel-runtime external channel message] "
+        + " ".join(fields)
+        + f" text={json.dumps(body, ensure_ascii=False)}"
+    )
+
+
+def _format_web_chat_wake_item(message: dict[str, Any]) -> str:
+    channel = str(message.get("channel") or "default")
+    meta = _metadata(message)
+    reply_channel = str(meta.get("reply_channel") or channel)
+    thread = str(message.get("thread_id") or meta.get("thread_id") or reply_channel)
+    message_id = str(message.get("id") or "")
+    body = re.sub(r"\s+", " ", str(message.get("message") or "")).strip()
+    fields = [f"id={message_id}", f"channel={reply_channel}", f"thread={thread}"]
+    return " ".join(field for field in fields if not field.endswith("=")) + (
+        f" user={json.dumps(body, ensure_ascii=False)}"
+    )
+
+
+def _web_chat_reply_routes(messages: list[dict[str, Any]]) -> list[dict[str, str]]:
+    routes: list[dict[str, str]] = []
+    seen: set[tuple[str, str]] = set()
+    for message in messages:
+        if not message_is_web_chat_request(message):
+            continue
+        meta = _metadata(message)
+        channel = str(meta.get("reply_channel") or message.get("channel") or "default").strip()
+        thread = str(message.get("thread_id") or meta.get("thread_id") or channel).strip()
+        route = (channel, thread)
+        if route in seen:
+            continue
+        seen.add(route)
+        routes.append({"channel": channel, "thread_id": thread})
+    return routes
+
+
+def _web_chat_reply_instruction(messages: list[dict[str, Any]]) -> str:
+    routes = _web_chat_reply_routes(messages)
+    if not routes:
+        return ""
+    encoded_routes = json.dumps(routes, ensure_ascii=False, separators=(",", ":"))
+    return (
+        "[ciel-runtime web reply required] Do not leave the answer only in the terminal. "
+        "After completing the answer, call MCP server `ciel-runtime-router` tool "
+        "`send_message` once for each route in "
+        f"{encoded_routes}, with that channel and thread_id, recipients=[\"web\"], "
+        "delivery=[\"web\"], kind=\"reply\", and message set to the complete answer. "
+        "Use `send_file` on the same route for files."
+    )
+
+
+def format_web_chat_wake_batch_prompt(messages: list[dict[str, Any]]) -> str:
+    items = " ; ".join(_format_web_chat_wake_item(message) for message in messages)
+    prompt = f"[ciel-runtime web chat] {len(messages)} browser message(s): {items}"
+    instruction = _web_chat_reply_instruction(messages)
+    return f"{prompt}\n\n{instruction}" if instruction else prompt
+
+
+def wake_message_noise_reason(message: dict[str, Any]) -> str | None:
+    body = re.sub(r"\s+", " ", str(message.get("message") or "")).strip().lower()
+    kind = str(message.get("kind") or "").strip().lower()
+    if not body:
+        return "empty"
+    if kind in {"connection", "connected", "heartbeat", "keepalive"}:
+        return kind
+    if re.fullmatch(r"[a-z0-9_.:-]{1,80}\.(ws|sse)\.connected", body):
+        return "transport_connected"
+    return None
+
+
+def llm_message_skip_reason(message: dict[str, Any]) -> str | None:
+    visibility = str(message.get("visibility") or "user").strip().lower()
+    if visibility in {"hidden", "internal", "transport", "control", "system"}:
+        return f"visibility_{visibility}"
+    recipients = {item.strip().lower() for item in string_list(message.get("recipients"))}
+    if "internal" in recipients:
+        return "recipient_internal"
+    delivery = string_list(message.get("delivery"))
+    if delivery and not ({"all", "*", "llm"} & {item.strip().lower() for item in delivery}):
+        return "delivery_not_llm"
+    noise_reason = wake_message_noise_reason(message)
+    if noise_reason:
+        return noise_reason
+    meta = _metadata(message)
+    source = str(meta.get("sse_source") or meta.get("source") or "").strip().lower()
+    sender = str(message.get("sender_id") or meta.get("sender_id") or "").strip().lower()
+    if source in NATIVE_ROUTER_CHANNEL_NAMES or sender in NATIVE_ROUTER_CHANNEL_NAMES:
+        return "native_router_self_echo"
+    meta_kind = str(
+        meta.get("kind")
+        or meta.get("type")
+        or meta.get("event_type")
+        or meta.get("eventType")
+        or meta.get("event")
+        or meta.get("status")
+        or ""
+    ).strip().lower()
+    if meta_kind in CHANNEL_CONTROL_KINDS:
+        return meta_kind
+    if not delivery and not message_has_external_provenance(message):
+        return "unscoped_channel_message"
+    return None
+
+
+def wake_message_is_noise(message: dict[str, Any]) -> bool:
+    return wake_message_noise_reason(message) is not None
+
+
+def format_wake_batch_prompt(messages: list[dict[str, Any]]) -> str:
+    if len(messages) == 1:
+        return format_wake_prompt(messages[0])
+    parts: list[str] = []
+    for message in messages:
+        channel = str(message.get("channel") or "default")
+        sender = str(message.get("sender_id") or "channel")
+        message_id = str(message.get("id") or "")
+        meta = _metadata(message)
+        room = str(meta.get("room_id") or meta.get("room") or channel)
+        thread = str(message.get("thread_id") or meta.get("thread_id") or "")
+        body = str(message.get("message") or "")
+        fields = [f"id={message_id}", f"room={room}", f"from={sender}"]
+        if thread:
+            fields.append(f"thread={thread}")
+        metadata = prompt_metadata(message)
+        if metadata:
+            fields.append(f"metadata={metadata}")
+        parts.append("(" + " ".join(fields) + ") " + json.dumps(body, ensure_ascii=False))
+    return f"[ciel-runtime external channel messages] {len(messages)} new messages: " + " ; ".join(parts)
+
+
+def _source_header_scalar(value: Any) -> str:
+    if value is None or isinstance(value, (dict, list)):
+        return ""
+    text = re.sub(r"\s+", " ", str(value)).strip()
+    return text if text and len(text) <= 240 else ""
+
+
+def _first_source_header_value(message: dict[str, Any], keys: tuple[str, ...]) -> str:
+    for source in message_meta_sources(message):
+        for key in keys:
+            if metadata_key_is_sensitive(key):
+                continue
+            text = _source_header_scalar(source.get(key))
+            if text:
+                return text
+    return ""
+
+
+def _message_source_header(message: dict[str, Any]) -> str:
+    meta = _metadata(message)
+    if not any(isinstance(meta.get(key), (dict, list)) for key in ("mcp_json", "sse_json")):
+        return ""
+    room_name = _first_source_header_value(message, ("room_name", "room_label", "title", "name"))
+    room_id = _first_source_header_value(message, ("room_id", "room"))
+    channel = _first_source_header_value(message, ("channel",)) or _source_header_scalar(
+        message.get("channel")
+    )
+    source = room_name or room_id or channel
+    if not source:
+        return ""
+    source_text = f"{room_name} (room_id={room_id})" if room_name and room_id != room_name else source
+    return f"[Source channel] {source_text}"
+
+
+def message_llm_display_text(message: dict[str, Any]) -> str:
+    meta = _metadata(message)
+    for key in ("mcp_json", "sse_json"):
+        value = meta.get(key)
+        if isinstance(value, (dict, list)):
+            text = pretty_json_value(value)
+            header = _message_source_header(message)
+            return f"{header}\n\n{text}" if header else text
+    return str(message.get("message") if message.get("message") is not None else "")
+
+
+def format_llm_batch_prompt(messages: list[dict[str, Any]]) -> str:
+    prompt = "\n\n".join(message_llm_display_text(message) for message in messages)
+    instruction = _web_chat_reply_instruction(messages)
+    return f"{prompt}\n\n{instruction}" if instruction else prompt