fix(onboarding): improve hosted cli trace and prompt guidance (#124)

Co-authored-by: David <david@student-net-nw-0650.intern.ethz.ch>

Author: tzerweck

README.md

@@ -72,7 +72,7 @@ print(agent.get_strategies())
 
 No fine-tuning, no training data, no vector database.
 
-[-> Quick Start Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/quick-start/) | [-> Setup Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/setup/)
+[-> Quick Start Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/quick-start/) | [-> Setup Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/setup/) | [-> Hosted API: Where Do Traces Come From?](https://kayba-ai.github.io/agentic-context-engine/latest/integrations/hosted-api/#where-do-traces-come-from)
 
 ---
 
@@ -117,11 +117,11 @@ All roles are backed by [PydanticAI](https://ai.pydantic.dev/) agents with struc
 | **Claude Code** | `ClaudeCode` | Claude Code CLI tasks with learning |
 
 ```bash
-uv add ace-framework[browser-use]    # Browser automation
-uv add ace-framework[langchain]      # LangChain
-uv add ace-framework[logfire]        # Observability (auto-instruments PydanticAI)
-uv add ace-framework[mcp]            # MCP server for IDE integration
-uv add ace-framework[deduplication]  # Embedding-based skill deduplication
+uv add 'ace-framework[browser-use]'    # Browser automation
+uv add 'ace-framework[langchain]'      # LangChain
+uv add 'ace-framework[logfire]'        # Observability (auto-instruments PydanticAI)
+uv add 'ace-framework[mcp]'            # MCP server for IDE integration
+uv add 'ace-framework[deduplication]'  # Embedding-based skill deduplication
 ```
 
 Have existing agent logs? Extract strategies from them directly:
@@ -202,6 +202,7 @@ The pipeline engine ([`pipeline/`](pipeline/)) is framework-agnostic with `requi
 - [Full Documentation](https://kayba-ai.github.io/agentic-context-engine/latest/) — Guides, API reference, examples
 - [Quick Start](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/quick-start/) — 5-minute setup
 - [Setup Guide](https://kayba-ai.github.io/agentic-context-engine/latest/getting-started/setup/) — Configuration and providers
+- [Hosted API Guide](https://kayba-ai.github.io/agentic-context-engine/latest/integrations/hosted-api/) — Hosted CLI, trace upload, prompt install
 - [Architecture](docs/design/ACE_ARCHITECTURE.md) — Core concepts and system design
 - [Code Reference](docs/design/ACE_REFERENCE.md) — Implementations, API, usage examples
 - [Design Decisions](docs/design/ACE_DECISIONS.md) — Rejected alternatives and rationale

ace/cli/client.py

@@ -2,11 +2,11 @@
 
 from __future__ import annotations
 
+import json
 import os
+import re
 from typing import Any, Dict, List, Optional
 
-import requests
-
 
 class KaybaAPIError(Exception):
     """Structured error from the Kayba API."""
@@ -19,6 +19,39 @@ def __init__(self, code: str, message: str, status_code: int = 0):
 
 
 DEFAULT_BASE_URL = "https://use.kayba.ai/api"
+MAX_TRACE_UPLOAD_BODY_BYTES = 900_000
+
+
+def _chunk_trace_uploads(
+    traces: List[Dict[str, Any]],
+) -> List[List[Dict[str, Any]]]:
+    """Split uploads into request-sized batches under the body size cap."""
+    batches: List[List[Dict[str, Any]]] = []
+    current: List[Dict[str, Any]] = []
+    current_size = len('{"traces":[]}')
+
+    for trace in traces:
+        trace_size = len(
+            json.dumps(trace, ensure_ascii=False, separators=(",", ":")).encode(
+                "utf-8"
+            )
+        )
+        separator_size = 1 if current else 0
+        candidate_size = current_size + separator_size + trace_size
+
+        if current and candidate_size > MAX_TRACE_UPLOAD_BODY_BYTES:
+            batches.append(current)
+            current = [trace]
+            current_size = len('{"traces":[]}') + trace_size
+            continue
+
+        current.append(trace)
+        current_size = candidate_size
+
+    if current:
+        batches.append(current)
+
+    return batches
 
 
 class KaybaClient:
@@ -35,6 +68,16 @@ def __init__(
         api_key: Optional[str] = None,
         base_url: Optional[str] = None,
     ):
+        try:
+            import requests
+        except ImportError as exc:
+            raise KaybaAPIError(
+                "DEPENDENCY_MISSING",
+                "The hosted Kayba CLI requires the cloud extra. Install with "
+                "`uv add \"ace-framework[cloud]\"` or "
+                "`pip install 'ace-framework[cloud]'`.",
+            ) from exc
+
         self.api_key = api_key or os.environ.get("KAYBA_API_KEY", "")
         if not self.api_key:
             raise KaybaAPIError(
@@ -44,9 +87,19 @@ def __init__(
         self.base_url = (
             base_url or os.environ.get("KAYBA_API_URL") or DEFAULT_BASE_URL
         ).rstrip("/")
-        self.session = requests.Session()
+        self.session: Any = requests.Session()
         self.session.headers["Authorization"] = f"Bearer {self.api_key}"
 
+    @staticmethod
+    def _summarize_http_body(body: str, limit: int = 240) -> str:
+        """Collapse whitespace so raw HTML and proxy errors stay readable."""
+        snippet = re.sub(r"\s+", " ", body or "").strip()
+        if not snippet:
+            return "Unexpected non-JSON error from the Kayba API."
+        if len(snippet) <= limit:
+            return snippet
+        return snippet[: limit - 3] + "..."
+
     def _request(
         self,
         method: str,
@@ -69,15 +122,36 @@ def _request(
                         message=err,
                         status_code=resp.status_code,
                     )
+                message = err.get("message", resp.text)
+                if (
+                    resp.status_code == 413
+                    or "maximum content size" in message.lower()
+                    or "too large" in message.lower()
+                ):
+                    raise KaybaAPIError(
+                        code="PAYLOAD_TOO_LARGE",
+                        message=message,
+                        status_code=resp.status_code,
+                    )
                 raise KaybaAPIError(
                     code=err.get("code", "UNKNOWN"),
-                    message=err.get("message", resp.text),
+                    message=message,
                     status_code=resp.status_code,
                 )
             except (ValueError, KeyError, AttributeError):
+                message = self._summarize_http_body(resp.text)
+                if resp.status_code == 413:
+                    message = (
+                        "Upload rejected because the request body is too large. "
+                        "Try smaller traces or upload fewer files at once."
+                    )
+                elif resp.status_code in (401, 403):
+                    message = "Authentication failed; check KAYBA_API_KEY"
+                else:
+                    message = f"HTTP {resp.status_code} from Kayba API: {message}"
                 raise KaybaAPIError(
                     code="HTTP_ERROR",
-                    message=resp.text,
+                    message=message,
                     status_code=resp.status_code,
                 )
 
@@ -93,7 +167,20 @@ def upload_traces(self, traces: List[Dict[str, Any]]) -> Dict[str, Any]:
         Args:
             traces: List of dicts with keys: filename, content, fileType.
         """
-        return self._request("POST", "/traces", json={"traces": traces})
+        batches = _chunk_trace_uploads(traces)
+        if len(batches) == 1:
+            return self._request("POST", "/traces", json={"traces": traces})
+
+        combined: Dict[str, Any] = {"count": 0, "traces": []}
+        for batch in batches:
+            result = self._request("POST", "/traces", json={"traces": batch})
+            uploaded = result.get("traces", [])
+            combined["count"] += result.get("count", len(uploaded) or len(batch))
+            combined["traces"].extend(uploaded)
+            for key, value in result.items():
+                if key not in {"count", "traces"} and key not in combined:
+                    combined[key] = value
+        return combined
 
     def list_traces(self) -> Dict[str, Any]:
         """List all traces (metadata only, no content)."""