End users of your app: connect, saveKey, disconnect and tenantId

README.md

@@ -68,6 +68,8 @@ output = exec("api.report.export", {"id": "123"}, raw=True)
 - **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).
+- **tenant_id** - Run the call for one end user of your app, with their own connected account (passes `--tenant`). Never falls back to your account. See [Multi-tenant apps](#multi-tenant-apps).
+- **tenant_label** - How approvers see that end user, e.g. `"Alice Smith (alice@acme.com)"` (passes `--tenant-label`). Needs `tenant_id`.
 
 This runtime invokes `swytchcode exec [canonical_id]` with the flags above. For full exec behavior, see the Swytchcode kernel documentation.
 
@@ -103,6 +105,22 @@ except SwytchcodeError as e:
         print(e.details.get("suggested_action"))
 ```
 
+## Multi-tenant apps
+
+When your app's own users each connect their accounts, pass your id for the logged-in user (from your server's session, never from the browser) on every call made for them:
+
+```python
+from swytchcode_runtime import connect, save_key, disconnect, exec, Swytchcode
+
+url = connect("gmail", user.id)["url"]                  # one-time link (OAuth), open it from the user's click
+save_key("stripe", user.id, key)                        # API-key providers: stored on your server only
+exec("gmail.user.profile.get", {"params": {"userId": "me"}}, tenant_id=user.id)
+client = Swytchcode(provider, tenant_id=user.id)        # agents: every tool runs for this user
+disconnect("gmail", user.id)
+```
+
+An end user who has not connected raises `SwytchcodeError` with `details["category"] == "tenant_not_connected"`. Guide: https://docs.swytchcode.com/guides/multi-tenant/
+
 ## What this library is
 
 - A thin process wrapper over the Swytchcode shell.

swytchcode_runtime/__init__.py

@@ -4,13 +4,17 @@
 from .errors import SwytchcodeError, is_swytchcode_error
 from .exec import exec_ as exec
 from .prompts import TOOL_USE_INSTRUCTIONS
+from .tenants import connect, disconnect, save_key
 
 __all__ = [
     "TOOL_USE_INSTRUCTIONS",
     "Swytchcode",
     "SwytchcodeError",
+    "connect",
+    "disconnect",
     "exec",
     "is_swytchcode_error",
+    "save_key",
 ]
 
 

swytchcode_runtime/cli.py

@@ -17,18 +17,21 @@ def run_cli(
     cwd: str | None = None,
     env: dict | None = None,
     timeout: float | None = 60,
+    input: str | None = None,
+    json_output: bool = True,
 ) -> Any:
     run_env = os.environ.copy()
     if env:
         run_env.update(env)
 
     cmd = [_resolve_bin(run_env), *args]
-    if "--json" not in args:
+    if json_output and "--json" not in args:
         cmd.append("--json")
 
     try:
         r = subprocess.run(
             cmd,
+            input=input.encode("utf-8") if input is not None else None,
             capture_output=True,
             cwd=cwd or os.getcwd(),
             env=run_env,
@@ -51,7 +54,7 @@ def run_cli(
         )
 
     out = r.stdout.decode("utf-8", "replace").strip()
-    if not out:
+    if not out or not json_output:
         return None
 
     try:

swytchcode_runtime/client.py

@@ -9,6 +9,7 @@
 from . import discover as _discover
 from . import manage as _manage
 from . import schema as _schema
+from .errors import SwytchcodeError
 from .exec import exec_ as _exec
 from .providers.base import Provider, Tool
 
@@ -170,7 +171,14 @@ def execute(self, canonical_id: str, args: dict, **options) -> Any:
             final_args["body"] = _strip_empty(final_args["body"])
         if isinstance(final_args.get("params"), (dict, list)):
             final_args["params"] = _strip_empty(final_args["params"])
-        # Forward exec options (dry_run, raw, allow_raw, cwd, env) to the CLI.
+        # A client bound to one end user runs every tool for that user unless
+        # the call names another one itself.
+        if self._c.tenant_id is not None and options.get("tenant_id") is None:
+            options["tenant_id"] = self._c.tenant_id
+            if options.get("tenant_label") is None:
+                options["tenant_label"] = self._c.tenant_label
+        # Forward exec options (dry_run, raw, allow_raw, cwd, env, tenant_id,
+        # tenant_label) to the CLI.
         return _exec(canonical_id, final_args, **options)
 
     def _tool(self, cid: str) -> Tool:
@@ -225,8 +233,31 @@ def _ids(self, toolkits, tools, search) -> list[str]:
 
 
 class Swytchcode:
-    def __init__(self, provider: Provider | None = None):
+    def __init__(
+        self,
+        provider: Provider | None = None,
+        *,
+        tenant_id: str | None = None,
+        tenant_label: str | None = None,
+    ):
+        """
+        tenant_id binds the client to one end user of your app: every tool it
+        runs, including those an AI agent picks, uses that user's connected
+        accounts and never yours. Create one client per request, from your
+        server's session. tenant_label is how approvers see that end user, for
+        example "Alice Smith (alice@acme.com)".
+        """
         self.provider = provider
+        if tenant_id is not None:
+            tenant_id = tenant_id.strip()
+            # An empty id would quietly run the agent's tools on your own account.
+            if not tenant_id:
+                raise SwytchcodeError("tenant_id must be a non-empty string when set")
+        self.tenant_id = tenant_id
+        tenant_label = (tenant_label or "").strip() or None
+        if tenant_label and not tenant_id:
+            raise SwytchcodeError("tenant_label needs tenant_id")
+        self.tenant_label = tenant_label
         self.tools = _Tools(self)
 
     def handle_tool_calls(

swytchcode_runtime/exec.py

@@ -80,6 +80,8 @@ def exec_(
     dry_run: bool = False,
     allow_raw: bool = False,
     timeout: float | None = None,
+    tenant_id: str | None = None,
+    tenant_label: str | None = None,
 ) -> Any:
     """
     Run swytchcode exec <canonical_id> with optional JSON args on stdin.
@@ -102,6 +104,14 @@ def exec_(
         dry_run: If True, pass --dry-run; request details are output instead of calling the server.
         allow_raw: If True, pass --allow-raw; required for executing raw methods (kernel default is disabled).
         timeout: Optional timeout in seconds for the subprocess.
+        tenant_id: Run the call for one end user (tenant) of your app, with their own
+            connected account (passes --tenant). Use your own id for the logged-in user,
+            taken from your server's session. Never falls back to your own account: if
+            this user has not connected the provider, it fails with category
+            "tenant_not_connected".
+        tenant_label: How approvers see this end user when a policy asks for human
+            approval, for example "Alice Smith (alice@acme.com)" (passes
+            --tenant-label). Needs tenant_id.
 
     Returns:
         Parsed result (any) or raw string when raw is True.
@@ -112,6 +122,14 @@ def exec_(
     canonical_id = canonical_id.strip()
     if not canonical_id:
         raise SwytchcodeError("canonical_id must be a non-empty string")
+    # An empty tenant id must never quietly run the call on the developer's own account.
+    if tenant_id is not None:
+        tenant_id = tenant_id.strip()
+        if not tenant_id:
+            raise SwytchcodeError("tenant_id must be a non-empty string when set")
+    tenant_label = (tenant_label or "").strip()
+    if tenant_label and not tenant_id:
+        raise SwytchcodeError("tenant_label needs tenant_id")
 
     run_env = os.environ.copy()
     if env:
@@ -124,6 +142,10 @@ def exec_(
         cmd.append("--dry-run")
     if allow_raw:
         cmd.append("--allow-raw")
+    if tenant_id:
+        cmd.extend(["--tenant", tenant_id])
+    if tenant_label:
+        cmd.extend(["--tenant-label", tenant_label])
 
     stdin_payload: bytes | None = None
     if input is not None:

swytchcode_runtime/tenants.py

@@ -0,0 +1,96 @@
+"""Connect, save and remove accounts for the end users (tenants) of your app."""
+
+from __future__ import annotations
+
+from .cli import run_cli
+from .errors import SwytchcodeError
+
+
+def _tenant_args(provider: str, tenant_id: str) -> list[str]:
+    provider = (provider or "").strip()
+    tenant_id = (tenant_id or "").strip()
+    if not provider:
+        raise SwytchcodeError("provider must be a non-empty string")
+    # An empty tenant id would act on the developer's own account.
+    if not tenant_id:
+        raise SwytchcodeError("tenant_id must be a non-empty string")
+    return [provider, "--tenant", tenant_id]
+
+
+def connect(
+    provider: str,
+    tenant_id: str,
+    *,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+) -> dict:
+    """
+    Start an OAuth connection for one end user and return the link they open.
+
+    tenant_id is your own id for the end user, taken from your server's session,
+    never from the browser. The account is ready once they finish in the popup;
+    the first exec() with this tenant_id picks it up. The provider app used
+    (Swytchcode's or your own) is the one you chose with `swytchcode auth connect`.
+
+    Returns {"url": ..., "connected_account_uuid": ...}.
+    """
+    out = run_cli(
+        ["auth", "connect", *_tenant_args(provider, tenant_id), "--json"],
+        cwd=cwd,
+        env=env,
+    )
+    if not isinstance(out, dict) or not out.get("authorization_url"):
+        raise SwytchcodeError(
+            f"{provider} does not connect with OAuth; collect the end user's key "
+            "in your app and save it with save_key()",
+            out,
+        )
+    return {
+        "url": out["authorization_url"],
+        "connected_account_uuid": out.get("connected_account_uuid", ""),
+    }
+
+
+def save_key(
+    provider: str,
+    tenant_id: str,
+    key: str,
+    *,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+) -> None:
+    """
+    Save an end user's API key for a provider that uses keys. The key is stored
+    encrypted on this machine only and never sent to Swytchcode; the end user is
+    recorded (without the key) toward your plan's end-user limit, so this needs a
+    login or API key, and at the limit it raises and nothing is saved.
+    """
+    key = (key or "").strip()
+    if not key:
+        raise SwytchcodeError("key must be a non-empty string")
+    out = run_cli(
+        ["auth", "connect", *_tenant_args(provider, tenant_id), "--json"],
+        cwd=cwd,
+        env=env,
+        input=key + "\n",
+    )
+    if not isinstance(out, dict) or out.get("stored") != "local":
+        raise SwytchcodeError(
+            f"{provider} does not use an API key; use connect() instead", out
+        )
+
+
+def disconnect(
+    provider: str,
+    tenant_id: str,
+    *,
+    cwd: str | None = None,
+    env: dict[str, str] | None = None,
+) -> None:
+    """Remove one end user's account for a provider, on this machine and on Swytchcode."""
+    run_cli(
+        ["auth", "disconnect", *_tenant_args(provider, tenant_id)],
+        cwd=cwd,
+        env=env,
+        json_output=False,
+    )