swytchcode-runtime 1.0.1__tar.gz → 1.1.2__tar.gz

{swytchcode_runtime-1.0.1/swytchcode_runtime.egg-info → swytchcode_runtime-1.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swytchcode-runtime
-Version: 1.0.1
+Version: 1.1.2
 Summary: Thin runtime wrapper around the Swytchcode CLI
 Author: Swytchcode
 License: MIT
@@ -20,11 +20,11 @@ Dynamic: license-file
 
 Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
 
-**Requires:** The `swytchcode` CLI must be installed. The binary is located automatically — no configuration needed in most environments. Resolution order:
+**Requires:** The `swytchcode` CLI must be installed. The binary is located automatically - no configuration needed in most environments. Resolution order:
 
-1. `SWYTCHCODE_BIN` env var — explicit override.
-2. `$PATH` lookup via `shutil.which` — the standard system resolution.
-3. Common install paths — `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
+1. `SWYTCHCODE_BIN` env var - explicit override.
+2. `$PATH` lookup via `shutil.which` - the standard system resolution.
+3. Common install paths - `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
 
 ## Install
 
@@ -52,10 +52,10 @@ result = exec("api.account.create", {"email": "test@example.com"})
 Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
 
 **Request input (args):** The second argument is the kernel **args** object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
-- **body** — Request body (dict).
-- **params** — Query/path params (e.g. `{"id": "cluster-123"}`).
-- **Authorization** — Auth header value (e.g. `"Bearer token123"`).
-- **headers** — Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
+- **body** - Request body (dict).
+- **params** - Query/path params (e.g. `{"id": "cluster-123"}`).
+- **Authorization** - Auth header value (e.g. `"Bearer token123"`).
+- **headers** - Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
 - Other top-level keys are passed as query params.
 
 Example with body, params, and headers:
@@ -81,20 +81,22 @@ output = exec("api.report.export", {"id": "123"}, raw=True)
 
 ### Options
 
-- **cwd** – Working directory for the process (default: current directory).
-- **env** – Extra environment variables (merged with `os.environ`).
-- **raw** – If `True`, use `--raw` and return stdout as a string.
-- **dry_run** – If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
-- **allow_raw** – If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
+- **cwd** - Working directory for the process (default: current directory).
+- **env** - Extra environment variables (merged with `os.environ`).
+- **raw** - If `True`, use `--raw` and return stdout as a string.
+- **dry_run** - If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
+- **allow_raw** - If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
 
 This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
 
 ### Environment variables
 
+This runtime itself needs no environment configuration to run - all auth lives in the CLI's own session (`swytchcode login`, stored under `~/.swytchcode/`) or in `.swytchcode/` in your project. The variables below are for the rarer cases where you need to override that:
+
 | Variable | Description |
 |----------|-------------|
 | `SWYTCHCODE_BIN` | Override the resolved binary path. Set this only when automatic resolution does not find the correct binary (e.g. non-standard install locations or virtualised environments). |
-| `SWYTCHCODE_TOKEN` | Auth token passed to the CLI via the process environment. |
+| `SWYTCHCODE_TOKEN` | Service-token auth for headless environments (CI, servers) where an interactive `swytchcode login` isn't possible. Not needed for local development once you've run `swytchcode login`. |
 
 ### Error handling
 
@@ -111,6 +113,14 @@ except Exception as e:
     raise
 ```
 
+On a non-zero exit the CLI writes a classified JSON error to stderr; `exec()` parses it into a clean `.message` and a structured `.details` dict (`category`, `retryable`, `suggested_action`, `docs_url`) instead of leaving you to parse the raw JSON yourself:
+
+```python
+except SwytchcodeError as e:
+    if e.details and e.details.get("category") == "auth":
+        print(e.details.get("suggested_action"))
+```
+
 ## What this library is
 
 - A thin process wrapper over the Swytchcode shell.
@@ -151,9 +161,48 @@ For full, production-ready examples across all major frameworks, check out the [
 
 On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools into the native tool objects each agent framework expects. 
 
+### Tool-use guidance - `TOOL_USE_INSTRUCTIONS`
+
+Without an explicit nudge, models can be conservative about side-effecting actions (starring a repo, sending a payment, creating an issue) - they'll describe what they *would* do instead of actually calling the tool. `TOOL_USE_INSTRUCTIONS` is a short, framework-agnostic string that fixes this; concatenate it into whatever your provider calls its system prompt / instructions. It's scoped to only the tools this library provides, so it's safe to combine with instructions for other, unrelated tools in the same system prompt:
+
+```python
+from swytchcode_runtime import TOOL_USE_INSTRUCTIONS
+
+system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
+```
+
 ### Quickstart: Anthropic SDK
 
-Here is a clean example of building a simple agent using the Anthropic SDK. We use `python-dotenv` to load environment variables (like `ANTHROPIC_API_KEY`).
+Here is a clean example of building a simple agent using the Anthropic SDK. It stars the [Swytchcode Examples repo](https://github.com/swytchcodehq/swytchcode-examples) on GitHub - a genuine OAuth-connected action (not just an API key passed on the request), so the setup below covers the real one-time flow: installing the CLI, logging in, and connecting a GitHub account.
+
+**One-time setup** (run once per machine/project):
+
+```bash
+# 1. Install the CLI (macOS/Linux; see https://cli.swytchcode.com for other platforms)
+curl -fsSL https://cli.swytchcode.com/install.sh | sh
+
+# 2. Scaffold .swytchcode/ + tooling.json in your project
+swytchcode init
+
+# 3. Log in (opens a browser; creates your Swytchcode session)
+swytchcode login
+
+# 4. Fetch the GitHub integration
+swytchcode get github
+
+# 5. Enable the "star a repo" tool - the trust boundary for what this project can call
+swytchcode add github.user.starred.update
+
+# 6. Connect your GitHub account (opens a browser for the OAuth flow)
+swytchcode auth connect github
+```
+
+Then add your Anthropic key to a `.env` file in your project root (used by `python-dotenv` below):
+
+```bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+```
 
 **Installation:**
 ```bash
@@ -166,29 +215,36 @@ pip install swytchcode-runtime anthropic python-dotenv
 import os
 from dotenv import load_dotenv
 import anthropic
-from swytchcode_runtime import Swytchcode
+from swytchcode_runtime import Swytchcode, TOOL_USE_INSTRUCTIONS
 from swytchcode_runtime.providers.anthropic import AnthropicProvider
 
 load_dotenv()  # Loads .env automatically
 
 def run_agent():
     client = anthropic.Anthropic()
-    
+
     # 1. Initialize Swytchcode with the Anthropic provider
     swx = Swytchcode(provider=AnthropicProvider())
-    
-    # 2. Fetch the tools you want your agent to use (e.g., Stripe tools)
-    tools = swx.tools.get(toolkits=["stripe"])
 
-    # 3. Pass them to Claude
+    # 2. Fetch the tools you want your agent to use (e.g., GitHub tools)
+    tools = swx.tools.get(toolkits=["github"])
+
+    # 3. Build the system prompt: your own instructions plus TOOL_USE_INSTRUCTIONS,
+    # which tells Claude to call the tool directly for action requests instead of
+    # just describing what it would do
+    system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
+
     response = client.messages.create(
-        model="claude-3-5-sonnet-latest",
+        model="claude-sonnet-5",
         max_tokens=1024,
+        system=system,
         tools=tools,
-        messages=[{"role": "user", "content": "Refund charge ch_123 for $20."}],
+        messages=[{"role": "user", "content": "Star the swytchcodehq/swytchcode-examples repo on GitHub for me."}],
     )
 
-    print(response)
+    # 4. Run any tool calls Claude made and send the results back
+    results = swx.handle_tool_calls(response)
+    print(results)
 
 if __name__ == "__main__":
     run_agent()

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/README.md

@@ -2,11 +2,11 @@
 
 Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
 
-**Requires:** The `swytchcode` CLI must be installed. The binary is located automatically — no configuration needed in most environments. Resolution order:
+**Requires:** The `swytchcode` CLI must be installed. The binary is located automatically - no configuration needed in most environments. Resolution order:
 
-1. `SWYTCHCODE_BIN` env var — explicit override.
-2. `$PATH` lookup via `shutil.which` — the standard system resolution.
-3. Common install paths — `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
+1. `SWYTCHCODE_BIN` env var - explicit override.
+2. `$PATH` lookup via `shutil.which` - the standard system resolution.
+3. Common install paths - `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
 
 ## Install
 
@@ -34,10 +34,10 @@ result = exec("api.account.create", {"email": "test@example.com"})
 Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
 
 **Request input (args):** The second argument is the kernel **args** object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
-- **body** — Request body (dict).
-- **params** — Query/path params (e.g. `{"id": "cluster-123"}`).
-- **Authorization** — Auth header value (e.g. `"Bearer token123"`).
-- **headers** — Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
+- **body** - Request body (dict).
+- **params** - Query/path params (e.g. `{"id": "cluster-123"}`).
+- **Authorization** - Auth header value (e.g. `"Bearer token123"`).
+- **headers** - Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
 - Other top-level keys are passed as query params.
 
 Example with body, params, and headers:
@@ -63,20 +63,22 @@ output = exec("api.report.export", {"id": "123"}, raw=True)
 
 ### Options
 
-- **cwd** – Working directory for the process (default: current directory).
-- **env** – Extra environment variables (merged with `os.environ`).
-- **raw** – If `True`, use `--raw` and return stdout as a string.
-- **dry_run** – If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
-- **allow_raw** – If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
+- **cwd** - Working directory for the process (default: current directory).
+- **env** - Extra environment variables (merged with `os.environ`).
+- **raw** - If `True`, use `--raw` and return stdout as a string.
+- **dry_run** - If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
+- **allow_raw** - If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
 
 This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
 
 ### Environment variables
 
+This runtime itself needs no environment configuration to run - all auth lives in the CLI's own session (`swytchcode login`, stored under `~/.swytchcode/`) or in `.swytchcode/` in your project. The variables below are for the rarer cases where you need to override that:
+
 | Variable | Description |
 |----------|-------------|
 | `SWYTCHCODE_BIN` | Override the resolved binary path. Set this only when automatic resolution does not find the correct binary (e.g. non-standard install locations or virtualised environments). |
-| `SWYTCHCODE_TOKEN` | Auth token passed to the CLI via the process environment. |
+| `SWYTCHCODE_TOKEN` | Service-token auth for headless environments (CI, servers) where an interactive `swytchcode login` isn't possible. Not needed for local development once you've run `swytchcode login`. |
 
 ### Error handling
 
@@ -93,6 +95,14 @@ except Exception as e:
     raise
 ```
 
+On a non-zero exit the CLI writes a classified JSON error to stderr; `exec()` parses it into a clean `.message` and a structured `.details` dict (`category`, `retryable`, `suggested_action`, `docs_url`) instead of leaving you to parse the raw JSON yourself:
+
+```python
+except SwytchcodeError as e:
+    if e.details and e.details.get("category") == "auth":
+        print(e.details.get("suggested_action"))
+```
+
 ## What this library is
 
 - A thin process wrapper over the Swytchcode shell.
@@ -133,9 +143,48 @@ For full, production-ready examples across all major frameworks, check out the [
 
 On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools into the native tool objects each agent framework expects. 
 
+### Tool-use guidance - `TOOL_USE_INSTRUCTIONS`
+
+Without an explicit nudge, models can be conservative about side-effecting actions (starring a repo, sending a payment, creating an issue) - they'll describe what they *would* do instead of actually calling the tool. `TOOL_USE_INSTRUCTIONS` is a short, framework-agnostic string that fixes this; concatenate it into whatever your provider calls its system prompt / instructions. It's scoped to only the tools this library provides, so it's safe to combine with instructions for other, unrelated tools in the same system prompt:
+
+```python
+from swytchcode_runtime import TOOL_USE_INSTRUCTIONS
+
+system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
+```
+
 ### Quickstart: Anthropic SDK
 
-Here is a clean example of building a simple agent using the Anthropic SDK. We use `python-dotenv` to load environment variables (like `ANTHROPIC_API_KEY`).
+Here is a clean example of building a simple agent using the Anthropic SDK. It stars the [Swytchcode Examples repo](https://github.com/swytchcodehq/swytchcode-examples) on GitHub - a genuine OAuth-connected action (not just an API key passed on the request), so the setup below covers the real one-time flow: installing the CLI, logging in, and connecting a GitHub account.
+
+**One-time setup** (run once per machine/project):
+
+```bash
+# 1. Install the CLI (macOS/Linux; see https://cli.swytchcode.com for other platforms)
+curl -fsSL https://cli.swytchcode.com/install.sh | sh
+
+# 2. Scaffold .swytchcode/ + tooling.json in your project
+swytchcode init
+
+# 3. Log in (opens a browser; creates your Swytchcode session)
+swytchcode login
+
+# 4. Fetch the GitHub integration
+swytchcode get github
+
+# 5. Enable the "star a repo" tool - the trust boundary for what this project can call
+swytchcode add github.user.starred.update
+
+# 6. Connect your GitHub account (opens a browser for the OAuth flow)
+swytchcode auth connect github
+```
+
+Then add your Anthropic key to a `.env` file in your project root (used by `python-dotenv` below):
+
+```bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+```
 
 **Installation:**
 ```bash
@@ -148,29 +197,36 @@ pip install swytchcode-runtime anthropic python-dotenv
 import os
 from dotenv import load_dotenv
 import anthropic
-from swytchcode_runtime import Swytchcode
+from swytchcode_runtime import Swytchcode, TOOL_USE_INSTRUCTIONS
 from swytchcode_runtime.providers.anthropic import AnthropicProvider
 
 load_dotenv()  # Loads .env automatically
 
 def run_agent():
     client = anthropic.Anthropic()
-    
+
     # 1. Initialize Swytchcode with the Anthropic provider
     swx = Swytchcode(provider=AnthropicProvider())
-    
-    # 2. Fetch the tools you want your agent to use (e.g., Stripe tools)
-    tools = swx.tools.get(toolkits=["stripe"])
 
-    # 3. Pass them to Claude
+    # 2. Fetch the tools you want your agent to use (e.g., GitHub tools)
+    tools = swx.tools.get(toolkits=["github"])
+
+    # 3. Build the system prompt: your own instructions plus TOOL_USE_INSTRUCTIONS,
+    # which tells Claude to call the tool directly for action requests instead of
+    # just describing what it would do
+    system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
+
     response = client.messages.create(
-        model="claude-3-5-sonnet-latest",
+        model="claude-sonnet-5",
         max_tokens=1024,
+        system=system,
         tools=tools,
-        messages=[{"role": "user", "content": "Refund charge ch_123 for $20."}],
+        messages=[{"role": "user", "content": "Star the swytchcodehq/swytchcode-examples repo on GitHub for me."}],
     )
 
-    print(response)
+    # 4. Run any tool calls Claude made and send the results back
+    results = swx.handle_tool_calls(response)
+    print(results)
 
 if __name__ == "__main__":
     run_agent()

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "swytchcode-runtime"
-version = "1.0.1"
+version = "1.1.2"
 description = "Thin runtime wrapper around the Swytchcode CLI"
 readme = "README.md"
 license = { text = "MIT" }

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/__init__.py

@@ -1,13 +1,15 @@
 """Thin runtime wrapper around the Swytchcode CLI."""
 
+from .client import Swytchcode
 from .errors import SwytchcodeError, is_swytchcode_error
 from .exec import exec_ as exec
-from .client import Swytchcode
+from .prompts import TOOL_USE_INSTRUCTIONS
 
 __all__ = [
-    "exec",
+    "TOOL_USE_INSTRUCTIONS",
     "Swytchcode",
     "SwytchcodeError",
+    "exec",
     "is_swytchcode_error",
 ]
 

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/cli.py

@@ -1,13 +1,14 @@
 """Run a swytchcode CLI subcommand with --json and parse the output."""
 
 from __future__ import annotations
+
 import json
 import os
 import subprocess
 from typing import Any
 
-from .exec import _resolve_bin
 from .errors import SwytchcodeError
+from .exec import _resolve_bin
 
 
 def run_cli(
@@ -32,6 +33,7 @@ def run_cli(
             cwd=cwd or os.getcwd(),
             env=run_env,
             timeout=timeout,
+            check=False,
         )
     except FileNotFoundError as e:
         raise SwytchcodeError(

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/client.py

@@ -1,16 +1,17 @@
 """High-level agentic client on top of the existing exec()."""
 
 from __future__ import annotations
-from typing import Any, Optional
 
-import re
 import hashlib
+import re
+from typing import Any
 
-from . import discover as _discover, schema as _schema, manage as _manage
+from . import discover as _discover
+from . import manage as _manage
+from . import schema as _schema
 from .exec import exec_ as _exec
 from .providers.base import Provider, Tool
 
-
 MAX_TOOL_NAME_LEN = 64  # OpenAI and Anthropic strict limit
 
 
@@ -107,7 +108,7 @@ def _split_by_location(inputs: Any, flat_args: dict) -> dict:
 
 
 class _Tools:
-    def __init__(self, client: "Swytchcode"):
+    def __init__(self, client: Swytchcode):
         self._c = client
         # Maps a sanitized tool name (dots -> underscores) back to its canonical
         # ID, populated as tools are built. Used to reverse names in
@@ -199,7 +200,7 @@ class _Tools:
 
 
 class Swytchcode:
-    def __init__(self, provider: Optional[Provider] = None):
+    def __init__(self, provider: Provider | None = None):
         self.provider = provider
         self.tools = _Tools(self)
 
@@ -229,7 +230,7 @@ class Swytchcode:
                         )
                     )
                     is_error = False
-                except Exception as e:
+                except Exception as e:  # noqa: BLE001
                     content = f"Error executing {cid}: {e}"
                     is_error = True
                 results.append(

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/discover.py

@@ -1,7 +1,9 @@
 """Find tools by intent and read their schemas."""
 
 from __future__ import annotations
+
 import logging
+
 from .cli import run_cli
 
 logger = logging.getLogger(__name__)
@@ -19,7 +21,7 @@ def info(canonical_id: str) -> dict:
         if isinstance(result, list):
             return result[0] if result else {}
         return result
-    except Exception as e:
+    except Exception as e:  # noqa: BLE001
         # Broad by design: any CLI/parse failure degrades to an empty schema
         # rather than breaking tool discovery. Logged (not printed) so it
         # respects the host app's logging config.

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/errors.py

@@ -6,10 +6,19 @@ from typing import Any
 class SwytchcodeError(Exception):
     """Raised when exec() fails: spawn error, non-zero exit, or invalid JSON output."""
 
-    def __init__(self, message: str, cause: Any = None) -> None:
+    def __init__(
+        self,
+        message: str,
+        cause: Any = None,
+        details: dict[str, Any] | None = None,
+    ) -> None:
         super().__init__(message)
         self.message = message
         self.cause = cause
+        # Structured detail parsed from the CLI's classified JSON error (stderr),
+        # when available: category, retryable, suggested_action, docs_url. None for
+        # spawn errors, signals, or CLI versions predating this format.
+        self.details = details
 
     def __str__(self) -> str:
         if self.cause is not None:

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/exec.py

@@ -50,7 +50,26 @@ def _resolve_bin() -> str:
     return "swytchcode"  # fall through; subprocess.run reports FileNotFoundError if still missing
 
 
-def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
+def _parse_classified_error(stderr: str) -> dict[str, Any] | None:
+    """
+    The CLI writes a classified JSON error to stderr on every non-zero exit that
+    isn't a signal (see internal/kernel/errors.go's WriteClassifiedError) - always
+    JSON, even in --raw mode. Parsing it here turns a raw JSON blob into a clean
+    message plus structured details, instead of leaving the developer to see
+    '{"error": "...", ...}' as the exception message.
+    """
+    if not stderr:
+        return None
+    try:
+        obj = json.loads(stderr)
+    except json.JSONDecodeError:
+        return None
+    if isinstance(obj, dict) and isinstance(obj.get("error"), str):
+        return obj
+    return None
+
+
+def exec_(
     canonical_id: str,
     input: Any = None,
     *,
@@ -117,6 +136,7 @@ def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
             cwd=cwd or os.getcwd(),
             env=run_env,
             timeout=timeout,
+            check=False,
         )
     except subprocess.TimeoutExpired as e:
         raise SwytchcodeError(
@@ -128,7 +148,7 @@ def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
             if "SWYTCHCODE_BIN" in os.environ
             else "install it with: npm install -g swytchcode (or set SWYTCHCODE_BIN=/path/to/binary)"
         )
-        raise SwytchcodeError(f"Failed to spawn swytchcode — {hint}", e) from e
+        raise SwytchcodeError(f"Failed to spawn swytchcode - {hint}", e) from e
     except OSError as e:
         raise SwytchcodeError("Failed to run swytchcode", e) from e
 
@@ -136,6 +156,18 @@ def exec_(  # noqa: A001 - shadowing intentional for API consistency with JS/Go
     stdout = result.stdout.decode("utf-8", errors="replace")
 
     if result.returncode != 0:
+        classified = _parse_classified_error(stderr)
+        if classified:
+            msg = classified["error"]
+            if classified.get("suggested_action"):
+                msg = f"{msg} - {classified['suggested_action']}"
+            details = {
+                "category": classified.get("category"),
+                "retryable": classified.get("retryable"),
+                "suggested_action": classified.get("suggested_action"),
+                "docs_url": classified.get("docs_url"),
+            }
+            raise SwytchcodeError(msg, result.returncode, details)
         msg = stderr or "swytchcode exec failed"
         raise SwytchcodeError(msg, result.returncode)
 

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/manage.py

@@ -1,6 +1,7 @@
 """Management commands wrapper for the SDK."""
 
 from __future__ import annotations
+
 from .cli import run_cli
 
 

swytchcode_runtime-1.1.2/swytchcode_runtime/prompts.py

@@ -0,0 +1,19 @@
+"""Tool-use guidance for models - see TOOL_USE_INSTRUCTIONS."""
+
+# Models can be conservative about side-effecting actions (e.g. starring a repo,
+# sending a payment) when a system prompt doesn't explicitly grant permission to
+# act - they describe what they would do instead of calling the tool. Concatenate
+# this into your system prompt / instructions to fix that.
+#
+# Scoped deliberately to only the tools this library provides: a combined system
+# prompt often carries instructions for other, unrelated tools too, and a vaguer
+# "call tools directly" instruction could be read as applying to those as well.
+TOOL_USE_INSTRUCTIONS = (
+    "The tools below are provided by Swytchcode and represent real actions on connected "
+    "services (e.g. starring a repo, creating an issue, sending a payment). When the "
+    "user's request describes one of these actions, call the matching tool directly and "
+    "let it run - do not just describe what you would do, ask for confirmation first, or "
+    "wait for clarification if the request is already unambiguous. This guidance applies "
+    "only to the Swytchcode tools provided here - it does not affect how you use any "
+    "other tools available to you."
+)

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/providers/anthropic.py

@@ -1,6 +1,7 @@
 """Anthropic Claude provider (Non-agentic / raw tool use schemas)."""
 
 from __future__ import annotations
+
 from .base import Provider, Tool
 
 

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/providers/base.py

@@ -5,13 +5,16 @@ native tool object, and `format_tools` maps over a list. Execution is carried on
 the Tool itself via its `execute` closure (which runs the Swytchcode CLI): agentic
 frameworks (OpenAI Agents, Vercel, LangGraph, CrewAI) invoke that closure directly
 during their own loop, while non-agentic APIs (Anthropic) run it through
-`Swytchcode.handle_tool_calls`. Note this is deliberately NOT Composio's two-class
-agentic/non-agentic split - execution lives on the tool, not an injected function.
+`Swytchcode.handle_tool_calls`. Execution deliberately lives on the tool itself
+rather than an injected function, so both agentic and non-agentic callers share
+one code path instead of needing a separate split.
 """
 
 from __future__ import annotations
+
+from collections.abc import Callable
 from dataclasses import dataclass
-from typing import Any, Callable
+from typing import Any
 
 
 @dataclass

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/providers/crewai.py

@@ -1,12 +1,14 @@
 """CrewAI provider: neutral tools -> BaseTool subclasses."""
 
 from __future__ import annotations
+
 from .base import Provider, Tool
 
 
 class CrewAIProvider(Provider):
     def format_tool(self, tool: Tool):
         from crewai.tools import BaseTool
+
         from ..schema import to_pydantic_model
 
         args_schema_cls = to_pydantic_model(tool.input_schema, tool.name + "Schema")

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/providers/langgraph.py

@@ -1,12 +1,14 @@
 """LangGraph provider: neutral tools -> LangChain StructuredTool objects."""
 
 from __future__ import annotations
+
 from .base import Provider, Tool
 
 
 class LangGraphProvider(Provider):
     def format_tool(self, tool: Tool):
         from langchain_core.tools import StructuredTool
+
         from ..schema import to_pydantic_model
 
         return StructuredTool.from_function(

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/providers/openai_agents.py

@@ -1,8 +1,10 @@
 """OpenAI Agents SDK provider."""
 
 from __future__ import annotations
+
 import asyncio
 import json
+
 from .base import Provider, Tool
 
 

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/providers/vercel.py

@@ -1,6 +1,7 @@
 """Vercel AI SDK provider (Python equivalent)."""
 
 from __future__ import annotations
+
 from .base import Provider, Tool
 
 

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime/schema.py

@@ -1,7 +1,8 @@
 """Simplify a tool's input schema for the LLM: expose all fields, mark required ones."""
 
 from __future__ import annotations
-from typing import Any, Optional
+
+from typing import Any
 
 
 def simplify(inputs: Any) -> dict:
@@ -24,9 +25,7 @@ def simplify(inputs: Any) -> dict:
                     t = "number"
                 elif t == "bool":
                     t = "boolean"
-                elif t == "object":
-                    t = "object"
-                elif t == "any":
+                elif t == "object" or t == "any":
                     t = "object"
                 elif t.startswith("[]"):
                     t = "array"
@@ -45,7 +44,7 @@ def simplify(inputs: Any) -> dict:
                 if is_required:
                     required.append(name)
 
-        # Composio-style rule: expose ALL fields to the model and list only the
+        # rule: expose ALL fields to the model and list only the
         # truly-required ones in `required`. A required-only approach hid optional
         # fields - which left all-optional tools (e.g. Stripe) with an empty schema
         # so the model called them with no arguments, and blinded the model to
@@ -108,8 +107,8 @@ def to_pydantic_model(schema: dict, name: str = "ArgsSchema") -> Any:
         if field_name in required:
             fields[field_name] = (field_type, ...)
         else:
-            # Optional[...] so an explicit null is accepted (pydantic v2 rejects
+            # `X | None` so an explicit null is accepted (pydantic v2 rejects
             # None for a bare non-optional annotation).
-            fields[field_name] = (Optional[field_type], None)
+            fields[field_name] = (field_type | None, None)
 
     return create_model(name, **fields)

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2/swytchcode_runtime.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: swytchcode-runtime
-Version: 1.0.1
+Version: 1.1.2
 Summary: Thin runtime wrapper around the Swytchcode CLI
 Author: Swytchcode
 License: MIT
@@ -20,11 +20,11 @@ Dynamic: license-file
 
 Thin runtime wrapper around the Swytchcode CLI. Calls `swytchcode exec` for you so you can stay in Python without shell boilerplate.
 
-**Requires:** The `swytchcode` CLI must be installed. The binary is located automatically — no configuration needed in most environments. Resolution order:
+**Requires:** The `swytchcode` CLI must be installed. The binary is located automatically - no configuration needed in most environments. Resolution order:
 
-1. `SWYTCHCODE_BIN` env var — explicit override.
-2. `$PATH` lookup via `shutil.which` — the standard system resolution.
-3. Common install paths — `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
+1. `SWYTCHCODE_BIN` env var - explicit override.
+2. `$PATH` lookup via `shutil.which` - the standard system resolution.
+3. Common install paths - `~/.local/bin`, `/usr/local/bin` (Unix) or `%LOCALAPPDATA%\Programs\swytchcode\bin` (Windows).
 
 ## Install
 
@@ -52,10 +52,10 @@ result = exec("api.account.create", {"email": "test@example.com"})
 Equivalent to: `swytchcode exec api.account.create --json` with args on stdin.
 
 **Request input (args):** The second argument is the kernel **args** object (sent as JSON on stdin). Use this shape so the kernel builds the request correctly:
-- **body** — Request body (dict).
-- **params** — Query/path params (e.g. `{"id": "cluster-123"}`).
-- **Authorization** — Auth header value (e.g. `"Bearer token123"`).
-- **headers** — Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
+- **body** - Request body (dict).
+- **params** - Query/path params (e.g. `{"id": "cluster-123"}`).
+- **Authorization** - Auth header value (e.g. `"Bearer token123"`).
+- **headers** - Additional request headers (e.g. `{"X-Request-Id": "abc-123"}`).
 - Other top-level keys are passed as query params.
 
 Example with body, params, and headers:
@@ -81,20 +81,22 @@ output = exec("api.report.export", {"id": "123"}, raw=True)
 
 ### Options
 
-- **cwd** – Working directory for the process (default: current directory).
-- **env** – Extra environment variables (merged with `os.environ`).
-- **raw** – If `True`, use `--raw` and return stdout as a string.
-- **dry_run** – If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
-- **allow_raw** – If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
+- **cwd** - Working directory for the process (default: current directory).
+- **env** - Extra environment variables (merged with `os.environ`).
+- **raw** - If `True`, use `--raw` and return stdout as a string.
+- **dry_run** - If `True`, pass `--dry-run` to the CLI; request details (method, url, headers, body) are output instead of calling the server.
+- **allow_raw** - If `True`, pass `--allow-raw` to the CLI; required for executing raw methods (kernel has this disabled by default).
 
 This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
 
 ### Environment variables
 
+This runtime itself needs no environment configuration to run - all auth lives in the CLI's own session (`swytchcode login`, stored under `~/.swytchcode/`) or in `.swytchcode/` in your project. The variables below are for the rarer cases where you need to override that:
+
 | Variable | Description |
 |----------|-------------|
 | `SWYTCHCODE_BIN` | Override the resolved binary path. Set this only when automatic resolution does not find the correct binary (e.g. non-standard install locations or virtualised environments). |
-| `SWYTCHCODE_TOKEN` | Auth token passed to the CLI via the process environment. |
+| `SWYTCHCODE_TOKEN` | Service-token auth for headless environments (CI, servers) where an interactive `swytchcode login` isn't possible. Not needed for local development once you've run `swytchcode login`. |
 
 ### Error handling
 
@@ -111,6 +113,14 @@ except Exception as e:
     raise
 ```
 
+On a non-zero exit the CLI writes a classified JSON error to stderr; `exec()` parses it into a clean `.message` and a structured `.details` dict (`category`, `retryable`, `suggested_action`, `docs_url`) instead of leaving you to parse the raw JSON yourself:
+
+```python
+except SwytchcodeError as e:
+    if e.details and e.details.get("category") == "auth":
+        print(e.details.get("suggested_action"))
+```
+
 ## What this library is
 
 - A thin process wrapper over the Swytchcode shell.
@@ -151,9 +161,48 @@ For full, production-ready examples across all major frameworks, check out the [
 
 On top of `exec`, the runtime exposes a small agentic surface that turns Swytchcode tools into the native tool objects each agent framework expects. 
 
+### Tool-use guidance - `TOOL_USE_INSTRUCTIONS`
+
+Without an explicit nudge, models can be conservative about side-effecting actions (starring a repo, sending a payment, creating an issue) - they'll describe what they *would* do instead of actually calling the tool. `TOOL_USE_INSTRUCTIONS` is a short, framework-agnostic string that fixes this; concatenate it into whatever your provider calls its system prompt / instructions. It's scoped to only the tools this library provides, so it's safe to combine with instructions for other, unrelated tools in the same system prompt:
+
+```python
+from swytchcode_runtime import TOOL_USE_INSTRUCTIONS
+
+system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
+```
+
 ### Quickstart: Anthropic SDK
 
-Here is a clean example of building a simple agent using the Anthropic SDK. We use `python-dotenv` to load environment variables (like `ANTHROPIC_API_KEY`).
+Here is a clean example of building a simple agent using the Anthropic SDK. It stars the [Swytchcode Examples repo](https://github.com/swytchcodehq/swytchcode-examples) on GitHub - a genuine OAuth-connected action (not just an API key passed on the request), so the setup below covers the real one-time flow: installing the CLI, logging in, and connecting a GitHub account.
+
+**One-time setup** (run once per machine/project):
+
+```bash
+# 1. Install the CLI (macOS/Linux; see https://cli.swytchcode.com for other platforms)
+curl -fsSL https://cli.swytchcode.com/install.sh | sh
+
+# 2. Scaffold .swytchcode/ + tooling.json in your project
+swytchcode init
+
+# 3. Log in (opens a browser; creates your Swytchcode session)
+swytchcode login
+
+# 4. Fetch the GitHub integration
+swytchcode get github
+
+# 5. Enable the "star a repo" tool - the trust boundary for what this project can call
+swytchcode add github.user.starred.update
+
+# 6. Connect your GitHub account (opens a browser for the OAuth flow)
+swytchcode auth connect github
+```
+
+Then add your Anthropic key to a `.env` file in your project root (used by `python-dotenv` below):
+
+```bash
+# .env
+ANTHROPIC_API_KEY=sk-ant-...
+```
 
 **Installation:**
 ```bash
@@ -166,29 +215,36 @@ pip install swytchcode-runtime anthropic python-dotenv
 import os
 from dotenv import load_dotenv
 import anthropic
-from swytchcode_runtime import Swytchcode
+from swytchcode_runtime import Swytchcode, TOOL_USE_INSTRUCTIONS
 from swytchcode_runtime.providers.anthropic import AnthropicProvider
 
 load_dotenv()  # Loads .env automatically
 
 def run_agent():
     client = anthropic.Anthropic()
-    
+
     # 1. Initialize Swytchcode with the Anthropic provider
     swx = Swytchcode(provider=AnthropicProvider())
-    
-    # 2. Fetch the tools you want your agent to use (e.g., Stripe tools)
-    tools = swx.tools.get(toolkits=["stripe"])
 
-    # 3. Pass them to Claude
+    # 2. Fetch the tools you want your agent to use (e.g., GitHub tools)
+    tools = swx.tools.get(toolkits=["github"])
+
+    # 3. Build the system prompt: your own instructions plus TOOL_USE_INSTRUCTIONS,
+    # which tells Claude to call the tool directly for action requests instead of
+    # just describing what it would do
+    system = f"You are a helpful assistant.\n\n{TOOL_USE_INSTRUCTIONS}"
+
     response = client.messages.create(
-        model="claude-3-5-sonnet-latest",
+        model="claude-sonnet-5",
         max_tokens=1024,
+        system=system,
         tools=tools,
-        messages=[{"role": "user", "content": "Refund charge ch_123 for $20."}],
+        messages=[{"role": "user", "content": "Star the swytchcodehq/swytchcode-examples repo on GitHub for me."}],
     )
 
-    print(response)
+    # 4. Run any tool calls Claude made and send the results back
+    results = swx.handle_tool_calls(response)
+    print(results)
 
 if __name__ == "__main__":
     run_agent()

{swytchcode_runtime-1.0.1 → swytchcode_runtime-1.1.2}/swytchcode_runtime.egg-info/SOURCES.txt

@@ -8,6 +8,7 @@ swytchcode_runtime/discover.py
 swytchcode_runtime/errors.py
 swytchcode_runtime/exec.py
 swytchcode_runtime/manage.py
+swytchcode_runtime/prompts.py
 swytchcode_runtime/schema.py
 swytchcode_runtime.egg-info/PKG-INFO
 swytchcode_runtime.egg-info/SOURCES.txt
@@ -21,4 +22,6 @@ swytchcode_runtime/providers/langgraph.py
 swytchcode_runtime/providers/openai_agents.py
 swytchcode_runtime/providers/vercel.py
 tests/test_alias.py
+tests/test_exec_errors.py
+tests/test_prompts.py
 tests/test_schema_routing.py

swytchcode_runtime-1.1.2/tests/test_exec_errors.py

@@ -0,0 +1,36 @@
+import json
+import unittest
+
+from swytchcode_runtime.exec import _parse_classified_error
+
+
+class TestParseClassifiedError(unittest.TestCase):
+    def test_extracts_the_clis_classified_json_error_from_stderr(self):
+        stderr = json.dumps(
+            {
+                "error": "missing credentials for github - run `swytchcode auth connect github`",
+                "category": "auth",
+                "retryable": False,
+                "suggested_action": "to access registry features, run: swytchcode login",
+                "docs_url": "https://docs.swytchcode.com/auth",
+            }
+        )
+        parsed = _parse_classified_error(stderr)
+        self.assertEqual(
+            parsed["error"],
+            "missing credentials for github - run `swytchcode auth connect github`",
+        )
+        self.assertEqual(parsed["category"], "auth")
+        self.assertEqual(
+            parsed["suggested_action"],
+            "to access registry features, run: swytchcode login",
+        )
+
+    def test_returns_none_for_non_json_or_shapeless_stderr(self):
+        self.assertIsNone(_parse_classified_error(""))
+        self.assertIsNone(_parse_classified_error("a plain-text panic, not JSON"))
+        self.assertIsNone(_parse_classified_error('{"not_error_field": true}'))
+
+
+if __name__ == "__main__":
+    unittest.main()

swytchcode_runtime-1.1.2/tests/test_prompts.py

@@ -0,0 +1,21 @@
+import re
+import unittest
+
+from swytchcode_runtime import TOOL_USE_INSTRUCTIONS
+
+
+class TestToolUseInstructions(unittest.TestCase):
+    def test_is_exported_and_instructs_the_model_to_call_tools(self):
+        self.assertIsInstance(TOOL_USE_INSTRUCTIONS, str)
+        self.assertTrue(len(TOOL_USE_INSTRUCTIONS) > 0)
+        self.assertRegex(TOOL_USE_INSTRUCTIONS, re.compile("call the matching tool", re.I))
+
+    def test_scopes_itself_to_swytchcode_tools_only(self):
+        self.assertRegex(
+            TOOL_USE_INSTRUCTIONS,
+            re.compile(r"does not affect how you use any\s+other tools", re.I),
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()