sidekick-agent-cli 0.1.0__tar.gz

sidekick_agent_cli-0.1.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.coverage
+htmlcov/
+.DS_Store
+*.swp

sidekick_agent_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Datex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sidekick_agent_cli-0.1.0/PKG-INFO

@@ -0,0 +1,122 @@
+Metadata-Version: 2.4
+Name: sidekick-agent-cli
+Version: 0.1.0
+Summary: CLI for the Sidekick Agent Orchestrator
+Project-URL: Homepage, https://github.com/datex-labs/sidekick
+Project-URL: Repository, https://github.com/datex-labs/sidekick
+Project-URL: Bug Tracker, https://github.com/datex-labs/sidekick/issues
+Author-email: Datex <bbatchelder@datexcorp.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,llm,runtime,sidekick
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.11
+Requires-Dist: httpx-sse<0.5,>=0.4.0
+Requires-Dist: httpx<0.28,>=0.27.0
+Requires-Dist: pydantic<3.0,>=2.0.0
+Requires-Dist: rich<14.0,>=13.0
+Requires-Dist: websockets<15.0,>=14.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Sidekick Agent Runtime
+
+Portable agent execution engine for [Sidekick](https://github.com/datex/sidekick). Runs on user machines (laptops, VMs, self-hosted runners) and communicates with a Sidekick backend via HTTP and WebSocket.
+
+## Installation
+
+```bash
+pip install sidekick-agent-runtime
+```
+
+## Quick Start
+
+```bash
+sidekick serve --url https://sidekick.example.com --token <your-runner-token>
+```
+
+Or using environment variables:
+
+```bash
+export SIDEKICK_URL=https://sidekick.example.com
+export RUNNER_TOKEN=<your-runner-token>
+sidekick serve
+```
+
+## Configuration
+
+| Flag | Env Var | Default | Description |
+|------|---------|---------|-------------|
+| `--url` | `SIDEKICK_URL` | `http://localhost:8000` | Sidekick backend URL |
+| `--token` | `RUNNER_TOKEN` | *(required)* | Runner authentication token |
+| `--name` | `RUNNER_NAME` | hostname | Display name for this runner |
+| `--workspace` | `RUNNER_WORKSPACE` | `~/.sidekick/<name>/workspace` | Override working directory |
+| `--log-level` | `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
+| `--allow-insecure` | `SIDEKICK_ALLOW_INSECURE` | `false` | Allow unencrypted HTTP to non-localhost backends |
+| `--allow-env-passthrough` | `SIDEKICK_ALLOW_ENV_PASSTHROUGH` | `false` | Pass all server-provided env vars to CLI tools |
+
+> **Note:** The `--url` flag defaults to `http://localhost:8000` for local development.
+> In production, always set this to your Sidekick instance URL (e.g. `https://sidekick.example.com`).
+
+## How It Works
+
+The agent runtime connects to your Sidekick instance and executes agent turns:
+
+1. **Connects** via WebSocket for real-time notifications
+2. **Receives** turn assignments from Sidekick
+3. **Calls LLM** through Sidekick's proxy (SSE streaming)
+4. **Executes tools** locally (shell commands, file I/O) or remotely (via Sidekick)
+5. **Reports results** back to Sidekick
+
+## Local Tools
+
+The runtime can execute these tools directly on the host machine:
+
+- **RunCommand** — Execute shell commands
+- **ReadFile** — Read file contents
+- **WriteFile** — Write files
+- **ListFiles** — List directory contents
+- **CLI Tools** — Execute Python-based CLI tools defined in Sidekick
+
+## Requirements
+
+- Python 3.11+
+- A running [Sidekick](https://github.com/datex-labs/sidekick) backend instance
+- Network access from the runner to the Sidekick backend (HTTP + WebSocket)
+- A runner token (generated in Sidekick's admin UI)
+
+## Security Considerations
+
+The agent runtime **executes commands on behalf of the connected Sidekick backend**. Only connect to Sidekick instances you trust.
+
+Key security features:
+
+- **HTTPS enforced by default** — Connections to non-localhost backends over plain HTTP are blocked. Use `--allow-insecure` to override (not recommended).
+- **Sensitive env-var stripping** — Environment variables containing credentials, proxy settings, and path-injection vectors are stripped from CLI tool subprocesses by default. Use `--allow-env-passthrough` to override.
+- **Atomic credential writes** — Token cache (`~/.sidekick/credentials.json`) is written atomically with `0600` permissions.
+- **Token verification** — After browser-based authentication, the received token is verified against the backend before caching.
+
+See [SECURITY.md](SECURITY.md) for the full trust model and vulnerability reporting instructions.
+
+## Compatibility
+
+| Agent Runtime | Sidekick Backend |
+|---------------|------------------|
+| 0.1.x         | >= 0.1.0         |
+
+The runtime communicates via the `/api/runtime/v1` API. Breaking changes to this API will be reflected in the compatibility table above.
+
+## License
+
+MIT

sidekick_agent_cli-0.1.0/README.md

@@ -0,0 +1,90 @@
+# Sidekick Agent Runtime
+
+Portable agent execution engine for [Sidekick](https://github.com/datex/sidekick). Runs on user machines (laptops, VMs, self-hosted runners) and communicates with a Sidekick backend via HTTP and WebSocket.
+
+## Installation
+
+```bash
+pip install sidekick-agent-runtime
+```
+
+## Quick Start
+
+```bash
+sidekick serve --url https://sidekick.example.com --token <your-runner-token>
+```
+
+Or using environment variables:
+
+```bash
+export SIDEKICK_URL=https://sidekick.example.com
+export RUNNER_TOKEN=<your-runner-token>
+sidekick serve
+```
+
+## Configuration
+
+| Flag | Env Var | Default | Description |
+|------|---------|---------|-------------|
+| `--url` | `SIDEKICK_URL` | `http://localhost:8000` | Sidekick backend URL |
+| `--token` | `RUNNER_TOKEN` | *(required)* | Runner authentication token |
+| `--name` | `RUNNER_NAME` | hostname | Display name for this runner |
+| `--workspace` | `RUNNER_WORKSPACE` | `~/.sidekick/<name>/workspace` | Override working directory |
+| `--log-level` | `LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR) |
+| `--allow-insecure` | `SIDEKICK_ALLOW_INSECURE` | `false` | Allow unencrypted HTTP to non-localhost backends |
+| `--allow-env-passthrough` | `SIDEKICK_ALLOW_ENV_PASSTHROUGH` | `false` | Pass all server-provided env vars to CLI tools |
+
+> **Note:** The `--url` flag defaults to `http://localhost:8000` for local development.
+> In production, always set this to your Sidekick instance URL (e.g. `https://sidekick.example.com`).
+
+## How It Works
+
+The agent runtime connects to your Sidekick instance and executes agent turns:
+
+1. **Connects** via WebSocket for real-time notifications
+2. **Receives** turn assignments from Sidekick
+3. **Calls LLM** through Sidekick's proxy (SSE streaming)
+4. **Executes tools** locally (shell commands, file I/O) or remotely (via Sidekick)
+5. **Reports results** back to Sidekick
+
+## Local Tools
+
+The runtime can execute these tools directly on the host machine:
+
+- **RunCommand** — Execute shell commands
+- **ReadFile** — Read file contents
+- **WriteFile** — Write files
+- **ListFiles** — List directory contents
+- **CLI Tools** — Execute Python-based CLI tools defined in Sidekick
+
+## Requirements
+
+- Python 3.11+
+- A running [Sidekick](https://github.com/datex-labs/sidekick) backend instance
+- Network access from the runner to the Sidekick backend (HTTP + WebSocket)
+- A runner token (generated in Sidekick's admin UI)
+
+## Security Considerations
+
+The agent runtime **executes commands on behalf of the connected Sidekick backend**. Only connect to Sidekick instances you trust.
+
+Key security features:
+
+- **HTTPS enforced by default** — Connections to non-localhost backends over plain HTTP are blocked. Use `--allow-insecure` to override (not recommended).
+- **Sensitive env-var stripping** — Environment variables containing credentials, proxy settings, and path-injection vectors are stripped from CLI tool subprocesses by default. Use `--allow-env-passthrough` to override.
+- **Atomic credential writes** — Token cache (`~/.sidekick/credentials.json`) is written atomically with `0600` permissions.
+- **Token verification** — After browser-based authentication, the received token is verified against the backend before caching.
+
+See [SECURITY.md](SECURITY.md) for the full trust model and vulnerability reporting instructions.
+
+## Compatibility
+
+| Agent Runtime | Sidekick Backend |
+|---------------|------------------|
+| 0.1.x         | >= 0.1.0         |
+
+The runtime communicates via the `/api/runtime/v1` API. Breaking changes to this API will be reflected in the compatibility table above.
+
+## License
+
+MIT

sidekick_agent_cli-0.1.0/SECURITY.md

@@ -0,0 +1,43 @@
+# Security Policy
+
+## Reporting Vulnerabilities
+
+If you discover a security vulnerability in the Sidekick Agent Runtime, please report it responsibly:
+
+- **Email**: security@datexlabs.com
+- **Subject prefix**: `[sidekick-agent-runtime]`
+
+Please include:
+1. A description of the vulnerability
+2. Steps to reproduce
+3. Potential impact
+4. Suggested fix (if any)
+
+We will acknowledge receipt within 48 hours and aim to provide a fix or mitigation within 7 days for critical issues.
+
+## Scope
+
+The following are in scope for security reports:
+
+- Authentication bypass or token leakage
+- Arbitrary code execution beyond intended tool boundaries
+- Credential exposure via logs, environment, or filesystem
+- Man-in-the-middle vulnerabilities
+- Privilege escalation
+
+The following are **out of scope** (intentional design decisions):
+
+- **Package auto-install via `uvx`** (SEC-01): CLI tools are installed on demand. This is by design — the runtime trusts the connected Sidekick backend to provide valid tool definitions.
+- **Filesystem access** (SEC-03): Local tools (ReadFile, WriteFile, ListFiles, RunCommand) have full filesystem access within the runtime's working directory. Sandboxing is the responsibility of the deployment environment (VM, container, etc.).
+
+## Trust Model
+
+The Sidekick Agent Runtime operates under a **trusted server** model:
+
+1. **The runtime trusts the Sidekick backend it connects to.** It executes commands, installs packages, and accesses files as directed by the backend. Only connect to Sidekick instances you trust.
+
+2. **The backend authenticates the runtime** via runner tokens (for `serve` mode) or CLI tokens (for `chat` mode). Tokens are cached locally in `~/.sidekick/credentials.json` with `0600` permissions.
+
+3. **Transport security**: By default, the runtime refuses unencrypted HTTP connections to non-localhost backends. Use `--allow-insecure` to override (not recommended for production).
+
+4. **Environment isolation**: Sensitive environment variables (credentials, proxy settings, path manipulation) are stripped from CLI tool subprocesses by default. Use `--allow-env-passthrough` to override.

sidekick_agent_cli-0.1.0/pyproject.toml

@@ -0,0 +1,63 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "sidekick-agent-cli"
+version = "0.1.0"
+description = "CLI for the Sidekick Agent Orchestrator"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{name = "Datex", email = "bbatchelder@datexcorp.com"}]
+readme = "README.md"
+keywords = ["agent", "runtime", "llm", "sidekick"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+]
+dependencies = [
+    "httpx>=0.27.0,<0.28",
+    "httpx-sse>=0.4.0,<0.5",
+    "pydantic>=2.0.0,<3.0",
+    "rich>=13.0,<14.0",
+    "websockets>=14.0,<15.0",
+]
+
+[project.urls]
+"Homepage" = "https://github.com/datex-labs/sidekick"
+"Repository" = "https://github.com/datex-labs/sidekick"
+"Bug Tracker" = "https://github.com/datex-labs/sidekick/issues"
+
+[project.scripts]
+sidekick = "agent_runtime.cli:main"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.23",
+]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/agent_runtime"]
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+    ".claude/",
+    ".pytest_cache/",
+    ".venv/",
+    ".gitignore",
+    "publish.sh",
+    "tests/",
+    "uv.lock",
+]

sidekick_agent_cli-0.1.0/src/agent_runtime/__init__.py

@@ -0,0 +1,7 @@
+"""Agent Runtime — portable agent execution engine for Sidekick."""
+
+from .runtime import AgentRuntime
+from .api_client import RuntimeAPIClient
+from .display import RuntimeDisplay
+
+__all__ = ["AgentRuntime", "RuntimeAPIClient", "RuntimeDisplay"]

sidekick_agent_cli-0.1.0/src/agent_runtime/__main__.py

@@ -0,0 +1,4 @@
+"""Allow running as: python -m agent_runtime"""
+from .cli import main
+
+main()