@inline-chat/hermes-agent-adapter 0.0.8 → 0.0.10

package/plugin/inline/tools.py

@@ -8,6 +8,8 @@ import urllib.error
 import urllib.request
 from typing import Any, Dict, Iterable, Optional
 
+from .message_actions import build_inline_agent_action_id
+
 try:
     from tools.registry import tool_error, tool_result
 except Exception:  # pragma: no cover - used by lightweight package tests
@@ -27,6 +29,11 @@ _MAX_MESSAGE_IDS = 100
 _MAX_INLINE_ID = 9_223_372_036_854_775_807
 _DEFAULT_HISTORY_LIMIT = 20
 _MAX_TEXT_CHARS = 4000
+_MAX_ACTION_ROWS = 8
+_MAX_ACTIONS_PER_ROW = 8
+_MAX_ACTION_LABEL_CHARS = 64
+_MAX_ACTION_CALLBACK_BYTES = 1024
+_MAX_ACTION_COPY_TEXT_CHARS = 4096
 _MAX_QUERY_CHARS = 500
 _MAX_RESULT_TEXT_CHARS = 1600
 _MAX_MESSAGE_ENTITIES = 12
@@ -58,7 +65,11 @@ INLINE_PLATFORM_GUIDANCE = (
     "while keeping the stable user ID in the link target. Link chats as "
     "[title](inline://chat?id=123), and link reply threads as "
     "[title](inline://thread?id=123). In Inline, reply threads are chat ids; "
-    "do not treat thread ids as reply/quote message ids. Use ordinary Markdown "
+    "do not treat thread ids as reply/quote message ids. Supported Markdown is "
+    "emphasis, inline or fenced code, links, headings, lists or checklists, "
+    "quotes, tables, separators, and HTTP(S) images. Do not rely on "
+    "strikethrough, footnotes, or arbitrary HTML; unsupported or ambiguous "
+    "incomplete syntax remains visible text. Use ordinary Markdown "
     "tables for tabular data, never fenced-code tables. For collapsible work, "
     "use <details open>, then <summary>Title</summary>, body Markdown, and "
     "</details>; put kind=\"progress\" on summary only while work is in progress. "
@@ -68,11 +79,12 @@ INLINE_PLATFORM_GUIDANCE = (
 _sidecar: Dict[str, Any] = {}
 
 _ACTION_MANIFEST = [
+    ("send_message", "(chat_id?|user_id?, text, buttons?)", "Send a message, including optional agent-owned buttons."),
     ("get_chat", "(chat_id?)", "Get metadata for a chat or reply thread."),
     ("get_messages", "(chat_id?, message_ids)", "Fetch specific Inline messages by ID."),
     ("get_history", "(chat_id?, limit?, anchor_id?)", "Fetch recent or anchored Inline history."),
     ("search_messages", "(chat_id?|user_id?, query, limit?, offset_id?)", "Search Inline message text in a chat, thread, or DM."),
-    ("edit_message", "(chat_id?|user_id?, message_id, text)", "Edit a bot-owned message."),
+    ("edit_message", "(chat_id?|user_id?, message_id, text, buttons?)", "Edit a bot-owned message and optionally replace or clear its buttons."),
     ("delete_message", "(chat_id?|user_id?, message_id)", "Delete a bot-owned message."),
     ("add_reaction", "(chat_id?|user_id?, message_id?, emoji)", "Add a reaction to an Inline message."),
     ("remove_reaction", "(chat_id?|user_id?, message_id?, emoji)", "Remove the bot's reaction from an Inline message."),
@@ -83,6 +95,10 @@ _ACTION_MANIFEST = [
     ("create_thread", "(parent_chat_id?, parent_message_id?, title?)", "Create an Inline reply thread."),
     ("create_chat", "(title, space_id?, participant_user_ids?, is_public?)", "Create a top-level Inline thread/chat."),
     ("create_agent", "(name, skill_key?, instructions?)", "Create a named Inline Agent backed by this bot."),
+    ("get_agent", "(agent_id)", "Inspect one Agent backed by this bot."),
+    ("list_agents", "()", "List Agents backed by this bot."),
+    ("update_agent", "(agent_id, fields...)", "Update a named Inline Agent; empty optional fields clear them."),
+    ("delete_agent", "(agent_id)", "Delete an Agent backed by this bot."),
     ("set_presence", "(chat_id?|user_id?, kind, comment?)", "Set the bot avatar presence/status message."),
 ]
 _ACTIONS = [name for name, _, _ in _ACTION_MANIFEST]
@@ -139,7 +155,9 @@ def tool_context_prompt(
         return None
     lines = [
         "- The `inline` tool is available for Inline history, search, exact message lookup, reactions, pins, and explicit thread management.",
-        "- Do not use the `inline` tool to send normal replies; return reply text normally and Hermes will deliver it to the current chat or thread.",
+        "- Return normal replies as text. Use inline send_message only to create a message with action buttons or to send into a different destination.",
+        "- An Inline action-button turn names its source message. A normal response replaces that message; omitted buttons clear the old buttons. Use edit_message with buttons to replace them explicitly.",
+        "- If edit_message already finalized the source action card during this turn, return NO_REPLY so the automatic final response does not overwrite that edit.",
     ]
     if thread_id:
         lines.append(f"- Current Inline reply thread: `{thread_id}`. Use this as `chat_id` for thread-scoped reads.")
@@ -166,7 +184,8 @@ INLINE_TOOL_SCHEMA = {
         + "\n".join(f"  {name}{sig} - {desc}" for name, sig, desc in _ACTION_MANIFEST)
         + "\n\n"
         "When chat_id is omitted, the tool uses the current Inline reply thread if present, otherwise the current chat. "
-        "Do not use this tool to send the normal assistant reply; return text normally and Hermes will deliver it. "
+        "Return normal assistant replies as text. Use send_message only for a button card or a different destination. "
+        "Agent-owned button presses return as ordinary turns, and the normal response replaces the source card while clearing omitted buttons. "
         "Use create_thread with the current triggering message as parent_message_id to move large top-level discussions into a reply thread. "
         "Use create_chat to create a new top-level destination outside the current conversation; it defaults to private, and public creation must explicitly set is_public with a space_id. "
         "Use search_messages for exact catch-up across older chat history. "
@@ -196,11 +215,12 @@ INLINE_TOOL_SCHEMA = {
             },
             "title": {"type": "string", "description": "Thread title. Required for create_chat and optional for create_thread."},
             "name": {"type": "string", "description": "Agent name for create_agent."},
+            "agent_id": {"type": "string", "description": "Globally unique Inline Agent ID for get_agent, update_agent, or delete_agent."},
             "handle": {"type": "string", "description": "Optional Agent handle."},
-            "skill_key": {"type": "string", "description": "Optional harness skill key for create_agent."},
-            "instructions": {"type": "string", "description": "Optional specialized Agent instructions."},
-            "description": {"type": "string", "description": "Optional thread description for create_thread or create_chat."},
-            "emoji": {"type": "string", "description": "Optional thread emoji for create_thread/create_chat, or reaction emoji for reaction actions."},
+            "skill_key": {"type": "string", "description": "Optional harness skill key for create_agent or update_agent."},
+            "instructions": {"type": "string", "description": "Optional specialized Agent instructions for create_agent or update_agent."},
+            "description": {"type": "string", "description": "Optional thread or Agent description."},
+            "emoji": {"type": "string", "description": "Optional thread or Agent emoji, or reaction emoji for reaction actions."},
             "space_id": {"type": "string", "description": "Optional parent space ID for create_chat."},
             "participant_user_ids": {
                 "type": "array",
@@ -213,8 +233,26 @@ INLINE_TOOL_SCHEMA = {
                 "description": "Whether create_chat is visible to the parent space. Defaults to false and requires space_id when true.",
             },
             "query": {"type": "string", "description": "Search query for search_messages."},
-            "text": {"type": "string", "description": "Message text for edit_message."},
-            "parse_markdown": {"type": "boolean", "description": "Whether Inline should parse Markdown. Defaults to true."},
+            "text": {"type": "string", "description": "Message text for send_message or edit_message."},
+            "buttons": {
+                "type": "array",
+                "maxItems": _MAX_ACTION_ROWS,
+                "description": "Button rows. Omit to preserve buttons on edit; pass [] to clear them.",
+                "items": {
+                    "type": "array",
+                    "maxItems": _MAX_ACTIONS_PER_ROW,
+                    "items": {
+                        "type": "object",
+                        "properties": {
+                            "text": {"type": "string", "description": "Visible button label."},
+                            "callback_data": {"type": "string", "description": "Opaque data returned in an agent turn when pressed."},
+                            "copy_text": {"type": "string", "description": "Text copied locally instead of invoking the agent."},
+                        },
+                        "required": ["text"],
+                    },
+                },
+            },
+            "parse_markdown": {"type": "boolean", "description": "Whether Inline should parse its supported Markdown surface. Defaults to true; false preserves the supplied syntax literally."},
             "limit": {
                 "type": "integer",
                 "minimum": 1,
@@ -261,6 +299,17 @@ def _handle_inline_tool(args: Dict[str, Any], **_: Any) -> str:
 
 
 def _request_for_action(action: str, args: Dict[str, Any]) -> tuple[str, Dict[str, Any]]:
+    if action == "send_message":
+        body = {
+            "target": _target(args),
+            "text": _required_str(args, "text", max_chars=_MAX_TEXT_CHARS),
+            "parseMarkdown": _bool(args.get("parse_markdown"), True),
+        }
+        actions = _message_actions(args)
+        if actions is not None:
+            body["actions"] = actions
+        return "/send", body
+
     if action == "get_chat":
         return "/chat", {"target": _target(args)}
 
@@ -292,12 +341,16 @@ def _request_for_action(action: str, args: Dict[str, Any]) -> tuple[str, Dict[st
         return "/search", body
 
     if action == "edit_message":
-        return "/edit", {
+        body = {
             "target": _target(args),
             "messageId": _required_id(args, "message_id"),
             "text": _required_str(args, "text", max_chars=_MAX_TEXT_CHARS),
             "parseMarkdown": _bool(args.get("parse_markdown"), True),
         }
+        actions = _message_actions(args)
+        if actions is not None:
+            body["actions"] = actions
+        return "/edit", body
 
     if action == "delete_message":
         return "/delete", {
@@ -376,6 +429,26 @@ def _request_for_action(action: str, args: Dict[str, Any]) -> tuple[str, Dict[st
                 body[key] = value
         return "/create-agent", body
 
+    if action == "get_agent":
+        return "/get-agent", {"agentId": _required_id(args, "agent_id")}
+
+    if action == "list_agents":
+        return "/list-agents", {}
+
+    if action == "update_agent":
+        body = {"agentId": _required_id(args, "agent_id")}
+        if "name" in args:
+            body["name"] = _required_str(args, "name", max_chars=256)
+        for key in ("handle", "emoji", "description", "skill_key", "instructions"):
+            if key in args and args.get(key) is not None:
+                body[key] = _str(args.get(key))
+        if len(body) == 1:
+            raise InlineToolError("update_agent requires at least one field", "bad_format")
+        return "/update-agent", body
+
+    if action == "delete_agent":
+        return "/delete-agent", {"agentId": _required_id(args, "agent_id")}
+
     if action == "set_presence":
         kind = _str(args.get("kind"))
         if kind not in _PRESENCE_KINDS:
@@ -504,7 +577,75 @@ def _message_id_or_current(args: Dict[str, Any]) -> str:
     return message_id
 
 
+def _message_actions(args: Dict[str, Any]) -> Optional[Dict[str, Any]]:
+    if "buttons" not in args:
+        return None
+    raw_rows = args.get("buttons")
+    if not isinstance(raw_rows, list):
+        raise InlineToolError("buttons must be an array of button rows", "bad_format")
+    if len(raw_rows) > _MAX_ACTION_ROWS:
+        raise InlineToolError(f"buttons supports at most {_MAX_ACTION_ROWS} rows", "bad_format")
+
+    rows: list[Dict[str, Any]] = []
+    for row_index, raw_row in enumerate(raw_rows):
+        if not isinstance(raw_row, list) or not raw_row:
+            raise InlineToolError("each buttons row must be a non-empty array", "bad_format")
+        if len(raw_row) > _MAX_ACTIONS_PER_ROW:
+            raise InlineToolError(
+                f"each buttons row supports at most {_MAX_ACTIONS_PER_ROW} buttons",
+                "bad_format",
+            )
+        actions: list[Dict[str, str]] = []
+        for action_index, raw_button in enumerate(raw_row):
+            if not isinstance(raw_button, dict):
+                raise InlineToolError("each button must be an object", "bad_format")
+            label = _str(raw_button.get("text"))
+            if not label:
+                raise InlineToolError("button text is required", "bad_format")
+            if len(label) > _MAX_ACTION_LABEL_CHARS:
+                raise InlineToolError(
+                    f"button text supports at most {_MAX_ACTION_LABEL_CHARS} characters",
+                    "bad_format",
+                )
+            has_callback = "callback_data" in raw_button
+            has_copy = "copy_text" in raw_button
+            if has_callback == has_copy:
+                raise InlineToolError(
+                    "each button requires exactly one of callback_data or copy_text",
+                    "bad_format",
+                )
+            action: Dict[str, str] = {
+                "id": build_inline_agent_action_id(row_index, action_index),
+                "text": label,
+            }
+            if has_callback:
+                callback_data = raw_button.get("callback_data")
+                if not isinstance(callback_data, str):
+                    raise InlineToolError("callback_data must be a string", "bad_format")
+                if len(callback_data.encode("utf-8")) > _MAX_ACTION_CALLBACK_BYTES:
+                    raise InlineToolError(
+                        f"callback_data supports at most {_MAX_ACTION_CALLBACK_BYTES} UTF-8 bytes",
+                        "bad_format",
+                    )
+                action["callback"] = callback_data
+            else:
+                copy_text = raw_button.get("copy_text")
+                if not isinstance(copy_text, str) or not copy_text:
+                    raise InlineToolError("copy_text must be a non-empty string", "bad_format")
+                if len(copy_text) > _MAX_ACTION_COPY_TEXT_CHARS:
+                    raise InlineToolError(
+                        f"copy_text supports at most {_MAX_ACTION_COPY_TEXT_CHARS} characters",
+                        "bad_format",
+                    )
+                action["copyText"] = copy_text
+            actions.append(action)
+        rows.append({"actions": actions})
+    return {"rows": rows}
+
+
 def _compact_result(action: str, result: Dict[str, Any]) -> Dict[str, Any]:
+    if action in {"send_message", "edit_message"}:
+        return {"messageId": _str(result.get("messageId"))}
     if action == "get_chat":
         return _compact_chat(result)
     if action in {"get_messages", "get_history", "search_messages"}:
@@ -545,8 +686,17 @@ def _compact_result(action: str, result: Dict[str, Any]) -> Dict[str, Any]:
             "chat": _compact_chat(result.get("chat") if isinstance(result.get("chat"), dict) else {}),
             "dialog": _summarize_value(result.get("dialog")) if result.get("dialog") is not None else None,
         }
-    if action == "create_agent":
+    if action in {"create_agent", "update_agent"}:
         return {"agent": _summarize_value(result.get("agent"))}
+    if action == "get_agent":
+        return {
+            "bot": _summarize_value(result.get("bot")),
+            "agent": _summarize_value(result.get("agent")),
+        }
+    if action == "list_agents":
+        return {"agents": _summarize_value(result.get("agents"))}
+    if action == "delete_agent":
+        return {"agentId": _str(result.get("agentId") or result.get("agent_id"))}
     return result