gumloop 0.3.4__tar.gz → 0.4.0__tar.gz

{gumloop-0.3.4 → gumloop-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gumloop
-Version: 0.3.4
+Version: 0.4.0
 Summary: Python client for the Gumloop API
 Project-URL: Homepage, https://github.com/gumloop/gumloop-py
 Project-URL: Bug Tracker, https://github.com/gumloop/gumloop-py/issues

{gumloop-0.3.4 → gumloop-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "gumloop"
-version = "0.3.4"
+version = "0.4.0"
 description = "Python client for the Gumloop API"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -60,6 +60,7 @@ build = [
 testpaths = ["tests"]
 markers = [
     "live: hits the real Gumloop API and upstream providers; opt-in via `-m live`",
+    "implementation: asserts internals or invariants beyond the public contract",
 ]
 
 [tool.ruff]

{gumloop-0.3.4 → gumloop-0.4.0}/src/gumloop/__init__.py

@@ -1,12 +1,12 @@
 from gumloop._client import AsyncGumloop
 from gumloop._client import Gumloop
 from gumloop._client import GumloopClient
+from gumloop._version import __version__
 from gumloop.errors import APIStatusError
 from gumloop.errors import AuthenticationError
 from gumloop.errors import GumloopError
 from gumloop.oauth import OAuth
 
-__version__ = "0.3.3"
 __all__ = [
     "APIStatusError",
     "AsyncGumloop",
@@ -15,4 +15,5 @@ __all__ = [
     "GumloopClient",
     "GumloopError",
     "OAuth",
+    "__version__",
 ]

gumloop-0.4.0/src/gumloop/_auth.py

@@ -0,0 +1,35 @@
+"""Credential resolution shared by the sync and async transports."""
+
+from __future__ import annotations
+
+import os
+
+from gumloop.errors import AuthenticationError
+
+
+class EnvToken(str):
+    """Access token sourced from ``GUMLOOP_ACCESS_TOKEN``.
+
+    Stays live: ``current()`` returns the env var's present value, so
+    platform-rotated tokens (e.g. per-call sandbox credentials) are picked up
+    on every request. Explicit tokens are plain strings and never change.
+    """
+
+    @classmethod
+    def from_env(cls) -> EnvToken | None:
+        token = os.environ.get("GUMLOOP_ACCESS_TOKEN")
+        return cls(token) if token else None
+
+    def current(self) -> str:
+        return os.environ.get("GUMLOOP_ACCESS_TOKEN") or str(self)
+
+
+def auth_headers(access_token: str | None, user_id: str | None) -> dict[str, str]:
+    if isinstance(access_token, EnvToken):
+        access_token = access_token.current()
+    if not access_token:
+        raise AuthenticationError("access_token, api_key, or GUMLOOP_ACCESS_TOKEN is required")
+    headers = {"Authorization": f"Bearer {access_token}"}
+    if user_id:
+        headers["x-auth-key"] = user_id
+    return headers

{gumloop-0.3.4 → gumloop-0.4.0}/src/gumloop/_client.py

@@ -7,6 +7,7 @@ from typing import Any
 
 import httpx
 
+from gumloop._auth import EnvToken
 from gumloop._http import AsyncHttpClient
 from gumloop._http import HttpClient
 from gumloop.oauth import OAuth
@@ -27,6 +28,7 @@ from gumloop.resources import Chat
 from gumloop.resources import Models
 from gumloop.resources import Sessions
 from gumloop.resources import Skills
+from gumloop.resources import Sync
 from gumloop.resources import Teams
 
 DEFAULT_BASE_URL = "https://api.gumloop.com/api/v1"
@@ -59,7 +61,7 @@ class Gumloop:
         stream_timeout: float | None = DEFAULT_STREAM_TIMEOUT,
     ) -> None:
         self.api_key = api_key
-        self.access_token = access_token or api_key or os.environ.get("GUMLOOP_ACCESS_TOKEN")
+        self.access_token = access_token or api_key or EnvToken.from_env()
         # Personal Gumloop API keys are user-scoped; the backend uses the
         # x-auth-key header to look up the owner's stored secret. OAuth
         # callers omit it because the bearer token already identifies them.
@@ -86,6 +88,7 @@ class Gumloop:
         self.mcp = MCP(self._http)
         self.teams = Teams(self._http)
         self.skills = Skills(self._http)
+        self.sync = Sync(self._http)
         self.artifacts = Artifacts(self._http)
         self.brain = Brain(self._http)
         self.oauth = OAuth(base_url=self.base_url, timeout=self.timeout)
@@ -115,7 +118,7 @@ class AsyncGumloop:
         stream_timeout: float | None = DEFAULT_STREAM_TIMEOUT,
     ) -> None:
         self.api_key = api_key
-        self.access_token = access_token or api_key or os.environ.get("GUMLOOP_ACCESS_TOKEN")
+        self.access_token = access_token or api_key or EnvToken.from_env()
         self.user_id = user_id or os.environ.get("GUMLOOP_USER_ID")
         # Defaults to production; GUMLOOP_BASE_URL is an optional override.
         self.base_url = (base_url or os.environ.get("GUMLOOP_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")

{gumloop-0.3.4 → gumloop-0.4.0}/src/gumloop/_http.py

@@ -13,7 +13,7 @@ from httpx_sse import ServerSentEvent
 from pydantic import BaseModel
 from pydantic import ValidationError
 
-from gumloop.errors import AuthenticationError
+from gumloop._auth import auth_headers
 from gumloop.errors import to_api_error
 from gumloop.types import StreamEvent
 
@@ -23,13 +23,8 @@ _DONE_SENTINEL = "[DONE]"
 _T = TypeVar("_T", bound=BaseModel)
 
 
-def _auth_headers(access_token: str | None, user_id: str | None) -> dict[str, str]:
-    if not access_token:
-        raise AuthenticationError("access_token, api_key, or GUMLOOP_ACCESS_TOKEN is required")
-    headers = {"Authorization": f"Bearer {access_token}"}
-    if user_id:
-        headers["x-auth-key"] = user_id
-    return headers
+class ResponseSizeExceededError(Exception):
+    """Raised when a streamed response body exceeds the caller's byte limit."""
 
 
 def _omit_none_params(params: Mapping[str, Any] | None) -> dict[str, Any] | None:
@@ -97,8 +92,16 @@ class HttpClient:
         json: Any = None,
         data: Mapping[str, Any] | None = None,
         files: list[tuple[str, Any]] | None = None,
+        extra_headers: Mapping[str, str] | None = None,
     ) -> Any:
-        return self._request("POST", path, json=json, data=_omit_none_params(data), files=files)
+        return self._request(
+            "POST",
+            path,
+            json=json,
+            data=_omit_none_params(data),
+            files=files,
+            extra_headers=extra_headers,
+        )
 
     def patch(
         self,
@@ -116,11 +119,36 @@ class HttpClient:
     def delete(self, path: str) -> Any:
         return self._request("DELETE", path)
 
+    def post_bytes(
+        self,
+        path: str,
+        *,
+        json: Any = None,
+        extra_headers: Mapping[str, str] | None = None,
+        max_bytes: int,
+    ) -> tuple[bytes, httpx.Headers]:
+        headers = auth_headers(self.access_token, self.user_id)
+        headers["Content-Type"] = "application/json"
+        if extra_headers:
+            headers.update(extra_headers)
+        with self._client.stream("POST", path, headers=headers, json=json) as response:
+            if response.status_code >= 400:
+                response.read()
+                raise to_api_error(response)
+            chunks: list[bytes] = []
+            total = 0
+            for chunk in response.iter_bytes():
+                total += len(chunk)
+                if total > max_bytes:
+                    raise ResponseSizeExceededError(f"response body exceeds {max_bytes} bytes")
+                chunks.append(chunk)
+            return b"".join(chunks), response.headers
+
     def post_to_stream_host(self, path: str, *, json: Any = None) -> Any:
         # Endpoints whose streaming variant lives on the stream host (e.g. chat
         # completions) must accept their unary counterparts at the same host —
         # the api host has no handler for them.
-        headers = _auth_headers(self.access_token, self.user_id)
+        headers = auth_headers(self.access_token, self.user_id)
         headers["Content-Type"] = "application/json"
         response = self._client.post(
             f"{self._stream_base_url}/{path.lstrip('/')}",
@@ -140,7 +168,7 @@ class HttpClient:
         json: Any = None,
         params: Mapping[str, Any] | None = None,
     ) -> Iterator[StreamEvent]:
-        headers = {**_auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
+        headers = {**auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
         with self._client.stream(
             method,
             f"{self._stream_base_url}/{path.lstrip('/')}",
@@ -166,7 +194,7 @@ class HttpClient:
     ) -> Iterator[_T]:
         # Skips the StreamEvent envelope and honors OpenRouter's `data: [DONE]`
         # terminator. Unparseable events (keep-alives, comments) are skipped.
-        headers = {**_auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
+        headers = {**auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
         with self._client.stream(
             method,
             f"{self._stream_base_url}/{path.lstrip('/')}",
@@ -191,12 +219,21 @@ class HttpClient:
                     logger.debug("dropped non-%s SSE: %s", response_model.__name__, event.data)
                     continue
 
-    def _request(self, method: str, path: str, **kwargs: Any) -> Any:
+    def _request(
+        self,
+        method: str,
+        path: str,
+        *,
+        extra_headers: Mapping[str, str] | None = None,
+        **kwargs: Any,
+    ) -> Any:
         # Headers are rebuilt per request so ``access_token`` / ``user_id``
         # can be rotated on a live client without reconstructing it.
-        headers = _auth_headers(self.access_token, self.user_id)
+        headers = auth_headers(self.access_token, self.user_id)
         if not kwargs.get("files"):
             headers["Content-Type"] = "application/json"
+        if extra_headers:
+            headers.update(extra_headers)
         response = self._client.request(method, path, headers=headers, **kwargs)
         if response.status_code >= 400:
             raise to_api_error(response)
@@ -261,7 +298,7 @@ class AsyncHttpClient:
         return await self._request("DELETE", path)
 
     async def post_to_stream_host(self, path: str, *, json: Any = None) -> Any:
-        headers = _auth_headers(self.access_token, self.user_id)
+        headers = auth_headers(self.access_token, self.user_id)
         headers["Content-Type"] = "application/json"
         response = await self._client.post(
             f"{self._stream_base_url}/{path.lstrip('/')}",
@@ -281,7 +318,7 @@ class AsyncHttpClient:
         json: Any = None,
         params: Mapping[str, Any] | None = None,
     ) -> AsyncIterator[StreamEvent]:
-        headers = {**_auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
+        headers = {**auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
         async with self._client.stream(
             method,
             f"{self._stream_base_url}/{path.lstrip('/')}",
@@ -305,7 +342,7 @@ class AsyncHttpClient:
         json: Any = None,
         params: Mapping[str, Any] | None = None,
     ) -> AsyncIterator[_T]:
-        headers = {**_auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
+        headers = {**auth_headers(self.access_token, self.user_id), "Accept": "text/event-stream"}
         async with self._client.stream(
             method,
             f"{self._stream_base_url}/{path.lstrip('/')}",
@@ -331,7 +368,7 @@ class AsyncHttpClient:
                     continue
 
     async def _request(self, method: str, path: str, **kwargs: Any) -> Any:
-        headers = _auth_headers(self.access_token, self.user_id)
+        headers = auth_headers(self.access_token, self.user_id)
         if not kwargs.get("files"):
             headers["Content-Type"] = "application/json"
         response = await self._client.request(method, path, headers=headers, **kwargs)

gumloop-0.4.0/src/gumloop/_version.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+__version__ = "0.4.0"

gumloop-0.4.0/src/gumloop/cli/commands/_sync_output.py

@@ -0,0 +1,328 @@
+from __future__ import annotations
+
+from collections import Counter
+from types import TracebackType
+
+from rich.markup import escape as escape_markup
+from rich.status import Status
+from rich.table import Table
+from rich.text import Text
+
+from gumloop.cli.console import console
+from gumloop.cli.console import error_console
+from gumloop.sync.results import SyncExecution
+from gumloop.sync.results import SyncProgress
+from gumloop.sync.results import TargetOutcome
+from gumloop.sync.targets import PhysicalTarget
+from gumloop.types import CliSyncPlanResponse
+
+_ACTION_LABELS = {
+    "adopted": "adopted",
+    "failed": "failed",
+    "installed": "installed",
+    "overwritten_collision": "replaced",
+    "overwritten_local_edit": "replaced local edit",
+    "removed": "removed",
+    "unchanged": "unchanged",
+    "updated": "updated",
+}
+
+_CRITICAL_ACTIONS = frozenset(
+    {
+        "failed",
+        "overwritten_collision",
+        "overwritten_local_edit",
+        "removed",
+    }
+)
+
+# Human labels match Homecrew/crew adapter names (hyphenated).
+_AGENT_LABELS = {
+    "agent_skills": "agent-skills",
+    "claude_code": "claude-code",
+    "codex": "codex",
+    "cursor": "cursor",
+}
+
+
+class SyncOutput:
+    def __init__(self) -> None:
+        self._status: Status | None = None
+        self._already_current = False
+
+    def __enter__(self) -> SyncOutput:
+        return self
+
+    def __exit__(
+        self,
+        _exc_type: type[BaseException] | None,
+        _exc_value: BaseException | None,
+        _traceback: TracebackType | None,
+    ) -> None:
+        self._stop()
+
+    def __call__(self, progress: SyncProgress) -> None:
+        if progress.stage == "resolving_plan":
+            if progress.attempt == 1:
+                message = "Resolving managed Skills…"
+            else:
+                max_attempts = progress.max_attempts
+                retry_label = (
+                    f"{progress.attempt}/{max_attempts}" if max_attempts is not None else str(progress.attempt)
+                )
+                message = f"Desired state changed; retrying ({retry_label})…"
+            self._start(message)
+            return
+        if progress.stage == "plan_resolved":
+            self._stop()
+            skill_count = progress.skill_count or 0
+            agent_count = progress.agent_count or 0
+            console.print(
+                "[green]✓[/green] "
+                f"Found {skill_count} {self._pluralize('Skill', skill_count)} "
+                f"for {agent_count} {self._pluralize('agent', agent_count)}"
+            )
+            return
+        if progress.stage == "downloading_bundle":
+            self._start("Downloading and verifying Skill bundle…")
+            return
+        if progress.stage == "bundle_verified":
+            self._stop()
+            console.print("[green]✓[/green] Downloaded and verified Skill bundle")
+            return
+        if progress.stage == "reconciling_target" and progress.target is not None:
+            agents = escape_markup(self._format_agents(progress.target))
+            self._start(f"Syncing {agents}…")
+            return
+        if progress.stage == "target_complete" and progress.outcome is not None:
+            self._stop()
+            self._print_target_outcome(progress.outcome)
+            return
+        if progress.stage == "already_current":
+            self._stop()
+            self._already_current = True
+            skill_count = progress.skill_count or 0
+            agent_count = progress.agent_count or 0
+            console.print(
+                "[green]✓[/green] "
+                f"All {skill_count} {self._pluralize('Skill', skill_count)} are already current "
+                f"across {agent_count} {self._pluralize('agent', agent_count)}"
+            )
+
+    def print_enrollment(
+        self,
+        *,
+        plan: CliSyncPlanResponse,
+        targets: tuple[PhysicalTarget, ...],
+    ) -> None:
+        table = Table(show_lines=False)
+        table.add_column("Skills path", style="dim")
+        table.add_column("Coding agents")
+
+        console.print()
+        console.print(
+            f"Enrolled in [cyan]{escape_markup(plan.organization.organization_name)}[/cyan]"
+        )
+        if not targets:
+            table.add_row(
+                Text("—"),
+                Text("No coding agents found"),
+            )
+            console.print(table)
+            return
+
+        for target in targets:
+            table.add_row(
+                Text(str(target.skills_root)),
+                Text(self._format_agents(target)),
+            )
+        console.print(table)
+
+    def print_background_status(self, status: str) -> None:
+        console.print(f"[green]✓[/green] Background sync {status} [dim](every 4 hours)[/dim]")
+
+    def print_result(self, execution: SyncExecution, *, verbose: bool) -> None:
+        if execution.status == "blocked":
+            reason = execution.result.get("blocked_reason") or "unknown"
+            console.print(
+                f"\nSync blocked: {reason}. Installed Skills were preserved.",
+                markup=False,
+                highlight=False,
+            )
+            self._print_changes(execution, verbose=verbose)
+            return
+
+        skill_counts = self._unique_skill_counts(execution)
+        failed_count = self._failed_count_for_summary(execution, skill_counts)
+        action_parts = [
+            label
+            for count, label in (
+                (skill_counts.get("installed", 0), f"{skill_counts.get('installed', 0)} installed"),
+                (skill_counts.get("adopted", 0), f"{skill_counts.get('adopted', 0)} adopted"),
+                (skill_counts.get("overwritten", 0), f"{skill_counts.get('overwritten', 0)} replaced"),
+                (skill_counts.get("updated", 0), f"{skill_counts.get('updated', 0)} updated"),
+                (skill_counts.get("removed", 0), f"{skill_counts.get('removed', 0)} removed"),
+            )
+            if count
+        ]
+        agent_count = self._detected_agent_count(execution)
+        agents = f"{agent_count} {self._pluralize('agent', agent_count)}"
+
+        if not action_parts and failed_count == 0:
+            # Fast-path already printed "already current"; avoid a redundant summary.
+            if not self._already_current:
+                console.print(f"\nSync complete: already up to date across {agents}.")
+        else:
+            status = "complete" if execution.status == "ok" else execution.status
+            parts = [*action_parts, f"{failed_count} failed"]
+            console.print(f"\nSync {status}: {', '.join(parts)} across {agents}.")
+
+        self._print_changes(execution, verbose=verbose)
+
+    def _start(self, message: str) -> None:
+        if self._status is None:
+            self._status = Status(
+                message,
+                console=console,
+                spinner="dots",
+            )
+            self._status.start()
+        else:
+            self._status.update(message)
+
+    def _stop(self) -> None:
+        status = self._status
+        self._status = None
+        if status is None:
+            return
+        try:
+            status.stop()
+        except Exception:
+            pass
+
+    def _unique_skill_counts(self, execution: SyncExecution) -> dict[str, int]:
+        """Count each Skill once, even when the same change is written for multiple agents."""
+        by_skill: dict[str, set[str]] = {}
+        changes = execution.result.get("changes")
+        if isinstance(changes, list):
+            for change in changes:
+                if not isinstance(change, dict):
+                    continue
+                action = change.get("action")
+                if not isinstance(action, str) or action == "unchanged":
+                    continue
+                if action in ("overwritten_collision", "overwritten_local_edit"):
+                    bucket = "overwritten"
+                else:
+                    bucket = action
+                skill_key = change.get("skill_id") or change.get("name")
+                if not isinstance(skill_key, str) or not skill_key:
+                    skill_key = str(change.get("physical_path") or id(change))
+                by_skill.setdefault(skill_key, set()).add(bucket)
+
+        counts = Counter(bucket for actions in by_skill.values() for bucket in actions)
+        return dict(counts)
+
+    def _detected_agent_count(self, execution: SyncExecution) -> int:
+        detected = execution.result.get("detected_targets")
+        if isinstance(detected, list):
+            return len(detected)
+        return 0
+
+    def _failed_count_for_summary(
+        self,
+        execution: SyncExecution,
+        skill_counts: dict[str, int],
+    ) -> int:
+        """Prefer unique Skill failures; raise to target-level when partial under-reports."""
+        change_failed = skill_counts.get("failed", 0)
+        if execution.status != "partial":
+            return change_failed
+        physical_targets = execution.result.get("physical_targets")
+        if not isinstance(physical_targets, list):
+            return change_failed
+        target_failed = sum(
+            1 for target in physical_targets if isinstance(target, dict) and target.get("error") is not None
+        )
+        return max(change_failed, target_failed)
+
+    def _print_target_outcome(self, outcome: TargetOutcome) -> None:
+        agents = self._format_agents(outcome.target)
+        if outcome.error is not None:
+            error_console.print(f"✗ {agents} — {outcome.error}", markup=False, highlight=False)
+            return
+
+        counts = Counter(change.action for change in outcome.changes)
+        replaced = counts["overwritten_collision"] + counts["overwritten_local_edit"]
+        parts = [
+            label
+            for count, label in (
+                (counts["installed"], f"{counts['installed']} installed"),
+                (counts["adopted"], f"{counts['adopted']} adopted"),
+                (replaced, f"{replaced} replaced"),
+                (counts["updated"], f"{counts['updated']} updated"),
+                (counts["removed"], f"{counts['removed']} removed"),
+                (counts["failed"], f"{counts['failed']} failed"),
+            )
+            if count
+        ]
+        detail = ", ".join(parts) if parts else "up to date"
+        # One line per physical write; list every agent that shares that path.
+        console.print(f"[green]✓[/green] {escape_markup(agents)} — {detail}")
+
+    def _print_changes(self, execution: SyncExecution, *, verbose: bool) -> None:
+        changes = execution.result.get("changes")
+        if not isinstance(changes, list):
+            return
+
+        visible = [
+            change
+            for change in changes
+            if isinstance(change, dict)
+            and self._change_is_visible(change, verbose=verbose)
+        ]
+        if not visible:
+            return
+
+        console.print("\nChanges:")
+        for change in visible:
+            action = str(change.get("action", "changed"))
+            label = _ACTION_LABELS.get(action, action.replace("_", " "))
+            agents = self._format_agent_names(change.get("targets"))
+            line = f"  {label}: {change.get('name')}"
+            if agents:
+                line += f" ({agents})"
+            if change.get("backup_path"):
+                line += f" backup: {change['backup_path']}"
+            if change.get("error"):
+                line += f" error: {change['error']}"
+                error_console.print(line, markup=False, highlight=False)
+            else:
+                console.print(line, markup=False, highlight=False)
+
+    def _change_is_visible(self, change: dict[str, object], *, verbose: bool) -> bool:
+        action = change.get("action")
+        if change.get("error"):
+            return True
+        if action == "unchanged":
+            return False
+        if verbose:
+            return True
+        if change.get("backup_path"):
+            return True
+        return action in _CRITICAL_ACTIONS
+
+    def _format_agents(self, target: PhysicalTarget) -> str:
+        return self._format_agent_names(target.logical_targets)
+
+    def _format_agent_names(self, names: object) -> str:
+        if not isinstance(names, (list, tuple)):
+            return ""
+        labels = [self._agent_label(str(name)) for name in names]
+        return ", ".join(labels)
+
+    def _agent_label(self, name: str) -> str:
+        return _AGENT_LABELS.get(name, name.replace("_", "-"))
+
+    def _pluralize(self, word: str, count: int) -> str:
+        return word if count == 1 else f"{word}s"