runspec-console 0.1.0__tar.gz

runspec_console-0.1.0/.gitignore

@@ -0,0 +1,58 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json

runspec_console-0.1.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog — runspec-console
+
+All notable changes to this package are documented here.
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Version numbers follow [Semantic Versioning](https://semver.org/).
+
+---
+
+## [0.1.0] — 2026-05-27
+
+### Added
+
+- **runspec-console** — desktop GUI for runspec, packaged as a pip-installable wheel.
+  Ships a pywebview window hosting a Vite/React UI (the `console-ui` package built
+  and bundled at release time).
+- **Frameless window** with custom title bar: drag regions on sidebar and tab bar,
+  minimize / maximize-toggle / close controls (— □ ×).
+- **Hosts view** — displays connected and disconnected jump hosts; one-click SSH
+  connection test per host.
+- **Runnables view** — lists all runnables discovered on each host; shows group,
+  host, and autonomy level.
+- **Forms view** — per-runnable argument form with type-aware controls (text, number,
+  boolean toggle, choice dropdown), range validation, and positional-arg support.
+- **Console view** — live streaming output for in-flight invocations; collapsible
+  log blocks; truncation guard for large outputs.
+- **History view** — full invocation audit trail per host with arg provenance.
+- **Schedules view** — create, list, and delete cron-style scheduled invocations.
+- **Settings drawer** — jump-host config, SSH key generation and 90-day rotation
+  reminder, general preferences.
+- **Today summary** — at-a-glance counts of today's runs, failures, and upcoming
+  scheduled tasks.
+- **Built-in runnables** — `generate-ssh-key`, `disk-usage`, `ping-host`,
+  `flush-dns`, `check-port` shipped as console entry points.
+- **Chat integration** (optional extras `anthropic`, `openai`, `bedrock`) — natural-
+  language invocation via the slash menu.
+
+---

runspec_console-0.1.0/IMPL_NOTES.md

@@ -0,0 +1,143 @@
+# runspec-console — Implementation Notes
+
+Details worth capturing for documentation. Covers behaviour that isn't obvious
+from reading the code and that users / operators will ask about.
+
+---
+
+## Background refresh cycle
+
+All discovery and connectivity work runs in a daemon thread — the UI never blocks
+waiting for SSH. On app start a single background cycle begins immediately, then
+repeats every **30 seconds**.
+
+**Phase 1 — connectivity probes** (fast: `ssh -o ConnectTimeout=3 <host> true`)
+- One thread per remote host, run concurrently
+- Results written to `_connected_cache`; local is always True
+- Fires `runspec:hosts_updated` → App re-fetches host list (dot colours update)
+
+**Phase 2 — runnables discovery** (heavier: `runspec local --format json`)
+- One thread per host, run concurrently; unreachable hosts are skipped
+- Results written to `_runnables_cache`
+- Fires `runspec:runnables_updated` → App re-fetches runnable list
+
+`get_hosts()` and `get_runnables()` both read from cache and return instantly.
+On first render the runnable list is empty and dots are grey; both populate within
+a few seconds as the first cycle completes.
+
+A fresh cycle is also triggered immediately after `save_jump_hosts()` or
+`import_jump_hosts()` so newly added hosts appear without waiting 30 s.
+
+---
+
+## Host connectivity dots
+
+The coloured dot next to each host in the sidebar reflects a cached SSH probe result.
+
+- **Green** — last probe succeeded (`ssh -o ConnectTimeout=3 <host> true` exited 0)
+- **Grey** — not yet probed, or last probe failed / timed out
+- **Local host** — always green (no probe needed)
+
+**Refresh cadence:** probes run concurrently (one thread per remote host) immediately
+on app start, then every **30 seconds** in a background daemon thread. The UI dot
+updates automatically when each round completes via a `runspec:hosts_updated` event.
+
+**First load behaviour:** hosts appear grey on the initial render (cache is empty).
+Dots flip to green a few seconds later once the first probe round finishes. This is
+intentional — `get_hosts()` returns instantly rather than blocking for SSH round-trips.
+
+---
+
+## Streaming (invoke_runnable)
+
+Output from a runnable is streamed line-by-line from a background thread back to
+the frontend via `window.evaluate_js(CustomEvent)`. Two events:
+
+- `runspec:output  { id, line, stream }` — one stdout/stderr line
+- `runspec:run_end { id, exit_code, duration_ms }` — invocation complete
+
+Both local and SSH-remote runnables use the same streaming path (`executor.py`).
+For SSH, the subprocess is `ssh -o BatchMode=yes <host> <remote_runspec_path> [args]`.
+
+**No stdin support** — `BatchMode=yes` is set and the subprocess has no stdin pipe.
+Scripts that prompt for confirmation will stall and time out.
+
+---
+
+## Chat / LLM (agentic loop)
+
+`send_chat` always runs `_agentic_chat_turn`, which loops up to **10 iterations**:
+
+1. Call `adapter.stream_with_tools(history, tools)` — yields `('text', token)` then
+   `('done', ChatResponse)`.
+2. Dispatch each `token` as `runspec:token`. On `('done', ...)`, inspect `stop_reason`.
+3. If `stop_reason == 'tool_use'`, run each `ToolCall` via `asyncio.to_thread(_run_tool_sync)`,
+   dispatch `runspec:tool_start` / `runspec:tool_end`, build the tool-result turns,
+   extend `history`, and loop.
+4. Otherwise break — model is done.
+
+**Streaming implementation by adapter:**
+- **Anthropic / Bedrock** — `stream_with_tools()` iterates raw SSE events from the SDK
+  stream (`async for event in stream`). Text deltas yield tokens; `input_json_delta`
+  events accumulate JSON strings per block index. `get_final_message()` is called after
+  the loop to get the `Message` object needed by `make_tool_turn`.
+- **OpenAI** — falls back to `chat()` (non-streaming). Streaming + tool call delta
+  accumulation is complex; non-streaming is correct for tool turns.
+
+**Tool schemas** — `_runnables_to_tools()` converts the `_runnables_cache` to
+Anthropic-format `input_schema` tool definitions. Tool name: `{host}__{runnable}`,
+sanitised to `[a-zA-Z0-9_-]` and truncated to 64 chars. OpenAI adapter converts
+`input_schema` → `parameters` via `_to_openai_function()`.
+
+**`_run_tool_sync`** is blocking — safe because it's called via `asyncio.to_thread()`.
+Calls `run_local` / `run_remote` directly (they block). Output capped at **16 KB**;
+non-zero exit codes prepend `[exit N]` to the output string.
+
+**Tool output cap** — tool results sent to the LLM are truncated at 2 000 chars in the
+`runspec:tool_end` event (for the UI); the full ≤16 KB goes into `make_tool_turn`.
+
+**Frontend rendering** — `InvocationBlock` for chat blocks uses `segments: BlockSegment[]`
+(interleaved `{ kind: 'text', text }` and `{ kind: 'tool', entry: ToolCallEntry }`) plus
+`currentText: string` for the currently-streaming text. When `runspec:tool_start` fires,
+`currentText` is flushed to a text segment and a running tool entry is appended.
+`runspec:tool_end` marks the entry complete (output stored, `running: false`). `runspec:run_end`
+flushes any remaining `currentText` and sets `done: true`. Tool call blocks in the UI show
+the runnable name (host prefix stripped), args inline, and a collapsible output section.
+
+**Provider config** lives in `%APPDATA%\runspec-console\runspec_config.toml` under `[llm]`:
+  - `provider` — `"anthropic"` | `"openai"` | `"bedrock"`
+  - `api_key` — for Anthropic/OpenAI; or Bedrock proxy token
+  - `model` — defaults: `claude-sonnet-4-6`, `gpt-4o`, `anthropic.claude-sonnet-4-6`
+  - `base_url` — optional; for OpenAI-compatible endpoints or Bedrock corporate proxy
+  - `aws_region` — Bedrock only
+- Configurable in-app via Settings → General. Provider dropdown shows relevant fields
+  only (e.g. AWS Region only appears for Bedrock).
+
+---
+
+## Production build
+
+Only `--dev` mode is wired up (pywebview connects to Vite dev server on port 5173).
+`npm run build` → embedded `dist/` path is not yet configured in `app.py`. Running
+without `--dev` will show a blank window.
+
+---
+
+## Schedules
+
+Stored at `%APPDATA%\runspec-console\runspec_schedules.toml` as a TOML array of
+`[[schedule]]` entries. No scheduler process exists yet — schedules are persisted
+but nothing executes them. `nextRun` is always blank (`—`) until a scheduler is
+implemented. Marked as a **server-side / central git repo** feature for a later pass.
+
+---
+
+## File locations (Windows)
+
+| File | Path |
+|------|------|
+| Hosts config | `%APPDATA%\runspec-console\runspec_hosts.toml` |
+| App config (LLM / SSH defaults) | `%APPDATA%\runspec-console\runspec_config.toml` |
+| Schedules | `%APPDATA%\runspec-console\runspec_schedules.toml` |
+| Local venv logs | `{venv_root}\logs\{runnable}.log` |
+| Remote logs | fetched via one-shot SSH cat on demand |

runspec_console-0.1.0/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.4
+Name: runspec-console
+Version: 0.1.0
+Requires-Python: >=3.11
+Requires-Dist: pywebview>=5.0
+Requires-Dist: pywin32>=306
+Requires-Dist: runspec>=0.18.0
+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: dev
+Requires-Dist: mypy; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0.0; extra == 'openai'

runspec_console-0.1.0/dev_build.py

@@ -0,0 +1,48 @@
+#!/usr/bin/env python3
+"""Build runspec-console wheel.
+
+Steps:
+  1. npm run build  — Vite bundles the UI into runspec_console/dist/
+  2. python -m build — hatchling packages the wheel (force-includes dist/)
+
+Run from any directory:
+    python packages/python/runspec-console/build.py
+"""
+import subprocess
+import sys
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent.parent.parent  # repo root
+CONSOLE_UI = ROOT / "packages" / "console-ui"
+PYTHON_PKG = ROOT / "packages" / "python" / "runspec-console"
+
+
+def run(cmd: list[str], cwd: Path, *, shell: bool = False) -> None:
+    display = " ".join(cmd)
+    print(f"\n>>> {display}  (in {cwd.relative_to(ROOT)})")
+    result = subprocess.run(cmd, cwd=cwd, shell=shell)
+    if result.returncode != 0:
+        sys.exit(result.returncode)
+
+
+def main() -> None:
+    # On Windows, npm is npm.cmd — use shell=True so PATH resolution works
+    is_windows = sys.platform == "win32"
+    npm = ["npm.cmd", "run", "build"] if is_windows else ["npm", "run", "build"]
+
+    run(npm, CONSOLE_UI, shell=is_windows)
+
+    dist_dir = PYTHON_PKG / "runspec_console" / "dist"
+    if not dist_dir.exists():
+        print(f"ERROR: Vite output not found at {dist_dir}", file=sys.stderr)
+        sys.exit(1)
+
+    run([sys.executable, "-m", "build"], PYTHON_PKG)
+
+    wheels = list((PYTHON_PKG / "dist").glob("*.whl"))
+    if wheels:
+        print(f"\nWheel ready: {wheels[-1].name}")
+
+
+if __name__ == "__main__":
+    main()

runspec_console-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-console"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "pywebview>=5.0",
+    "runspec>=0.18.0",
+    "pywin32>=306",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["runspec_console"]
+
+[tool.hatch.build.targets.wheel.force-include]
+"runspec_console/runspec.toml" = "runspec_console/runspec.toml"
+# Vite build output — generated by `npm run build` in packages/console-ui
+# gitignored but force-included so `pip install` gets the full UI
+"runspec_console/dist" = "runspec_console/dist"
+
+[project.scripts]
+runspec-console = "runspec_console.app:main"
+disk-usage      = "runspec_console.tools.disk_usage:main"
+ping-host       = "runspec_console.tools.ping_host:main"
+flush-dns       = "runspec_console.tools.flush_dns:main"
+check-port      = "runspec_console.tools.check_port:main"
+generate-ssh-key = "runspec_console.tools.generate_ssh_key:main"
+
+[project.optional-dependencies]
+anthropic = ["anthropic>=0.40.0"]
+openai    = ["openai>=1.0.0"]
+bedrock   = ["anthropic[bedrock]>=0.40.0"]
+dev = [
+    "ruff",
+    "mypy",
+    "pytest>=8.0",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "../runspec"

runspec_console-0.1.0/runspec_console/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

runspec_console-0.1.0/runspec_console/adapters/anthropic.py

@@ -0,0 +1,117 @@
+"""pip install runspec-console[anthropic]"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import anthropic
+
+from .base import ChatResponse, ModelAdapter, ToolCall
+
+DEFAULT_MODEL = "claude-sonnet-4-6"
+DEFAULT_SYSTEM = (
+    "You are a helpful assistant with access to runspec tools running on local and remote hosts. "
+    "Use tools when they help answer the user's request. "
+    "When you call a tool, briefly explain what you're doing before the result."
+)
+
+
+class AnthropicAdapter(ModelAdapter):
+    def __init__(
+        self,
+        model: str = DEFAULT_MODEL,
+        system: str = DEFAULT_SYSTEM,
+        api_key: str | None = None,
+    ) -> None:
+        self.client = anthropic.AsyncAnthropic(api_key=api_key)
+        self.model = model
+        self.system = system
+
+    async def chat(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]]) -> ChatResponse:
+        kwargs: dict[str, Any] = dict(
+            model=self.model,
+            max_tokens=4096,
+            messages=messages,
+            system=self.system,
+        )
+        if tools:
+            kwargs["tools"] = tools
+        response = await self.client.messages.create(**kwargs)
+        text = next(
+            (block.text for block in response.content if hasattr(block, "text")), None
+        )
+        tool_calls = [
+            ToolCall(id=block.id, name=block.name, input=block.input)
+            for block in response.content
+            if block.type == "tool_use"
+        ]
+        return ChatResponse(text=text, tool_calls=tool_calls, stop_reason=response.stop_reason, _raw=response)
+
+    async def stream_chat(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]]):  # type: ignore[override]
+        kwargs: dict[str, Any] = dict(
+            model=self.model,
+            max_tokens=4096,
+            messages=messages,
+            system=self.system,
+        )
+        if tools:
+            kwargs["tools"] = tools
+        async with self.client.messages.stream(**kwargs) as stream:
+            async for token in stream.text_stream:
+                yield token
+
+    async def stream_with_tools(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]]):  # type: ignore[override]
+        import json
+        kwargs: dict[str, Any] = dict(
+            model=self.model,
+            max_tokens=4096,
+            messages=messages,
+            system=self.system,
+        )
+        if tools:
+            kwargs["tools"] = tools
+        # Collect tool input JSON chunks indexed by content-block position
+        tool_map: dict[int, dict[str, Any]] = {}
+        stop_reason = "end_turn"
+        async with self.client.messages.stream(**kwargs) as stream:
+            async for event in stream:
+                ev_type = getattr(event, "type", None)
+                if ev_type == "content_block_start":
+                    cb = getattr(event, "content_block", None)
+                    if cb and getattr(cb, "type", None) == "tool_use":
+                        tool_map[event.index] = {"id": cb.id, "name": cb.name, "json": ""}
+                elif ev_type == "content_block_delta":
+                    d = getattr(event, "delta", None)
+                    if d:
+                        if getattr(d, "type", None) == "text_delta":
+                            yield ("text", d.text)
+                        elif getattr(d, "type", None) == "input_json_delta":
+                            if event.index in tool_map:
+                                tool_map[event.index]["json"] += d.partial_json
+                elif ev_type == "message_delta":
+                    d = getattr(event, "delta", None)
+                    if d:
+                        stop_reason = getattr(d, "stop_reason", stop_reason) or stop_reason
+            final = await stream.get_final_message()
+        tool_calls = []
+        for tc in tool_map.values():
+            try:
+                inp = json.loads(tc["json"]) if tc["json"] else {}
+            except Exception:
+                inp = {}
+            tool_calls.append(ToolCall(id=tc["id"], name=tc["name"], input=inp))
+        yield ("done", ChatResponse(text=None, tool_calls=tool_calls, stop_reason=stop_reason, _raw=final))
+
+    def make_tool_turn(
+        self, response: ChatResponse, results: list[tuple[ToolCall, str]]
+    ) -> list[dict[str, Any]]:
+        return [
+            {"role": "assistant", "content": response._raw.content},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "tool_result", "tool_use_id": tc.id, "content": result}
+                    for tc, result in results
+                ],
+            },
+        ]

runspec_console-0.1.0/runspec_console/adapters/base.py

@@ -0,0 +1,92 @@
+"""
+base.py — ModelAdapter ABC shared across all LLM providers.
+
+Identical contract to runspec-chat's adapter.py so implementations
+can be ported between the two packages without changes.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, AsyncIterator
+
+
+@dataclass
+class ToolCall:
+    id: str
+    name: str
+    input: dict[str, Any]
+
+
+@dataclass
+class ChatResponse:
+    text: str | None
+    tool_calls: list[ToolCall]
+    stop_reason: str   # "tool_use" | "end_turn" | "stop"
+    _raw: Any = field(repr=False, default=None)
+
+
+class ModelAdapter(ABC):
+    @abstractmethod
+    async def chat(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]]) -> ChatResponse: ...
+
+    @abstractmethod
+    def stream_chat(self, messages: list[dict[str, Any]], tools: list[dict[str, Any]]) -> AsyncIterator[str]:
+        """Yield text tokens as they arrive from the model."""
+        ...
+
+    async def stream_with_tools(
+        self, messages: list[dict[str, Any]], tools: list[dict[str, Any]]
+    ):
+        """
+        Yield ('text', str) for each text token, then ('done', ChatResponse) at the end.
+
+        Default falls back to non-streaming chat(). Override for true streaming with tools.
+        """
+        response = await self.chat(messages, tools)
+        if response.text:
+            yield ("text", response.text)
+        yield ("done", response)
+
+    @abstractmethod
+    def make_tool_turn(
+        self, response: ChatResponse, results: list[tuple[ToolCall, str]]
+    ) -> list[dict[str, Any]]:
+        """Return [assistant_turn, tool_result_turn] to append to the conversation."""
+        ...
+
+
+def load_adapter(provider: str, **kwargs: Any) -> ModelAdapter:
+    """
+    Instantiate the named adapter.  Raises ImportError with install instructions
+    if the required extra is not installed.
+
+    provider: "anthropic" | "openai" | "bedrock"
+    kwargs:   passed straight through to the adapter __init__
+    """
+    if provider == "anthropic":
+        try:
+            from .anthropic import AnthropicAdapter
+            return AnthropicAdapter(**kwargs)
+        except ImportError:
+            raise ImportError(
+                "Install the Anthropic extra: pip install runspec-console[anthropic]"
+            )
+    if provider == "openai":
+        try:
+            from .openai import OpenAIAdapter
+            return OpenAIAdapter(**kwargs)
+        except ImportError:
+            raise ImportError(
+                "Install the OpenAI extra: pip install runspec-console[openai]"
+            )
+    if provider == "bedrock":
+        try:
+            from .bedrock import BedrockAdapter
+            return BedrockAdapter(**kwargs)
+        except ImportError:
+            raise ImportError(
+                "Install the Bedrock extra: pip install runspec-console[bedrock]"
+            )
+    raise ValueError(f"Unknown LLM provider: {provider!r}. Choose from: anthropic, openai, bedrock")