guzli-cli 0.2.0__py3-none-any.whl

guzli/mcp/server.py

@@ -0,0 +1,320 @@
+"""Curated MCP tools over the same Guzli services used by the CLI."""
+
+from __future__ import annotations
+
+import json
+import os
+from functools import lru_cache
+from typing import Annotated, Any, Literal
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import ToolAnnotations
+from pydantic import Field
+
+from guzli.errors import ConfigError
+from guzli.runtime import RuntimeContext, build_context_for_profile
+from guzli.workflows import CampaignLaunchError, CampaignLaunchInputs, CampaignLaunchWorkflow
+
+mcp = FastMCP(
+    "Guzli",
+    instructions=(
+        "Operate Guzli conversations and outbound calls. launch_calls can place real, "
+        "billable external calls; inspect number pools and voices before launching when needed."
+    ),
+)
+
+
+@lru_cache(maxsize=1)
+def _context() -> RuntimeContext:
+    return build_context_for_profile(os.getenv("GUZLI_PROFILE"))
+
+
+def _mapping(payload: Any) -> dict[str, Any]:
+    if isinstance(payload, dict):
+        return payload
+    if isinstance(payload, list):
+        return {"items": payload}
+    return {"value": payload}
+
+
+def _scope(context: RuntimeContext) -> tuple[str, str]:
+    if not context.agent_id:
+        raise ConfigError("GUZLI_AGENT_ID or a profile agent_id is required")
+    if not context.organization_id:
+        raise ConfigError("GUZLI_ORGANIZATION_ID or a profile organization_id is required")
+    return context.agent_id, context.organization_id
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Launch outbound calls",
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+    structured_output=True,
+)
+def launch_calls(
+    recipients: Annotated[
+        list[str],
+        Field(
+            min_length=1,
+            max_length=1000,
+            description="One or more recipient phone numbers in E.164 format.",
+        ),
+    ],
+    instructions: Annotated[
+        str | None,
+        Field(description="How the voice agent should conduct the call."),
+    ] = None,
+    message: Annotated[
+        str | None,
+        Field(description="Literal opening message spoken when the call connects."),
+    ] = None,
+    objective: Annotated[
+        str | None,
+        Field(description="Short runtime objective for the call."),
+    ] = None,
+    name: Annotated[
+        str | None,
+        Field(description="Campaign launch name; generated when omitted."),
+    ] = None,
+    number_pool_id: Annotated[
+        str | None,
+        Field(description="Existing active number pool ID; profile/default resolution if omitted."),
+    ] = None,
+    caller_phone: Annotated[
+        str | None,
+        Field(description="Find an existing pool containing this caller E.164 number."),
+    ] = None,
+    voice_profile_id: Annotated[
+        str | None,
+        Field(description="Existing voice profile ID; agent default if omitted."),
+    ] = None,
+    voice_id: Annotated[
+        str | None,
+        Field(description="Provider voice ID used to create a profile when explicitly supplied."),
+    ] = None,
+    post_call_extraction: Annotated[
+        dict[str, Any] | None,
+        Field(description="Optional CampaignPostCallExtractionSettings object."),
+    ] = None,
+    background_ambience: Annotated[
+        Literal["none", "people_in_lounge", "food_court", "restaurant", "crowd_talking"],
+        Field(description="Ambient soundbed; defaults to people_in_lounge."),
+    ] = "people_in_lounge",
+    ambience_volume: Annotated[
+        float,
+        Field(ge=0.0, le=1.0, description="Ambient soundbed volume."),
+    ] = 0.10,
+    activate: Annotated[
+        bool,
+        Field(description="Activate after creation. Defaults to true."),
+    ] = True,
+    run: Annotated[
+        bool,
+        Field(description="Queue calls immediately after activation. Defaults to true."),
+    ] = True,
+    dry_run: Annotated[
+        bool,
+        Field(description="Resolve and describe the launch without mutations."),
+    ] = False,
+) -> dict[str, Any]:
+    """Launch one or many real outbound calls using existing Guzli engine endpoints.
+
+    By default this creates a campaign, auto-configures/approves the intentional
+    advisory launch compliance profile, activates it, and queues billable external
+    calls. It never creates a number pool implicitly and is not atomically idempotent.
+    """
+    context = _context()
+    agent_id, organization_id = _scope(context)
+    workflow = CampaignLaunchWorkflow(
+        telephony=context.telephony,
+        voice_profiles=context.voice_profiles,
+        campaigns=context.campaigns,
+    )
+    try:
+        result = workflow.run(
+            CampaignLaunchInputs(
+                name=name or "",
+                agent_id=agent_id,
+                organization_id=organization_id,
+                targets=recipients,
+                number_pool_id=number_pool_id,
+                default_number_pool_id=context.default_number_pool_id,
+                caller_phone_e164=caller_phone,
+                voice_profile_id=voice_profile_id,
+                voice_id=voice_id,
+                call_instructions=instructions,
+                initial_message=message,
+                runtime_objective=objective,
+                post_call_extraction=post_call_extraction,
+                background_ambience=(
+                    None
+                    if background_ambience == "none"
+                    else {"mode": background_ambience, "volume": ambience_volume}
+                ),
+                activate=activate,
+                run=run,
+                dry_run=dry_run,
+            )
+        )
+    except CampaignLaunchError as exc:
+        failure = exc.result.to_summary()
+        failure["error"] = {
+            "code": "campaign_launch_failed",
+            "message": str(exc),
+            "retryable": False,
+        }
+        return failure
+    return result.to_summary()
+
+
+_READ_ONLY = ToolAnnotations(
+    readOnlyHint=True,
+    destructiveHint=False,
+    idempotentHint=True,
+    openWorldHint=True,
+)
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def list_number_pools(active_only: bool = True, limit: int = 50) -> dict[str, Any]:
+    """List number pools so an agent can choose a caller pool before launch."""
+    return _mapping(
+        _context().telephony.list_pools(
+            {
+                "is_active": "true" if active_only else None,
+                "limit": max(1, min(limit, 200)),
+            }
+        )
+    )
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def get_number_pool(number_pool_id: str) -> dict[str, Any]:
+    """Get a number pool, including strategy and active members."""
+    return _mapping(_context().telephony.get_pool(number_pool_id))
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def list_phone_numbers(
+    telephony_account_id: str | None = None,
+    limit: int = 50,
+) -> dict[str, Any]:
+    """List provisioned caller numbers that can be added to number pools."""
+    params: dict[str, object] = {"limit": max(1, min(limit, 200))}
+    if telephony_account_id:
+        params["telephony_account_id"] = telephony_account_id
+    return _mapping(_context().telephony.list_phone_numbers(params))
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def list_voice_profiles(limit: int = 50) -> dict[str, Any]:
+    """List available voice profiles and discover the agent default."""
+    context = _context()
+    params: dict[str, object] = {"limit": max(1, min(limit, 200))}
+    if context.agent_id:
+        params["agent_id"] = context.agent_id
+    return _mapping(context.voice_profiles.list_profiles(params))
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def get_campaign(campaign_id: str) -> dict[str, Any]:
+    """Get the backing campaign created by Campaign Launch."""
+    return _mapping(_context().campaigns.get_campaign(campaign_id))
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def list_campaign_runs(campaign_id: str, limit: int = 50) -> dict[str, Any]:
+    """List execution runs for a campaign."""
+    return _mapping(_context().campaigns.list_runs(campaign_id, {"limit": limit}))
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def list_calls(
+    campaign_id: str,
+    campaign_run_id: str | None = None,
+    limit: int = 50,
+) -> dict[str, Any]:
+    """List call attempts for a campaign, optionally restricted to a run."""
+    params: dict[str, object] = {"limit": max(1, min(limit, 200))}
+    if campaign_run_id:
+        params["campaign_run_id"] = campaign_run_id
+    return _mapping(_context().calls.list_attempts(campaign_id, params))
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def get_call(campaign_id: str, attempt_id: str) -> dict[str, Any]:
+    """Get one call attempt and its current outcome."""
+    return _mapping(_context().calls.get_attempt(campaign_id, attempt_id))
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def get_call_result(campaign_id: str, result_id: str) -> dict[str, Any]:
+    """Get one structured post-call extraction result."""
+    return _mapping(_context().campaigns.get_result(campaign_id, result_id))
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def list_conversations(status: str | None = None, limit: int = 20) -> dict[str, Any]:
+    """List inbox conversations for the configured agent."""
+    params: dict[str, object] = {"limit": max(1, min(limit, 200))}
+    if status:
+        params["status"] = [status]
+    return _mapping(_context().conversations.list_conversations(params))
+
+
+@mcp.tool(annotations=_READ_ONLY, structured_output=True)
+def get_conversation(conversation_id: str, include_transcript: bool = True) -> dict[str, Any]:
+    """Get one inbox conversation and optionally its transcript."""
+    return _mapping(_context().conversations.get_conversation(conversation_id, include_transcript))
+
+
+@mcp.tool(
+    annotations=ToolAnnotations(
+        title="Send agent reply",
+        readOnlyHint=False,
+        destructiveHint=True,
+        idempotentHint=False,
+        openWorldHint=True,
+    ),
+    structured_output=True,
+)
+def send_agent_reply(
+    conversation_id: str,
+    message: Annotated[str, Field(min_length=1, max_length=4000)],
+) -> dict[str, Any]:
+    """Send a real external reply in an inbox conversation."""
+    return _mapping(
+        _context().replies.send_agent_reply(
+            conversation_id,
+            {"message": message, "metadata": {"source": "guzli_mcp"}},
+        )
+    )
+
+
+@mcp.resource("guzli://capabilities")
+def capabilities() -> str:
+    """Return non-secret local configuration capabilities for diagnostics."""
+    context = _context()
+    client = context.campaigns.client
+    auth = client.auth_selector
+    payload = {
+        "base_url": client.base_url,
+        "has_api_key": auth.api_key_auth is not None,
+        "has_bearer": auth.bearer_auth is not None,
+        "has_agent_id": bool(context.agent_id),
+        "has_organization_id": bool(context.organization_id),
+        "default_number_pool_id": context.default_number_pool_id,
+    }
+    return json.dumps(payload, sort_keys=True)
+
+
+def main() -> None:
+    mcp.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

guzli/models.py

@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import List, Mapping, Sequence
+
+from guzli.types import JsonDict, JsonValue
+
+
+@dataclass(frozen=True)
+class ConversationAssignmentView:
+    assignment_type: str
+    assigned_to_id: str | None
+    queue_label: str | None
+
+    @staticmethod
+    def from_json(payload: Mapping[str, JsonValue] | None) -> "ConversationAssignmentView":
+        if not isinstance(payload, Mapping):
+            return ConversationAssignmentView("unknown", None, None)
+        assignment_type = _get_str(payload.get("type")) or "unknown"
+        assigned_to_id = _get_str(payload.get("assigned_to_id"))
+        queue_label = _get_str(payload.get("queue_label"))
+        return ConversationAssignmentView(assignment_type, assigned_to_id, queue_label)
+
+
+@dataclass(frozen=True)
+class ConversationPreviewView:
+    role: str
+    content: str | None
+    timestamp: str | None
+
+    @staticmethod
+    def from_json(payload: Mapping[str, JsonValue] | None) -> "ConversationPreviewView | None":
+        if not isinstance(payload, Mapping):
+            return None
+        role = _get_str(payload.get("role")) or "user"
+        content = _get_str(payload.get("content"))
+        timestamp = _get_str(payload.get("timestamp"))
+        return ConversationPreviewView(role=role, content=content, timestamp=timestamp)
+
+
+@dataclass(frozen=True)
+class TranscriptMessage:
+    role: str
+    content: str | None
+    timestamp: str | None
+
+    @staticmethod
+    def from_json(payload: Mapping[str, JsonValue]) -> "TranscriptMessage":
+        role = _get_str(payload.get("role")) or "user"
+        content = _get_str(payload.get("content"))
+        timestamp = _get_str(payload.get("timestamp"))
+        return TranscriptMessage(role=role, content=content, timestamp=timestamp)
+
+
+@dataclass(frozen=True)
+class ConversationSummaryView:
+    conversation_id: str
+    status: str | None
+    priority: str | None
+    channel: str | None
+    last_message_at: str | None
+    message_count: int
+    assignment: ConversationAssignmentView
+    preview: ConversationPreviewView | None
+    is_marked: bool
+    is_muted: bool
+    unread_count: int
+
+    @staticmethod
+    def from_json(payload: Mapping[str, JsonValue]) -> "ConversationSummaryView":
+        conversation_id = _get_str(payload.get("id")) or "unknown"
+        status = _get_str(payload.get("status"))
+        priority = _get_str(payload.get("priority"))
+        channel = _get_str(payload.get("channel"))
+        last_message_at = _get_str(payload.get("last_message_at"))
+        message_count = _get_int(payload.get("message_count"))
+        assignment = ConversationAssignmentView.from_json(_get_dict(payload.get("assignment")))
+        preview = ConversationPreviewView.from_json(_get_dict(payload.get("last_message_preview")))
+        is_marked = _get_bool(payload.get("is_marked"))
+        is_muted = _get_bool(payload.get("is_muted"))
+        unread_count = _extract_unread_count(payload.get("read_state"))
+        return ConversationSummaryView(
+            conversation_id=conversation_id,
+            status=status,
+            priority=priority,
+            channel=channel,
+            last_message_at=last_message_at,
+            message_count=message_count,
+            assignment=assignment,
+            preview=preview,
+            is_marked=is_marked,
+            is_muted=is_muted,
+            unread_count=unread_count,
+        )
+
+
+@dataclass(frozen=True)
+class ConversationDetailView:
+    summary: ConversationSummaryView
+    transcript: List[TranscriptMessage]
+
+    @staticmethod
+    def from_json(payload: Mapping[str, JsonValue]) -> "ConversationDetailView":
+        summary = ConversationSummaryView.from_json(payload)
+        transcript_items = _get_list(payload.get("transcript"))
+        transcript: List[TranscriptMessage] = []
+        for item in transcript_items:
+            if isinstance(item, Mapping):
+                transcript.append(TranscriptMessage.from_json(item))
+        return ConversationDetailView(summary=summary, transcript=transcript)
+
+
+@dataclass(frozen=True)
+class AgentReplyResult:
+    conversation_id: str
+    message_id: str
+    assignment_updated: bool
+
+    @staticmethod
+    def from_json(payload: Mapping[str, JsonValue]) -> "AgentReplyResult":
+        conversation_id = _get_str(payload.get("conversation_id")) or "unknown"
+        message_id = _get_str(payload.get("message_id")) or "unknown"
+        assignment_updated = _get_bool(payload.get("assignment_updated"))
+        return AgentReplyResult(
+            conversation_id=conversation_id,
+            message_id=message_id,
+            assignment_updated=assignment_updated,
+        )
+
+
+def _get_str(value: JsonValue) -> str | None:
+    if isinstance(value, str):
+        return value
+    return None
+
+
+def _get_int(value: JsonValue) -> int:
+    if isinstance(value, int):
+        return value
+    if isinstance(value, str) and value.isdigit():
+        return int(value)
+    return 0
+
+
+def _get_bool(value: JsonValue) -> bool:
+    if isinstance(value, bool):
+        return value
+    return False
+
+
+def _get_dict(value: JsonValue) -> JsonDict | None:
+    if isinstance(value, Mapping):
+        return dict(value)
+    return None
+
+
+def _get_list(value: JsonValue) -> Sequence[JsonValue]:
+    if isinstance(value, list):
+        return value
+    return []
+
+
+def _extract_unread_count(value: JsonValue) -> int:
+    if not isinstance(value, list):
+        return 0
+    max_unread = 0
+    for item in value:
+        if not isinstance(item, Mapping):
+            continue
+        unread = _get_int(item.get("unread_count"))
+        if unread > max_unread:
+            max_unread = unread
+    return max_unread

guzli/oauth_callback.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+
+import http.server
+import os
+import threading
+import time
+from dataclasses import dataclass, field
+from typing import Type
+from urllib.parse import parse_qs, urlparse
+
+from guzli.errors import ConfigError
+
+DEFAULT_OAUTH_CALLBACK_HOST = "127.0.0.1"
+DEFAULT_OAUTH_CALLBACK_PATH = "/oauth/callback"
+DEFAULT_OAUTH_CALLBACK_PORT = 8765
+DEFAULT_OAUTH_CALLBACK_TIMEOUT_SECONDS = 300
+
+
+@dataclass(frozen=True)
+class OAuthCallbackConfig:
+    host: str = DEFAULT_OAUTH_CALLBACK_HOST
+    port: int = DEFAULT_OAUTH_CALLBACK_PORT
+    path: str = DEFAULT_OAUTH_CALLBACK_PATH
+    timeout_seconds: int = DEFAULT_OAUTH_CALLBACK_TIMEOUT_SECONDS
+
+    @classmethod
+    def from_inputs(cls, port: int | None = None) -> "OAuthCallbackConfig":
+        return cls(port=port if port is not None else _callback_port_from_env())
+
+    @property
+    def redirect_uri(self) -> str:
+        return f"http://{self.host}:{self.port}{self.path}"
+
+
+@dataclass
+class OAuthCallbackResult:
+    state: str | None = None
+    code: str | None = None
+    error: str | None = None
+    error_description: str | None = None
+
+
+@dataclass
+class OAuthLoopbackCallbackServer:
+    config: OAuthCallbackConfig
+    success_html: str
+    _result: OAuthCallbackResult = field(default_factory=OAuthCallbackResult)
+    _done_event: threading.Event = field(default_factory=threading.Event)
+    _httpd: http.server.HTTPServer | None = None
+
+    @property
+    def redirect_uri(self) -> str:
+        return self.config.redirect_uri
+
+    def start(self) -> None:
+        handler = self._handler_class()
+        try:
+            self._httpd = http.server.HTTPServer((self.config.host, self.config.port), handler)
+        except OSError as exc:
+            raise ConfigError(
+                f"OAuth callback port {self.config.port} is unavailable. "
+                "Set GUZLI_OAUTH_CALLBACK_PORT to a registered callback port or free this port."
+            ) from exc
+        thread = threading.Thread(target=self._httpd.serve_forever, daemon=True)
+        thread.start()
+
+    def wait_for_result(self) -> OAuthCallbackResult:
+        deadline = time.monotonic() + self.config.timeout_seconds
+        while not self._done_event.is_set():
+            remaining = deadline - time.monotonic()
+            if remaining <= 0:
+                raise ConfigError(
+                    "OAuth callback timed out. Re-run `guzli auth login --mode oauth`."
+                )
+            self._done_event.wait(timeout=min(remaining, 1.0))
+        return self._result
+
+    def close(self) -> None:
+        if self._httpd is None:
+            return
+        self._httpd.shutdown()
+        self._httpd.server_close()
+        self._httpd = None
+
+    def _handler_class(self) -> Type[http.server.BaseHTTPRequestHandler]:
+        owner = self
+
+        class CallbackHandler(http.server.BaseHTTPRequestHandler):
+            def do_GET(self) -> None:
+                parsed = urlparse(self.path)
+                if parsed.path != owner.config.path:
+                    self.send_response(404)
+                    self.end_headers()
+                    return
+                qs = parse_qs(parsed.query)
+                if "error" in qs:
+                    owner._result.error = qs.get("error", ["unknown"])[0]
+                    owner._result.error_description = qs.get("error_description", [""])[0]
+                else:
+                    owner._result.state = qs.get("state", [""])[0]
+                    owner._result.code = qs.get("code", [""])[0]
+                owner._done_event.set()
+                self.send_response(200)
+                self.send_header("Content-Type", "text/html; charset=utf-8")
+                self.send_header("Cache-Control", "no-store, max-age=0")
+                self.send_header("Pragma", "no-cache")
+                self.end_headers()
+                self.wfile.write(owner.success_html.encode("utf-8"))
+
+            def log_message(self, format: str, *_args) -> None:
+                return
+
+        return CallbackHandler
+
+
+def _callback_port_from_env() -> int:
+    raw_port = os.getenv("GUZLI_OAUTH_CALLBACK_PORT")
+    if raw_port is None or not raw_port.strip():
+        return DEFAULT_OAUTH_CALLBACK_PORT
+    try:
+        port = int(raw_port)
+    except ValueError as exc:
+        raise ConfigError("GUZLI_OAUTH_CALLBACK_PORT must be an integer") from exc
+    if port < 1024 or port > 65535:
+        raise ConfigError("GUZLI_OAUTH_CALLBACK_PORT must be between 1024 and 65535")
+    return port

guzli/output.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Iterable, Mapping
+
+from guzli.models import AgentReplyResult, ConversationDetailView, ConversationSummaryView
+from guzli.types import JsonValue
+
+
+@dataclass(frozen=True)
+class ConsoleRenderer:
+    def print_conversation_list(self, items: Iterable[ConversationSummaryView]) -> None:
+        for item in items:
+            preview = item.preview.content if item.preview and item.preview.content else ""
+            preview_short = _shorten(preview, 80)
+            flags = []
+            if item.is_marked:
+                flags.append("marked")
+            if item.is_muted:
+                flags.append("muted")
+            if item.unread_count:
+                flags.append(f"unread:{item.unread_count}")
+            flag_text = f" [{', '.join(flags)}]" if flags else ""
+            assignment = item.assignment.assignment_type
+            if item.assignment.assigned_to_id:
+                assignment = f"{assignment}:{item.assignment.assigned_to_id}"
+            if item.assignment.queue_label:
+                assignment = f"{assignment}@{item.assignment.queue_label}"
+            print(
+                f"{item.conversation_id} | {item.status or 'unknown'} | {assignment} | {preview_short}{flag_text}"
+            )
+
+    def print_conversation_detail(
+        self, detail: ConversationDetailView, include_transcript: bool
+    ) -> None:
+        summary = detail.summary
+        print(f"Conversation: {summary.conversation_id}")
+        print(f"Status: {summary.status or 'unknown'}")
+        print(f"Priority: {summary.priority or 'normal'}")
+        if summary.channel:
+            print(f"Channel: {summary.channel}")
+        print(f"Messages: {summary.message_count}")
+        if summary.last_message_at:
+            print(f"Last message at: {summary.last_message_at}")
+        print(f"Assignment: {summary.assignment.assignment_type}")
+        if summary.assignment.assigned_to_id:
+            print(f"Assigned to: {summary.assignment.assigned_to_id}")
+        if summary.assignment.queue_label:
+            print(f"Queue: {summary.assignment.queue_label}")
+        if summary.preview and summary.preview.content:
+            print(f"Last preview: {_shorten(summary.preview.content, 200)}")
+        if not include_transcript:
+            return
+        if not detail.transcript:
+            print("Transcript: (empty)")
+            return
+        print("Transcript:")
+        for msg in detail.transcript:
+            timestamp = msg.timestamp or "unknown-time"
+            content = msg.content or ""
+            print(f"- [{timestamp}] {msg.role}: {_shorten(content, 500)}")
+
+    def print_reply_result(self, result: AgentReplyResult) -> None:
+        status = "assignment updated" if result.assignment_updated else "assignment unchanged"
+        print(f"Reply sent to {result.conversation_id} (message {result.message_id}, {status})")
+
+    def print_json(self, payload: JsonValue) -> None:
+        print(json.dumps(payload, indent=2, sort_keys=True))
+
+    def print_key_value(self, payload: Mapping[str, JsonValue]) -> None:
+        for key, value in payload.items():
+            print(f"{key}: {value}")
+
+
+def _shorten(value: str, limit: int) -> str:
+    if len(value) <= limit:
+        return value
+    return f"{value[: limit - 1]}…"