Metadata-Version: 2.5
Name: runspec-console
Version: 0.412.0
Summary: Desktop console for runspec runnables: run, schedule and monitor them locally and across an SSH fleet, with an optional AI agent
Project-URL: Homepage, https://runspec.app
Project-URL: Documentation, https://runspec.app/console-quickstart/
Project-URL: Repository, https://github.com/runspec-app/runspec
Project-URL: Issues, https://github.com/runspec-app/runspec/issues
Project-URL: Changelog, https://github.com/runspec-app/runspec/blob/main/packages/python/runspec-console/CHANGELOG.md
License-Expression: MIT
Requires-Python: >=3.11
Requires-Dist: cryptography>=42.0
Requires-Dist: paramiko>=3.0
Requires-Dist: pywebview>=5.0
Requires-Dist: pywin32>=306; sys_platform == 'win32'
Requires-Dist: runspec>=0.79.0
Requires-Dist: tomli-w>=1.0
Provides-Extra: all
Requires-Dist: anthropic>=0.40.0; extra == 'all'
Requires-Dist: anthropic[bedrock]>=0.40.0; extra == 'all'
Requires-Dist: apscheduler>=3.10; extra == 'all'
Requires-Dist: dulwich>=0.22; extra == 'all'
Requires-Dist: httpx>=0.27; extra == 'all'
Requires-Dist: keyring>=24; extra == 'all'
Requires-Dist: mcp<3,>=2; extra == 'all'
Requires-Dist: moonshine-voice>=0.1.5; extra == 'all'
Requires-Dist: openai>=1.0.0; extra == 'all'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'all'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'all'
Requires-Dist: winrt-runtime>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-applicationmodel>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-data-xml-dom>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-foundation-collections>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-foundation>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-ui-notifications-management>=2.0; (sys_platform == 'win32') and extra == 'all'
Requires-Dist: winrt-windows-ui-notifications>=2.0; (sys_platform == 'win32') and extra == 'all'
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.40.0; extra == 'anthropic'
Provides-Extra: bedrock
Requires-Dist: anthropic[bedrock]>=0.40.0; extra == 'bedrock'
Provides-Extra: credentials
Requires-Dist: keyring>=24; extra == 'credentials'
Provides-Extra: dev
Requires-Dist: apscheduler>=3.10; extra == 'dev'
Requires-Dist: dulwich>=0.22; extra == 'dev'
Requires-Dist: httpx>=0.27; extra == 'dev'
Requires-Dist: mcp<3,>=2; extra == 'dev'
Requires-Dist: mypy; extra == 'dev'
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'dev'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff==0.15.20; extra == 'dev'
Provides-Extra: git-sync
Requires-Dist: dulwich>=0.22; extra == 'git-sync'
Provides-Extra: langserve
Requires-Dist: httpx>=0.27; extra == 'langserve'
Provides-Extra: mcp
Requires-Dist: mcp<3,>=2; extra == 'mcp'
Provides-Extra: notifications
Requires-Dist: winrt-runtime>=2.0; (sys_platform == 'win32') and extra == 'notifications'
Requires-Dist: winrt-windows-applicationmodel>=2.0; (sys_platform == 'win32') and extra == 'notifications'
Requires-Dist: winrt-windows-data-xml-dom>=2.0; (sys_platform == 'win32') and extra == 'notifications'
Requires-Dist: winrt-windows-foundation-collections>=2.0; (sys_platform == 'win32') and extra == 'notifications'
Requires-Dist: winrt-windows-foundation>=2.0; (sys_platform == 'win32') and extra == 'notifications'
Requires-Dist: winrt-windows-ui-notifications-management>=2.0; (sys_platform == 'win32') and extra == 'notifications'
Requires-Dist: winrt-windows-ui-notifications>=2.0; (sys_platform == 'win32') and extra == 'notifications'
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == 'openai'
Provides-Extra: otel
Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.27; extra == 'otel'
Requires-Dist: opentelemetry-sdk>=1.27; extra == 'otel'
Provides-Extra: sandbox
Requires-Dist: wasmtime>=20; extra == 'sandbox'
Provides-Extra: schedule
Requires-Dist: apscheduler>=3.10; extra == 'schedule'
Provides-Extra: voice
Requires-Dist: moonshine-voice>=0.1.5; extra == 'voice'
Provides-Extra: windows
Requires-Dist: runspec-windows>=0.5.0; (sys_platform == 'win32') and extra == 'windows'
Description-Content-Type: text/markdown

# runspec-console

A desktop console for [runspec](https://pypi.org/project/runspec/) — run,
schedule, and monitor runnables from a graphical UI. Built on
[pywebview](https://pywebview.flowrl.com/) with a Vite/React frontend, it
discovers every runnable installed in its environment (via `runspec local`) and
can also reach runnables on remote hosts over SSH.

## Install

```
pip install runspec-console              # add [windows] on Windows for the runnable pack
runspec-console
```

On **Windows**, `pip install "runspec-console[windows]"` also installs
[`runspec-windows`](https://pypi.org/project/runspec-windows/), so its Windows
system-administration and cross-platform web/TLS runnables appear in the UI. The
extra is gated to `sys_platform == "win32"`, so it's a no-op on macOS/Linux, and
it's not part of `[all]`. It's an extra rather than a dependency so a white-label
console can ship a rebranded copy instead (see the runspec docs, "White-label
runnable packages"). The Microsoft 365 runnables are **not** pulled in
automatically — see below.

To add more runnables, just `pip install` the package that provides them into
the same environment (e.g. `runspec-linux`) — the console picks them up on the
next launch.

## Where runnables come from

The console lists whatever `runspec local` can discover: any installed package
that ships a `runspec.toml` and entry points. There's no registry and no
filesystem scanning — `pip install` (or `pip install -e .`) is how a runnable
becomes visible.

## Microsoft 365 runnables (Outlook · Teams · Calendar · OneDrive)

These live in the separate [`runspec-o365`](https://pypi.org/project/runspec-o365/)
package (they used to ship in `runspec-windows`, but the console no longer pulls
them in — so a Graph-blocked deployment isn't cluttered with unusable tools).
**Opt in with `pip install runspec-o365`** into the console's environment, then
restart. They authenticate as the signed-in user via the Microsoft Graph
**device-code** flow (no client secret). The full setup lives in the
[runspec-o365 README](https://pypi.org/project/runspec-o365/); the short version:

1. **Register an app** in your Entra (Azure AD) tenant
   (*App registrations → New registration*).
2. **Authentication → "Allow public client flows" → Yes** — device-code login
   needs this.
3. **API permissions → Microsoft Graph → Delegated**: add `User.Read`,
   `Mail.Read`, `Chat.Read`, `Calendars.Read`, `Files.Read.All`, then grant
   consent.
4. Copy the **Application (client) ID** and **Directory (tenant) ID**.
5. Drop them in `%APPDATA%\runspec-o365\graph.toml` (the client id is not a
   secret):

   ```toml
   client_id = "00000000-0000-0000-0000-000000000000"
   tenant    = "yourcompany.onmicrosoft.com"
   ```

   For a **personal** Microsoft account (e.g. trying it at home), register the
   app for "personal Microsoft accounts" and set `tenant = "consumers"` (or
   `"common"`) instead of a tenant domain.
6. Run `graph-login` once (it prints a URL + code to authenticate); the token
   caches and refreshes silently thereafter.

> **In a managed tenant:** `Chat.Read` (Teams) is typically **admin-consent-required**, so a
> tenant admin may need to grant consent on the app registration. The
> mail/calendar/files scopes are usually user-consentable.

## AI assistant (optional)

The console can drive runnables through an LLM. Install the provider extra you
want:

```
pip install "runspec-console[anthropic]"   # Claude
pip install "runspec-console[openai]"      # OpenAI
pip install "runspec-console[bedrock]"     # Claude via AWS Bedrock
pip install "runspec-console[langserve]"   # corporate LLM gateway (LangServe /invoke)
```

### LangServe gateway (no Anthropic/OpenAI account)

If your only model access is a corporate **LLM gateway** that exposes a
LangServe `/invoke` route (commonly Bedrock/Claude underneath), pick the
`langserve` provider. Configure it in Settings → LLM, or hand-edit
`%APPDATA%\runspec-console\config.toml`:

```toml
[llm]
provider = "langserve"
base_url = "https://gateway.corp/my-chain"   # /invoke is appended automatically
model    = ""                                 # the published chain usually pins its model
# Static token:
api_key  = "..."
# …or a short-lived token re-fetched on a TTL (rotating corporate creds):
# api_key_command = "aws-vend-token --print"
# api_key_ttl_ms  = 300000
```

Tool calling is structured — runspec tools are sent to the gateway and the
model's tool calls are executed exactly as with the native providers. The two
parts that vary per-gateway are knobs under `[llm]`, adjustable once you've seen
the endpoint's `GET /input_schema`:

| key | default | meaning |
|---|---|---|
| `input_messages_key` | `"messages"` | key the chat history is sent under, inside `input` |
| `input_tools_key` | `"tools"` | key the tool schemas are sent under |
| `tools_in_config` | `false` | when `true`, tools move to `config.configurable.<key>` instead of `input` |
| `auth_header` | `"Authorization"` | header the token is sent in |
| `auth_scheme` | `"Bearer"` | scheme prefix; set to `""` to send the raw token |

### Agent tool list (`tool_mode`)

The assistant turns each fleet runnable into an LLM tool. On a uniform fleet —
many hosts running the same package set — the default **`tool_mode = "dedup"`**
sends **one tool per folder/runnable** (named `group__runnable`) with a required
`host` enum listing the hosts that have it, instead of one tool per
host×runnable. This keeps the tool list — re-sent on every turn — small (an
18-host × 20-runnable fleet: 20 tools instead of 360). The agent names the host
as an argument.

Set it in **Settings → LLM → Tool list mode**, or in the config file:

```toml
[llm]
tool_mode = "dedup"      # default — collapse identical per-host tools
# tool_mode = "per_host" # one tool per host__runnable (the original layout)
# tool_mode = "search"   # discovery meta-tools only (best for large, multi-package fleets)
```

Use `"per_host"` if you'd rather the host be encoded in the tool name than chosen
as an argument.

**`"search"`** goes further for fleets that install *many distinct* runnables
(several packages = 70–100+ tools): instead of listing every runnable, it exposes
three fixed meta-tools — `search_runnables` (find by keyword; returns typed argument
rows), `run_runnable` (execute by id + host, with arguments validated *before*
dispatch), and `describe_runnable` (full schema on demand). The per-turn tool block
stays ~3 tools regardless of fleet size. Same autonomy gate, credentials, and
secret handling as the other modes. Agent-mode triggers (which scope to a curated
allowlist) keep the `dedup` layout automatically.

So the agent still knows *what exists* without paying for every schema, search mode
also folds a compact **catalog index** into each turn — one line per runnable
(`id — first sentence of its description`, no arguments). The agent reads the menu,
then calls `search_runnables`/`describe_runnable` for the details of the one it
wants. The index is bounded by `[llm] tool_index_limit` (default 300, with an
overflow note) and can be turned off with `[llm] tool_index = false`. Tip: lead each
runnable's description with its distinguishing detail — that first sentence is what
the agent scans.

### Custom providers (plugins)

When a model gateway is proprietary and its adapter must stay in a **private**
repo, ship it as a plugin instead of forking the console. A plugin implements
`runspec_console.ModelAdapter` (dependency-free, so no SDKs leak in) and is
resolved under a `[llm] provider` name three ways:

- **Entry point** (recommended) — your wheel advertises the
  `runspec_console.adapters` group; `pip install` it and the provider appears
  (selectable in Settings → LLM).
- **`register_adapter(name, factory)`** — call it from a module imported at
  startup via `[plugins] modules = ["your_pkg"]`.
- **Dotted path** — `provider = "your_pkg.module:AdapterClass"`, no packaging.

A "LangServe-ish but not vanilla" gateway can subclass `LangServeAdapter` and
override only `_build_payload` / `_parse_output`. See
[`examples/console-adapter-plugin/`](https://github.com/runspec-app/runspec/tree/main/packages/python/runspec-console/examples/console-adapter-plugin) for a
ready-to-copy template — it includes an `AGENTS.md` brief and a Copilot prompt
file for building the adapter with an AI agent, and conformance helpers
(`runspec_console.adapters.testing`) to validate it without a live gateway.

## Usage

```
runspec-console              # production (bundled UI)
runspec-console --dev        # point pywebview at a running Vite dev server
runspec-console --devtools   # enable the Chromium inspector in a prod build
```

## Version & documentation

The installed version is shown at the bottom of the host sidebar. On launch the
console checks for a newer release by asking `pip` — running from the very venv
runspec-console is installed in — what the newest available version is. Going
through that venv's `pip` means the check honours its index configuration: an
**internal PyPI proxy / mirror** is queried instead of public PyPI when the venv
is pointed at one. It's best-effort — a blocked or offline network (or missing
pip) simply shows the version with no update indicator; when a newer release
exists, an `↑ <version>` chip appears next to it. The toolbar's docs icon (top
right) opens the documentation site in your browser.

The docs target defaults to <https://runspec.app/> and is
overridable per-install in `%APPDATA%\runspec-console\config.toml`:

```toml
[console]
docs_url = "https://docs.internal.corp/runspec/"
```

See the main [runspec docs](https://github.com/runspec-app/runspec) for the
runspec format, the SSH jump-host model, and logging.
