Fix linux crash issue

.github/workflows/publish-packages.yml

@@ -154,6 +154,40 @@ jobs:
           echo "=== Package contents for ${{ matrix.platform }} ==="
           ls -la "$PKG_DIR/"
 
+      - name: Verify Linux native dependencies
+        if: matrix.platform == 'linux-x64'
+        run: |
+          set -euo pipefail
+
+          PKG_DIR="packages/${{ matrix.platform }}/${{ matrix.pkg_name }}/lib"
+          echo "=== Verifying Linux native dependencies in $PKG_DIR ==="
+
+          found=0
+          for sofile in "$PKG_DIR"/*.so "$PKG_DIR"/*.so.*; do
+            [ -L "$sofile" ] && continue
+            [ -f "$sofile" ] || continue
+            found=1
+            echo "--- $sofile"
+            readelf -d "$sofile" | grep -E 'RUNPATH|RPATH' | grep -F '$ORIGIN'
+            LD_LIBRARY_PATH="$PKG_DIR:${LD_LIBRARY_PATH:-}" ldd "$sofile" | tee /tmp/ldd.out
+            missing="$(awk '/not found/ {print $1}' /tmp/ldd.out | grep -Ev '^(libssl\.so|libcrypto\.so)' || true)"
+            if [ -n "$missing" ]; then
+              echo "$missing"
+              echo "Missing shared dependency for $sofile"
+              exit 1
+            fi
+          done
+
+          if find "$PKG_DIR" -maxdepth 1 -type f \( -name 'libssl.so*' -o -name 'libcrypto.so*' \) | grep .; then
+            echo "OpenSSL libraries must remain system-provided, not bundled."
+            exit 1
+          fi
+
+          if [ "$found" -ne 1 ]; then
+            echo "No Linux shared libraries found in $PKG_DIR"
+            exit 1
+          fi
+
       - name: Update package version
         run: |
           cd packages/${{ matrix.platform }}

CHANGELOG.md

@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- `GopherAgent.run()` now raises `AgentError` when the native library returns a null response instead of returning a `"No response for query"` string.
+
 
 ## [0.1.2] - 2026-03-12
 

README.md

@@ -15,7 +15,18 @@ Python SDK for gopher-mcp-python, providing AI agent orchestration with native C
 ## Requirements
 
 - Python 3.8 or higher
+- `venv` and `pip` for PyPI installation, examples, and development workflows
 - Native gopher-mcp-python library (built from source)
+- On Linux, system OpenSSL runtime libraries (`libssl` / `libcrypto`) from
+  your distribution. Native wheels do not bundle OpenSSL, so OS security
+  updates remain effective.
+
+On Debian/Ubuntu, install the Python venv and pip packages before using the
+PyPI install path, running examples, or setting up development dependencies:
+
+```bash
+sudo apt-get install python3 python3-venv python3-pip
+```
 
 ## Installation
 
@@ -34,7 +45,7 @@ cd gopher-mcp-python
 
 3. Install the Python package:
 ```bash
-pip install -e .
+python3 -m pip install -e .
 ```
 
 ## Quick Start