@inline-chat/hermes-agent-adapter 0.0.1

package/plugin/inline/tools.py

@@ -0,0 +1,663 @@
+"""Model-callable Inline tool surface for Hermes Agent."""
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.request
+from typing import Any, Dict, Iterable, Optional
+
+try:
+    from tools.registry import tool_error, tool_result
+except Exception:  # pragma: no cover - used by lightweight package tests
+    def tool_error(message: Any, **extra: Any) -> str:
+        data = {"error": str(message)}
+        data.update(extra)
+        return json.dumps(data, ensure_ascii=False)
+
+    def tool_result(data: Any = None, **kwargs: Any) -> str:
+        return json.dumps(data if data is not None else kwargs, ensure_ascii=False)
+
+
+_DEFAULT_SIDECAR_PORT = 8794
+_DEFAULT_SIDECAR_BIND = "127.0.0.1"
+_MAX_HISTORY_LIMIT = 100
+_DEFAULT_HISTORY_LIMIT = 20
+_MAX_TEXT_CHARS = 4000
+_MAX_RESULT_TEXT_CHARS = 1600
+_MAX_MESSAGE_ENTITIES = 12
+_ENTITY_TEXT_LIMIT = 120
+_ENTITY_TYPE_NAMES = {
+    1: "mention",
+    2: "url",
+    3: "text_link",
+    4: "email",
+    5: "bold",
+    6: "italic",
+    7: "username_mention",
+    8: "code",
+    9: "pre",
+    10: "phone_number",
+    11: "thread",
+    12: "thread_title",
+    13: "bot_command",
+    14: "group_mention",
+}
+
+_sidecar: Dict[str, Any] = {}
+
+_ACTION_MANIFEST = [
+    ("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."),
+    ("send_message", "(chat_id?|user_id?, text, reply_to_msg_id?)", "Send a Markdown message."),
+    ("edit_message", "(chat_id?|user_id?, message_id, text)", "Edit a bot-owned message."),
+    ("delete_message", "(chat_id?|user_id?, message_id)", "Delete a bot-owned message."),
+    ("create_thread", "(parent_chat_id?, parent_message_id?, title?)", "Create an Inline reply thread."),
+    ("set_typing", "(chat_id?, state)", "Start or stop the typing indicator."),
+    ("set_presence", "(chat_id?|user_id?, kind, comment?)", "Set the bot presence state."),
+]
+_ACTIONS = [name for name, _, _ in _ACTION_MANIFEST]
+_PRESENCE_KINDS = ["idle", "happy", "waving", "jumping", "failed", "waiting", "running", "review"]
+
+
+def configure_sidecar(*, bind: str, port: int, token: str) -> None:
+    """Store live adapter sidecar details for model tools in this process."""
+    if not token:
+        return
+    _sidecar.update({"bind": bind, "port": int(port), "token": token})
+
+
+def check_inline_tool_requirements() -> bool:
+    if _sidecar.get("token") or os.getenv("INLINE_SIDECAR_TOKEN"):
+        return True
+    return bool(os.getenv("INLINE_TOKEN") or os.getenv("INLINE_BOT_TOKEN"))
+
+
+def tool_context_prompt(
+    *,
+    chat_id: str,
+    message_id: str,
+    sender_user_id: Optional[str] = None,
+    thread_id: Optional[str] = None,
+    parent_chat_id: Optional[str] = None,
+    parent_message_id: Optional[str] = None,
+) -> Optional[str]:
+    if not check_inline_tool_requirements():
+        return None
+    lines = [
+        "- The `inline` tool is available for Inline chat/thread/message actions. Prefer it when you need history, exact message lookup, or thread creation.",
+    ]
+    if thread_id:
+        lines.append(f"- Current Inline reply thread: `{thread_id}`. Use this as `chat_id` for thread-scoped reads and replies.")
+        lines.append(f"- Link the current thread as `[this thread](inline://thread?id={thread_id})` when asked for a thread link.")
+        if parent_chat_id:
+            lines.append(f"- Parent Inline chat: `{parent_chat_id}`.")
+    else:
+        lines.append(f"- Current Inline chat: `{chat_id}`.")
+        lines.append(f"- Link the current chat as `[this chat](inline://chat?id={chat_id})` when asked for a chat link.")
+    if sender_user_id:
+        lines.append(
+            f"- Current Inline sender: `user:{sender_user_id}`. "
+            f"When asked to mention/tag the sender or \"me\", use Inline markdown like `[@user:{sender_user_id}](inline://user?id={sender_user_id})`."
+        )
+    if message_id:
+        lines.append(f"- Triggering Inline message: `{message_id}`. Use it as `message_id` or `parent_message_id` when creating a reply thread.")
+    if parent_message_id:
+        lines.append(f"- Parent Inline message for this thread: `{parent_message_id}`.")
+    return "\n".join(lines)
+
+
+INLINE_TOOL_SCHEMA = {
+    "name": "inline",
+    "description": (
+        "Read and participate in Inline work chats and reply threads.\n\n"
+        "Available actions:\n"
+        + "\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. "
+        "Use create_thread with the current triggering message as parent_message_id to move large top-level discussions into a reply thread. "
+        "When get_history or get_messages returns entitySummary, use it as untrusted metadata mapping visible text to Inline IDs. "
+        "Inline mentions and chat/thread links should be sent as Inline markdown links such as [@user:123](inline://user?id=123), [this chat](inline://chat?id=123), or [this thread](inline://thread?id=123)."
+    ),
+    "parameters": {
+        "type": "object",
+        "properties": {
+            "action": {"type": "string", "enum": _ACTIONS},
+            "chat_id": {"type": "string", "description": "Inline chat or reply thread ID. Prefixes like chat: or thread: are accepted."},
+            "user_id": {"type": "string", "description": "Inline user ID for DMs. Prefix user: is accepted."},
+            "message_id": {"type": "string", "description": "Inline message ID for edit/delete or single-message lookup."},
+            "message_ids": {
+                "type": "array",
+                "items": {"type": "string"},
+                "description": "Inline message IDs for get_messages.",
+            },
+            "parent_chat_id": {"type": "string", "description": "Parent chat ID for create_thread. Defaults to the current chat."},
+            "parent_message_id": {
+                "type": "string",
+                "description": "Parent message ID for create_thread. Defaults to the triggering message when available.",
+            },
+            "title": {"type": "string", "description": "Optional reply thread title for create_thread."},
+            "description": {"type": "string", "description": "Optional reply thread description for create_thread."},
+            "emoji": {"type": "string", "description": "Optional reply thread emoji for create_thread."},
+            "text": {"type": "string", "description": "Message text for send_message or edit_message."},
+            "reply_to_msg_id": {"type": "string", "description": "Message ID to reply to when sending."},
+            "parse_markdown": {"type": "boolean", "description": "Whether Inline should parse Markdown. Defaults to true."},
+            "send_mode": {"type": "string", "enum": ["normal", "silent"], "description": "Optional send mode."},
+            "limit": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": _MAX_HISTORY_LIMIT,
+                "description": "Max history messages, default 20, max 100.",
+            },
+            "anchor_id": {"type": "string", "description": "Anchor message ID for get_history pagination."},
+            "state": {"type": "string", "enum": ["start", "stop"], "description": "Typing indicator state."},
+            "kind": {"type": "string", "enum": _PRESENCE_KINDS, "description": "Bot presence kind."},
+            "comment": {"type": "string", "description": "Optional bot presence comment."},
+        },
+        "required": ["action"],
+    },
+}
+
+
+def register(ctx: Any) -> None:
+    ctx.register_tool(
+        name="inline",
+        toolset="inline",
+        schema=INLINE_TOOL_SCHEMA,
+        handler=_handle_inline_tool,
+        check_fn=check_inline_tool_requirements,
+        description="Read and participate in Inline chats, messages, and reply threads.",
+        emoji="I",
+    )
+
+
+def _handle_inline_tool(args: Dict[str, Any], **_: Any) -> str:
+    if not isinstance(args, dict):
+        return tool_error("inline: expected JSON object arguments")
+
+    action = _str(args.get("action"))
+    if action not in _ACTIONS:
+        return tool_error(f"inline: unknown action {action or '(empty)'}", allowed_actions=_ACTIONS)
+
+    try:
+        path, body = _request_for_action(action, args)
+        response = _sidecar_call(path, body)
+        result = _compact_result(action, response.get("result") or {})
+        return tool_result({"success": True, "action": action, "result": result})
+    except InlineToolError as exc:
+        return tool_error(str(exc), action=action, error_kind=exc.error_kind)
+
+
+def _request_for_action(action: str, args: Dict[str, Any]) -> tuple[str, Dict[str, Any]]:
+    if action == "get_chat":
+        return "/chat", {"target": _target(args)}
+
+    if action == "get_messages":
+        ids = _message_ids(args)
+        if not ids:
+            raise InlineToolError("get_messages requires message_ids or message_id", "bad_format")
+        return "/messages", {"target": _target(args), "messageIds": ids}
+
+    if action == "get_history":
+        body = {
+            "target": _target(args),
+            "limit": _limit(args.get("limit")),
+        }
+        anchor_id = _inline_id(args.get("anchor_id"))
+        if anchor_id:
+            body["anchorId"] = anchor_id
+        return "/history", body
+
+    if action == "send_message":
+        text = _required_str(args, "text", max_chars=_MAX_TEXT_CHARS)
+        body = {
+            "target": _target(args),
+            "text": text,
+            "parseMarkdown": _bool(args.get("parse_markdown"), True),
+        }
+        reply_to = _inline_id(args.get("reply_to_msg_id"))
+        if reply_to:
+            body["replyToMsgId"] = reply_to
+        if _str(args.get("send_mode")) == "silent":
+            body["sendMode"] = "silent"
+        return "/send", body
+
+    if action == "edit_message":
+        return "/edit", {
+            "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),
+        }
+
+    if action == "delete_message":
+        return "/delete", {
+            "target": _target(args),
+            "messageId": _required_id(args, "message_id"),
+        }
+
+    if action == "create_thread":
+        parent_chat_id = _inline_id(args.get("parent_chat_id")) or _session_chat_id(prefer_thread=False)
+        if not parent_chat_id:
+            raise InlineToolError("create_thread requires parent_chat_id or current Inline chat context", "bad_format")
+        body = {"parentChatId": parent_chat_id}
+        parent_message_id = _inline_id(args.get("parent_message_id")) or _session_message_id()
+        if parent_message_id:
+            body["parentMessageId"] = parent_message_id
+        for key in ("title", "description", "emoji"):
+            value = _str(args.get(key))
+            if value:
+                body[key] = value
+        return "/create-subthread", body
+
+    if action == "set_typing":
+        return "/typing", {
+            "target": _target(args),
+            "state": _str(args.get("state")) or "start",
+        }
+
+    if action == "set_presence":
+        kind = _str(args.get("kind"))
+        if kind not in _PRESENCE_KINDS:
+            raise InlineToolError(f"set_presence requires kind: {', '.join(_PRESENCE_KINDS)}", "bad_format")
+        body = {"target": _target(args), "kind": kind}
+        comment = _str(args.get("comment"))
+        if comment:
+            body["comment"] = comment
+        return "/presence", body
+
+    raise InlineToolError(f"inline: unimplemented action {action}", "bad_format")
+
+
+def _sidecar_call(path: str, body: Dict[str, Any]) -> Dict[str, Any]:
+    base_url, token = _sidecar_config()
+    request = urllib.request.Request(
+        f"{base_url}{path}",
+        data=json.dumps({k: v for k, v in body.items() if v is not None}).encode("utf-8"),
+        headers={
+            "content-type": "application/json; charset=utf-8",
+            "x-hermes-sidecar-token": token,
+        },
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(request, timeout=15) as response:
+            raw = response.read().decode("utf-8")
+            status = response.status
+    except urllib.error.HTTPError as exc:
+        raw = exc.read().decode("utf-8", errors="replace")
+        status = exc.code
+    except urllib.error.URLError as exc:
+        raise InlineToolError(f"Inline sidecar is not reachable: {exc}", "transient") from exc
+
+    try:
+        data = json.loads(raw or "{}")
+    except json.JSONDecodeError as exc:
+        raise InlineToolError(f"Inline sidecar returned invalid JSON: {exc}", "unknown") from exc
+
+    if status != 200 or not data.get("ok"):
+        error = str(data.get("error") or f"Inline sidecar returned HTTP {status}")
+        error_kind = str(data.get("errorKind") or "unknown")
+        raise InlineToolError(error, error_kind)
+    return data
+
+
+def _sidecar_config() -> tuple[str, str]:
+    token = _str(_sidecar.get("token")) or _str(os.getenv("INLINE_SIDECAR_TOKEN"))
+    if not token:
+        raise InlineToolError("Inline sidecar token is not configured; start the Inline gateway adapter first", "forbidden")
+    bind = _normalize_bind(_sidecar.get("bind") or os.getenv("INLINE_SIDECAR_BIND"))
+    port = _normalize_port(_sidecar.get("port") or os.getenv("INLINE_SIDECAR_PORT"))
+    host = f"[{bind}]" if ":" in bind and not bind.startswith("[") else bind
+    return f"http://{host}:{port}", token
+
+
+def _target(args: Dict[str, Any]) -> Dict[str, str]:
+    chat_id = _inline_id(args.get("chat_id"))
+    user_id = _inline_id(args.get("user_id"))
+    if chat_id and user_id:
+        raise InlineToolError("target cannot include both chat_id and user_id", "bad_format")
+    if chat_id:
+        return {"chatId": chat_id}
+    if user_id:
+        return {"userId": user_id}
+    current = _session_chat_id(prefer_thread=True)
+    if current:
+        return {"chatId": current}
+    raise InlineToolError("target requires chat_id, user_id, or current Inline chat context", "bad_format")
+
+
+def _session_chat_id(*, prefer_thread: bool) -> str:
+    if _session_env("HERMES_SESSION_PLATFORM", "") not in {"", "inline"}:
+        return ""
+    if prefer_thread:
+        thread_id = _inline_id(_session_env("HERMES_SESSION_THREAD_ID", ""))
+        if thread_id:
+            return thread_id
+    return _inline_id(_session_env("HERMES_SESSION_CHAT_ID", ""))
+
+
+def _session_message_id() -> str:
+    if _session_env("HERMES_SESSION_PLATFORM", "") not in {"", "inline"}:
+        return ""
+    return _inline_id(_session_env("HERMES_SESSION_MESSAGE_ID", ""))
+
+
+def _session_env(name: str, default: str = "") -> str:
+    try:
+        from gateway.session_context import get_session_env
+        return str(get_session_env(name, default) or "")
+    except Exception:
+        return str(os.getenv(name, default) or "")
+
+
+def _message_ids(args: Dict[str, Any]) -> list[str]:
+    raw = args.get("message_ids")
+    values: Iterable[Any]
+    if isinstance(raw, list):
+        values = raw
+    elif _str(raw):
+        values = _str(raw).split(",")
+    else:
+        values = []
+    ids = [_inline_id(value) for value in values]
+    single = _inline_id(args.get("message_id"))
+    if single:
+        ids.append(single)
+    return [item for item in ids if item]
+
+
+def _compact_result(action: str, result: Dict[str, Any]) -> Dict[str, Any]:
+    if action == "get_chat":
+        return _compact_chat(result)
+    if action in {"get_messages", "get_history"}:
+        messages = result.get("messages") if isinstance(result, dict) else []
+        if not isinstance(messages, list):
+            messages = []
+        return {
+            "count": len(messages),
+            "messages": [_compact_message(msg) for msg in messages],
+        }
+    if action == "create_thread":
+        return {
+            "chatId": _str(result.get("chatId")),
+            "chat": _compact_chat(result.get("chat") if isinstance(result.get("chat"), dict) else {}),
+        }
+    return result
+
+
+def _compact_chat(chat: Dict[str, Any]) -> Dict[str, Any]:
+    if not isinstance(chat, dict):
+        return {}
+    out: Dict[str, Any] = {}
+    for source, dest in [
+        ("chatId", "chatId"),
+        ("id", "chatId"),
+        ("title", "title"),
+        ("spaceId", "spaceId"),
+        ("parentChatId", "parentChatId"),
+        ("parentMessageId", "parentMessageId"),
+        ("isPublic", "isPublic"),
+        ("untitled", "untitled"),
+        ("number", "number"),
+    ]:
+        if source in chat and chat[source] is not None and dest not in out:
+            out[dest] = chat[source]
+    return out
+
+
+def _compact_message(message: Any) -> Dict[str, Any]:
+    if not isinstance(message, dict):
+        return {"raw": _truncate(str(message), 200)}
+    out: Dict[str, Any] = {}
+    for key in ["id", "chatId", "fromId", "date", "out", "replyToMsgId", "mentioned", "rev"]:
+        if key in message and message[key] is not None:
+            out[key] = message[key]
+    text = message.get("message")
+    if text is None:
+        text = message.get("text")
+    if text is not None:
+        out["text"] = _truncate(str(text), _MAX_RESULT_TEXT_CHARS)
+    for key in ["media", "attachments", "reactions", "replies", "actions"]:
+        if key in message and message[key] is not None:
+            out[key] = _summarize_value(message[key])
+    entity_summary, entity_count = _entity_summary_text(message, str(text or ""))
+    if entity_summary:
+        out["entitySummary"] = entity_summary
+    if entity_count > 0:
+        out["entityCount"] = entity_count
+        if entity_count > _MAX_MESSAGE_ENTITIES:
+            out["entitiesMore"] = entity_count - _MAX_MESSAGE_ENTITIES
+    return out
+
+
+def _message_entities(message: Dict[str, Any]) -> list[Dict[str, Any]]:
+    candidates: list[Any] = [message.get("entities")]
+    raw = message.get("raw")
+    if isinstance(raw, dict):
+        candidates.append(raw.get("entities"))
+    for container in candidates:
+        if isinstance(container, dict):
+            entities = container.get("entities")
+        else:
+            entities = container
+        if isinstance(entities, list):
+            return [entity for entity in entities if isinstance(entity, dict)]
+    return []
+
+
+def _entity_summary_text(message: Dict[str, Any], text: str) -> tuple[str, int]:
+    entities = _message_entities(message)
+    parts: list[str] = []
+    for entity in entities[:_MAX_MESSAGE_ENTITIES]:
+        summary = _format_entity_summary(entity, text)
+        if summary:
+            parts.append(summary)
+    if len(entities) > _MAX_MESSAGE_ENTITIES:
+        parts.append(f"+{len(entities) - _MAX_MESSAGE_ENTITIES} more")
+    return " | ".join(parts), len(entities)
+
+
+def _format_entity_summary(entity: Dict[str, Any], text: str) -> Optional[str]:
+    kind = _entity_kind(entity)
+    label = _entity_slice(text, entity)
+    quoted = f' "{label}"' if label else ""
+
+    if kind == "mention":
+        user_id = _entity_id(_entity_payload(entity, "mention"), "userId")
+        return f"mention{quoted} -> user:{user_id}" if user_id else f"mention{quoted}"
+    if kind == "group_mention":
+        group_id = _entity_id(_entity_payload(entity, "groupMention", "group_mention"), "groupId")
+        return f"group mention{quoted} -> group:{group_id}" if group_id else f"group mention{quoted}"
+    if kind == "text_link":
+        url = _compact_text(_entity_payload(entity, "textUrl", "text_url").get("url"), 240)
+        return f"text link{quoted} -> {url}" if url else f"text link{quoted}"
+    if kind == "thread":
+        chat_id = _entity_id(_entity_payload(entity, "thread"), "chatId")
+        return f"thread link{quoted} -> thread:{chat_id}" if chat_id else f"thread link{quoted}"
+    if kind == "thread_title":
+        payload = _entity_payload(entity, "threadTitle", "thread_title")
+        space_id = _entity_id(payload, "spaceId")
+        title = _compact_text(payload.get("title"), _ENTITY_TEXT_LIMIT)
+        if space_id and title:
+            return f"thread title link{quoted} -> space:{space_id} title:\"{title}\""
+        return f"thread title link{quoted} -> space:{space_id}" if space_id else f"thread title link{quoted}"
+    if kind == "pre":
+        language = _compact_text(_entity_payload(entity, "pre").get("language"), 80)
+        return f"preformatted block{quoted} (language: {language})" if language else f"preformatted block{quoted}"
+    if kind == "username_mention":
+        return f"username mention{quoted}"
+    if kind == "phone_number":
+        return f"phone number{quoted}"
+    if kind == "bot_command":
+        return f"bot command{quoted}"
+    if kind == "unknown" and not label:
+        return None
+    return f"{kind.replace('_', ' ')}{quoted}"
+
+
+def _entity_kind(entity: Dict[str, Any]) -> str:
+    payload = entity.get("entity")
+    oneof = str(payload.get("oneofKind") or "") if isinstance(payload, dict) else ""
+    if oneof == "textUrl":
+        return "text_link"
+    if oneof == "threadTitle":
+        return "thread_title"
+    if oneof == "groupMention":
+        return "group_mention"
+    if oneof:
+        return re.sub(r"[^a-z0-9_]", "_", oneof.strip().lower())
+
+    type_id = _to_int(entity.get("type"))
+    if type_id is not None:
+        return _ENTITY_TYPE_NAMES.get(type_id, "unknown")
+    text = str(entity.get("type") or "").strip().lower()
+    text = re.sub(r"^type_", "", text).replace("-", "_")
+    if text in {"text_url", "texturl"}:
+        return "text_link"
+    if text in {"threadtitle", "thread_title"}:
+        return "thread_title"
+    if text in {"groupmention", "group_mention"}:
+        return "group_mention"
+    return text or "unknown"
+
+
+def _entity_payload(entity: Dict[str, Any], *keys: str) -> Dict[str, Any]:
+    payload = entity.get("entity")
+    if not isinstance(payload, dict):
+        return {}
+    for key in keys:
+        value = payload.get(key)
+        if isinstance(value, dict):
+            return value
+    return {}
+
+
+def _entity_id(payload: Dict[str, Any], key: str) -> Optional[str]:
+    value = payload.get(key)
+    if value is None:
+        return None
+    text = str(value).strip()
+    return text or None
+
+
+def _entity_slice(text: str, entity: Dict[str, Any]) -> str:
+    offset = _to_int(entity.get("offset"))
+    length = _to_int(entity.get("length"))
+    if offset is None or length is None or offset < 0 or length <= 0:
+        return ""
+    return _compact_text(text[offset: offset + length], _ENTITY_TEXT_LIMIT)
+
+
+def _summarize_value(value: Any) -> Any:
+    if value is None or isinstance(value, (bool, int, float)):
+        return value
+    if isinstance(value, str):
+        return _truncate(value, 240)
+    if isinstance(value, list):
+        return [_summarize_value(item) for item in value[:8]]
+    if isinstance(value, dict):
+        out: Dict[str, Any] = {}
+        for key, item in list(value.items())[:12]:
+            if str(key).lower() == "raw":
+                continue
+            out[str(key)] = _summarize_value(item)
+        return out
+    return _truncate(str(value), 240)
+
+
+def _compact_text(value: Any, limit: int) -> str:
+    return _truncate(str(value or "").replace("\n", " ").strip(), limit)
+
+
+def _to_int(value: Any) -> Optional[int]:
+    try:
+        return int(str(value))
+    except (TypeError, ValueError):
+        return None
+
+
+def _required_str(args: Dict[str, Any], key: str, *, max_chars: int) -> str:
+    value = _str(args.get(key))
+    if not value:
+        raise InlineToolError(f"{key} is required", "bad_format")
+    return _truncate(value, max_chars)
+
+
+def _required_id(args: Dict[str, Any], key: str) -> str:
+    value = _inline_id(args.get(key))
+    if not value:
+        raise InlineToolError(f"{key} is required", "bad_format")
+    return value
+
+
+def _inline_id(value: Any) -> str:
+    text = _str(value)
+    if not text:
+        return ""
+    if ":" in text:
+        prefix, rest = text.split(":", 1)
+        if prefix.lower() in {"chat", "thread", "user", "message", "msg"}:
+            text = rest.strip()
+    return text
+
+
+def _limit(value: Any) -> int:
+    try:
+        limit = int(value)
+    except (TypeError, ValueError):
+        return _DEFAULT_HISTORY_LIMIT
+    return min(max(limit, 1), _MAX_HISTORY_LIMIT)
+
+
+def _bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+    text = _str(value).lower()
+    if text in {"1", "true", "yes", "on"}:
+        return True
+    if text in {"0", "false", "no", "off"}:
+        return False
+    return default
+
+
+def _normalize_bind(value: Any) -> str:
+    text = _str(value) or _DEFAULT_SIDECAR_BIND
+    if text == "[::1]":
+        return "::1"
+    if text in {"127.0.0.1", "localhost", "::1"}:
+        return text
+    raise InlineToolError(f"INLINE_SIDECAR_BIND must be loopback, got {text}", "bad_format")
+
+
+def _normalize_port(value: Any) -> int:
+    text = _str(value)
+    if not text:
+        return _DEFAULT_SIDECAR_PORT
+    try:
+        port = int(text)
+    except ValueError as exc:
+        raise InlineToolError("INLINE_SIDECAR_PORT must be an integer from 1 to 65535", "bad_format") from exc
+    if port < 1 or port > 65535:
+        raise InlineToolError("INLINE_SIDECAR_PORT must be an integer from 1 to 65535", "bad_format")
+    return port
+
+
+def _str(value: Any) -> str:
+    if value is None:
+        return ""
+    return str(value).strip()
+
+
+def _truncate(text: str, limit: int) -> str:
+    if limit <= 0 or len(text) <= limit:
+        return text
+    return text[: max(0, limit - 3)] + "..."
+
+
+class InlineToolError(RuntimeError):
+    def __init__(self, message: str, error_kind: str = "unknown"):
+        self.error_kind = error_kind
+        super().__init__(message)