Merge pull request #6 from ComposioHQ/kj/plugin-upgrade-nudge

feat(hooks): nudge CLI upgrade when a newer stable release is cached

Author: KJ-11

plugins/composio/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "composio",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Your agent decides what to do — Composio handles the rest. Use just-in-time tool calls across 1,000+ apps with managed auth through the hosted app or local CLI.",
   "author": {
     "name": "Composio",

plugins/composio/hooks/session-start.sh

@@ -32,6 +32,20 @@ else
         '"authenticated"[[:space:]]*:[[:space:]]*false|not[[:space:]-]+logged[[:space:]-]+in'; then
     cli_status="The local Composio CLI is available and signed in."
   fi
+
+  # Upgrade nudge from the CLI's local release cache — never the network.
+  # Stable X.Y.Z versions only; anything missing or malformed stays silent.
+  update_cache="${HOME:-}/.composio/update-check.json"
+  if [ -f "$update_cache" ]; then
+    latest="$(sed -n 's/.*"latestVersion"[[:space:]]*:[[:space:]]*"\([0-9]\{1,\}\.[0-9]\{1,\}\.[0-9]\{1,\}\)".*/\1/p' "$update_cache" 2>/dev/null | head -n 1)"
+    installed="$(composio version 2>/dev/null | tail -n 1 | tr -d '[:space:]')"
+    if [ -n "$latest" ] && [ "$installed" != "$latest" ] \
+        && printf '%s' "$installed" | grep -Eq '^[0-9]+\.[0-9]+\.[0-9]+$' \
+        && [ "$(printf '%s\n%s\n' "$installed" "$latest" \
+              | sort -t. -k1,1n -k2,2n -k3,3n | head -n 1)" = "$installed" ]; then
+      cli_status="${cli_status} A newer Composio CLI (${latest}) is available — run \`composio upgrade\`."
+    fi
+  fi
 fi
 
 [ -n "$cache_pid" ] && wait "$cache_pid" 2>/dev/null

tests/test_package.py

@@ -169,7 +169,8 @@ def test_readme_documents_the_combined_local_flow(self):
 
 class HookBehaviorTests(unittest.TestCase):
     def run_hook(self, script, payload, tmpdir, path=None):
-        env = dict(os.environ, TMPDIR=tmpdir)
+        # HOME is pinned so tests never read the real ~/.composio.
+        env = dict(os.environ, TMPDIR=tmpdir, HOME=tmpdir)
         if path is not None:
             env["PATH"] = path
         return subprocess.run(
@@ -182,11 +183,20 @@ def run_hook(self, script, payload, tmpdir, path=None):
             check=False,
         )
 
-    def fake_composio(self, tmpdir, stdout="", exit_code=0, toolkits=None):
+    def fake_composio(self, tmpdir, stdout="", exit_code=0, toolkits=None, version=None):
         bindir = pathlib.Path(tmpdir) / "bin"
         bindir.mkdir(exist_ok=True)
         script = bindir / "composio"
         lines = ["#!/usr/bin/env bash"]
+        if version is not None:
+            lines.extend(
+                [
+                    'if [ "$1" = "version" ]; then',
+                    f"  printf '%s\\n' {shlex.quote(version)}",
+                    "  exit 0",
+                    "fi",
+                ]
+            )
         if toolkits is not None:
             lines.extend(
                 [
@@ -246,6 +256,59 @@ def test_session_start_offers_cli_install_in_terminal_context(self):
             self.assertNotIn("composio execute", context)
             self.assertNotIn("composio search", context)
 
+    NUDGE = "newer Composio CLI"
+
+    def write_update_cache(self, tmpdir, content):
+        cache_dir = pathlib.Path(tmpdir) / ".composio"
+        cache_dir.mkdir(exist_ok=True)
+        (cache_dir / "update-check.json").write_text(content, encoding="utf-8")
+
+    def session_context(self, tmpdir, path):
+        result = self.run_hook(
+            "session-start.sh", {"hook_event_name": "SessionStart"}, tmpdir, path
+        )
+        self.assertEqual(0, result.returncode, result.stderr)
+        return json.loads(result.stdout)["hookSpecificOutput"]["additionalContext"]
+
+    def test_session_start_nudges_upgrade_for_older_stable_cli(self):
+        with tempfile.TemporaryDirectory() as tmpdir:
+            self.write_update_cache(
+                tmpdir,
+                json.dumps(
+                    {"lastChecked": "2026-07-24T00:00:00.000Z", "latestVersion": "0.2.32"}
+                ),
+            )
+            path = self.fake_composio(
+                tmpdir, stdout='{"authenticated": true}', version="0.2.30"
+            )
+            context = self.session_context(tmpdir, path)
+            self.assertIn("local Composio CLI is available and signed in", context)
+            self.assertIn("A newer Composio CLI (0.2.32) is available", context)
+            self.assertIn("composio upgrade", context)
+
+    def test_session_start_upgrade_nudge_degrades_to_silence(self):
+        cache = json.dumps(
+            {"lastChecked": "2026-07-24T00:00:00.000Z", "latestVersion": "0.2.32"}
+        )
+        silent_cases = [
+            ("beta-installed", cache, "0.2.32-beta.289"),
+            ("up-to-date", cache, "0.2.32"),
+            ("installed-newer", cache, "0.3.0"),
+            ("prerelease-latest", cache.replace("0.2.32", "0.3.0-beta.1"), "0.2.31"),
+            ("malformed-cache", "not json at all {{{", "0.2.30"),
+            ("cache-missing", None, "0.2.30"),
+        ]
+        for name, cache_content, installed in silent_cases:
+            with self.subTest(name):
+                with tempfile.TemporaryDirectory() as tmpdir:
+                    if cache_content is not None:
+                        self.write_update_cache(tmpdir, cache_content)
+                    path = self.fake_composio(
+                        tmpdir, stdout='{"authenticated": true}', version=installed
+                    )
+                    context = self.session_context(tmpdir, path)
+                    self.assertNotIn(self.NUDGE, context)
+
     def test_prompt_hook_is_surface_aware_for_cached_toolkits(self):
         with tempfile.TemporaryDirectory() as tmpdir:
             cache = pathlib.Path(tmpdir) / "composio-plugin-toolkits.cache"