webbee 0.1.0__tar.gz

webbee-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,28 @@
+name: publish
+
+# Publish to PyPI on a version tag (e.g. `v0.1.0`), matching the Imperal
+# convention (imperal-mcp). Auth uses the account API token stored as the
+# GitHub Actions secret `PYPI_API_TOKEN` — add it to this repo, or set an
+# `imperalcloud` org-level secret so every package inherits it. The token is
+# NEVER stored in the repo/files; only in the encrypted Actions secret.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Build sdist + wheel
+        run: |
+          python -m pip install --upgrade build
+          python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          password: ${{ secrets.PYPI_API_TOKEN }}

webbee-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.venv/
+venv/
+build/
+dist/
+.DS_Store

webbee-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0
+
+First public release.
+
+- `webbee` — a coding agent in your terminal: reads, writes, and runs code in
+  the current directory; the brain runs in the Imperal Cloud on ICNLI. No model
+  keys on the machine.
+- Full-screen dock: a scrollable, colored output pane with the input box and
+  toolbar pinned at the bottom.
+- Consent modes — **default** (asks before anything it can't undo), **plan**
+  (read-only), **autopilot** (acts without asking); cycle with **Shift + TAB**.
+  Spending money always needs a browser approval.
+- Reaches your connected Imperal apps (mail, notes, tasks, …) alongside the
+  local code tools.
+- Slash commands: `/login` `/logout` `/mode` `/cost` `/status` `/clear` `/exit`.
+- Live token/cost meter (session total) and update check.

webbee-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Imperal, Inc.
+
+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.

webbee-0.1.0/PKG-INFO

@@ -0,0 +1,86 @@
+Metadata-Version: 2.4
+Name: webbee
+Version: 0.1.0
+Summary: Webbee 🐝 — the Imperal Cloud coding agent in your terminal
+Project-URL: Homepage, https://imperal.io
+Project-URL: Documentation, https://docs.imperal.io
+Project-URL: Repository, https://github.com/imperalcloud/webbee-code
+Project-URL: Issues, https://github.com/imperalcloud/webbee-code/issues
+Project-URL: Protocol, https://icnli.org
+Author-email: "Imperal, Inc." <hello@imperal.io>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,cli,coding-agent,icnli,imperal,llm,terminal,webbee
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+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
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: httpx-sse>=0.4
+Requires-Dist: httpx>=0.27
+Requires-Dist: imperal-mcp>=0.4.0
+Requires-Dist: imperal-sdk>=5.9.2
+Requires-Dist: prompt-toolkit>=3
+Requires-Dist: rich>=13.7
+Description-Content-Type: text/markdown
+
+# Webbee 🐝 — the coding agent in your terminal
+
+[![PyPI](https://img.shields.io/pypi/v/webbee.svg)](https://pypi.org/project/webbee/)
+[![Python](https://img.shields.io/pypi/pyversions/webbee.svg)](https://pypi.org/project/webbee/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-imperal.io-00afd7.svg)](https://docs.imperal.io)
+
+Webbee is the [Imperal Cloud](https://imperal.io) coding agent, in your terminal. It reads, writes, and runs code in your working directory — while the brain runs in the cloud on **ICNLI**, the open protocol behind Webbee. No model keys on your machine. Swap the model underneath and it behaves the same, because the safety was never in the model.
+
+**The model proposes. The kernel decides. The key — delete, drop, wipe — stays with you.**
+
+## Install
+
+```sh
+pipx install webbee          # or:  uv tool install webbee
+```
+
+No Python on the box? One line:
+
+```sh
+curl -LsSf https://webbee.imperal.io/install.sh | sh
+```
+
+## Use
+
+```sh
+webbee            # start the agent in the current directory
+webbee login      # sign in to your Imperal account (opens the browser)
+```
+
+Type in plain English. Webbee reads your files, runs commands, and reaches your connected Imperal apps — mail, notes, tasks, and more — to get the job done. `/help` lists the commands: `/login` `/logout` `/mode` `/cost` `/status` `/clear` `/exit`.
+
+## Modes — you hold the key
+
+Cycle with **Shift + TAB**:
+
+- **default** — Webbee does the small, reversible stuff herself. Anything she can't undo, she stops and asks you first.
+- **plan** — read-only. She plans and reads; she touches nothing.
+- **autopilot** — she acts without asking. (Spending money always needs a browser approval — no terminal reply can release it.)
+
+## How it works
+
+Your machine runs the hands — read, write, edit, run. The brain runs in the Imperal Cloud and reasons over your files, your history, and your connected apps through ICNLI. The model is a replaceable proposer at the edge; the kernel resolves, grounds, and decides. Webbee reads your facts. She doesn't invent them.
+
+## Links
+
+- **Imperal Cloud** — [imperal.io](https://imperal.io)
+- **Docs** — [docs.imperal.io](https://docs.imperal.io)
+- **ICNLI** — the open protocol, CC BY-SA 4.0 — [icnli.org](https://icnli.org)
+- **More from Imperal** — [github.com/imperalcloud](https://github.com/imperalcloud)
+
+---
+
+MIT © Imperal, Inc.

webbee-0.1.0/README.md

@@ -0,0 +1,54 @@
+# Webbee 🐝 — the coding agent in your terminal
+
+[![PyPI](https://img.shields.io/pypi/v/webbee.svg)](https://pypi.org/project/webbee/)
+[![Python](https://img.shields.io/pypi/pyversions/webbee.svg)](https://pypi.org/project/webbee/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
+[![Docs](https://img.shields.io/badge/docs-imperal.io-00afd7.svg)](https://docs.imperal.io)
+
+Webbee is the [Imperal Cloud](https://imperal.io) coding agent, in your terminal. It reads, writes, and runs code in your working directory — while the brain runs in the cloud on **ICNLI**, the open protocol behind Webbee. No model keys on your machine. Swap the model underneath and it behaves the same, because the safety was never in the model.
+
+**The model proposes. The kernel decides. The key — delete, drop, wipe — stays with you.**
+
+## Install
+
+```sh
+pipx install webbee          # or:  uv tool install webbee
+```
+
+No Python on the box? One line:
+
+```sh
+curl -LsSf https://webbee.imperal.io/install.sh | sh
+```
+
+## Use
+
+```sh
+webbee            # start the agent in the current directory
+webbee login      # sign in to your Imperal account (opens the browser)
+```
+
+Type in plain English. Webbee reads your files, runs commands, and reaches your connected Imperal apps — mail, notes, tasks, and more — to get the job done. `/help` lists the commands: `/login` `/logout` `/mode` `/cost` `/status` `/clear` `/exit`.
+
+## Modes — you hold the key
+
+Cycle with **Shift + TAB**:
+
+- **default** — Webbee does the small, reversible stuff herself. Anything she can't undo, she stops and asks you first.
+- **plan** — read-only. She plans and reads; she touches nothing.
+- **autopilot** — she acts without asking. (Spending money always needs a browser approval — no terminal reply can release it.)
+
+## How it works
+
+Your machine runs the hands — read, write, edit, run. The brain runs in the Imperal Cloud and reasons over your files, your history, and your connected apps through ICNLI. The model is a replaceable proposer at the edge; the kernel resolves, grounds, and decides. Webbee reads your facts. She doesn't invent them.
+
+## Links
+
+- **Imperal Cloud** — [imperal.io](https://imperal.io)
+- **Docs** — [docs.imperal.io](https://docs.imperal.io)
+- **ICNLI** — the open protocol, CC BY-SA 4.0 — [icnli.org](https://icnli.org)
+- **More from Imperal** — [github.com/imperalcloud](https://github.com/imperalcloud)
+
+---
+
+MIT © Imperal, Inc.

webbee-0.1.0/install.sh

@@ -0,0 +1,17 @@
+#!/bin/sh
+# Webbee installer — bootstraps uv (which brings its own Python) then installs webbee.
+set -e
+
+if ! command -v uv >/dev/null 2>&1; then
+  echo "Installing uv (Python toolchain manager)…"
+  curl -LsSf https://astral.sh/uv/install.sh | sh
+  # uv installs to ~/.local/bin or ~/.cargo/bin; make it visible for this run.
+  export PATH="$HOME/.local/bin:$HOME/.cargo/bin:$PATH"
+fi
+
+echo "Installing webbee…"
+uv tool install webbee
+
+echo ""
+echo "✅ webbee installed. Start it with:  webbee"
+echo "   (if 'webbee' is not found, add uv's tool bin to your PATH: uv tool update-shell)"

webbee-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "webbee"
+version = "0.1.0"
+description = "Webbee 🐝 — the Imperal Cloud coding agent in your terminal"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+authors = [{ name = "Imperal, Inc.", email = "hello@imperal.io" }]
+dependencies = ["imperal-mcp>=0.4.0", "imperal-sdk>=5.9.2", "httpx>=0.27", "httpx-sse>=0.4", "rich>=13.7", "prompt_toolkit>=3"]
+keywords = ["webbee", "imperal", "icnli", "coding-agent", "ai-agent", "cli", "terminal", "llm"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Operating System :: OS Independent",
+    "Topic :: Software Development",
+    "Topic :: Utilities",
+]
+
+[project.urls]
+Homepage = "https://imperal.io"
+Documentation = "https://docs.imperal.io"
+Repository = "https://github.com/imperalcloud/webbee-code"
+Issues = "https://github.com/imperalcloud/webbee-code/issues"
+Protocol = "https://icnli.org"
+
+[project.scripts]
+webbee = "webbee.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/webbee"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+asyncio_mode = "auto"

webbee-0.1.0/src/webbee/__init__.py

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

webbee-0.1.0/src/webbee/account.py

@@ -0,0 +1,78 @@
+import asyncio
+from dataclasses import dataclass
+from datetime import datetime
+
+
+@dataclass(frozen=True)
+class Account:
+    signed_in: bool = False
+    email: str = ""
+    nickname: str = ""
+    plan: str = ""
+    plan_status: str = ""
+    plan_renews: str = ""
+    dev_tier: str = ""
+    member_since: str = ""
+
+
+def _fmt_month(iso: str) -> str:
+    """'2026-04-27T10:00:00Z' -> 'Apr 2026'; '' on any failure."""
+    try:
+        return datetime.fromisoformat(iso.replace("Z", "+00:00")).strftime("%b %Y")
+    except Exception:
+        return ""
+
+
+def _fmt_day(iso: str) -> str:
+    """'2026-08-01T00:00:00Z' -> '2026-08-01'; '' on any failure."""
+    try:
+        return datetime.fromisoformat(iso.replace("Z", "+00:00")).strftime("%Y-%m-%d")
+    except Exception:
+        return ""
+
+
+async def _default_get(cfg, token: str, path: str) -> dict:
+    import httpx
+    async with httpx.AsyncClient(base_url=cfg.api_url, timeout=3.0) as c:
+        r = await c.get(path, headers={"Authorization": f"Bearer {token}"})
+        r.raise_for_status()
+        return r.json()
+
+
+async def fetch_account(cfg, token_provider, *, get=None) -> Account:
+    """Best-effort account summary for the welcome screen. NEVER raises: no
+    token or a failed /v1/auth/me -> Account(signed_in=False); a failed
+    billing/developer call just omits those fields."""
+    try:
+        token = await token_provider()
+    except Exception:
+        return Account(signed_in=False)
+
+    async def getter(path: str) -> dict:
+        if get is not None:
+            return await get(path)
+        return await _default_get(cfg, token, path)
+
+    async def _try(path):
+        try:
+            return await getter(path)
+        except Exception:
+            return None
+
+    me, sub, dev = await asyncio.gather(
+        _try("/v1/auth/me"), _try("/v1/billing/subscription"), _try("/v1/developer/profile"))
+    if not me:
+        return Account(signed_in=False)
+    attrs = me.get("attributes") or {}
+    sub = sub or {}
+    dev = dev or {}
+    return Account(
+        signed_in=True,
+        email=str(me.get("email", "") or ""),
+        nickname=str(dev.get("nickname", "") or ""),
+        plan=str(sub.get("plan", "") or ""),
+        plan_status=str(sub.get("status", "") or ""),
+        plan_renews=_fmt_day(str(sub.get("expires_at", "") or "")),
+        dev_tier=str(dev.get("tier", "") or attrs.get("developer_tier", "") or ""),
+        member_since=_fmt_month(str(me.get("created_at", "") or dev.get("registered_at", "") or "")),
+    )

webbee-0.1.0/src/webbee/banner_art.py

@@ -0,0 +1,9 @@
+# Webbee Code logo — pyfiglet "big" font (generated). Rendered bee-yellow + centered by render.py.
+WEBBEE_CODE = r"""__          __  _     _                  _____          _
+\ \        / / | |   | |                / ____|        | |
+ \ \  /\  / /__| |__ | |__   ___  ___  | |     ___   __| | ___
+  \ \/  \/ / _ \ '_ \| '_ \ / _ \/ _ \ | |    / _ \ / _` |/ _ \
+   \  /\  /  __/ |_) | |_) |  __/  __/ | |___| (_) | (_| |  __/
+    \/  \/ \___|_.__/|_.__/ \___|\___|  \_____\___/ \__,_|\___|
+
+"""

webbee-0.1.0/src/webbee/cli.py

@@ -0,0 +1,56 @@
+import argparse
+import asyncio
+import os
+
+from webbee import __version__
+from webbee.config import Config
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="webbee", description="Webbee 🐝 — coding agent in your terminal")
+    p.add_argument("--version", action="version", version=f"webbee {__version__}")
+    p.add_argument("--mode", choices=["default", "plan", "autopilot"], default="default")
+    sub = p.add_subparsers(dest="cmd")
+    sub.add_parser("login", help="Log in to your Imperal account in the browser")
+    sub.add_parser("logout", help="Log out and remove local credentials")
+    return p
+
+
+def main(argv=None) -> None:
+    args = build_parser().parse_args(argv)
+    cfg = Config.from_env()
+
+    if args.cmd == "login":
+        from imperal_mcp import auth
+        print(f"Logged in as {auth.login(cfg)}.")
+        return
+    if args.cmd == "logout":
+        from imperal_mcp import auth
+        asyncio.run(auth.logout(cfg))
+        print("Logged out.")
+        return
+
+    # Default: the polished REPL. Fire a non-blocking update-check first.
+    from webbee.repl import run_repl
+    try:
+        _maybe_print_update_notice()
+        asyncio.run(run_repl(cfg, args.mode))
+    except KeyboardInterrupt:
+        # Ctrl-C during the update-check fetch, or at the read_line() prompt,
+        # unwinds here — exit clean, no traceback. (repl.py itself now cancels
+        # a Ctrl-C mid-turn internally and returns to the prompt instead of
+        # propagating — see run_repl.)
+        print("\nBye 🐝")
+
+
+def _maybe_print_update_notice() -> None:
+    try:
+        from pathlib import Path
+        import time
+        from webbee.update import check_for_update, default_fetch
+        cache = Path(os.path.expanduser("~/.cache/webbee/update.json"))
+        notice = check_for_update(__version__, cache_path=cache, now=time.time(), fetch=default_fetch)
+        if notice:
+            print(notice)
+    except Exception:
+        pass  # update-check must never block or crash startup

webbee-0.1.0/src/webbee/commands.py

@@ -0,0 +1,77 @@
+from dataclasses import dataclass
+
+_MODES = ("default", "plan", "autopilot")
+
+_HELP = """Commands:
+  /help              show this help
+  /login             sign in to your Imperal account (browser)
+  /logout            sign out and remove local credentials
+  /clear             clear the screen + reset session counters
+  /mode [default|plan|autopilot]   consent mode (no arg — show current)
+  /cost  (=/usage)   tokens + $ cost this session
+  /status            cwd · git · surface · tokens · version
+  /exit  (=/quit)    quit"""
+
+
+@dataclass(frozen=True)
+class CommandContext:
+    mode: str
+    workspace: str
+    version: str
+    surface: str
+    logged_in: bool
+    session_tokens: int
+    session_cost: float
+    git_branch: str
+
+
+@dataclass(frozen=True)
+class SlashResult:
+    handled: bool
+    exit: bool = False
+    message: str = ""
+    action: str = ""
+    new_mode: "str | None" = None
+
+
+def dispatch(line: str, ctx: CommandContext) -> SlashResult:
+    """Parse one input line. Non-slash lines return handled=False (the REPL
+    then sends them to the agent). Slash lines are fully handled here."""
+    text = line.strip()
+    if not text.startswith("/"):
+        return SlashResult(handled=False)
+
+    parts = text.split()
+    cmd, args = parts[0].lower(), parts[1:]
+
+    if cmd in ("/exit", "/quit"):
+        return SlashResult(handled=True, exit=True)
+    if cmd == "/help":
+        return SlashResult(handled=True, action="help", message=_HELP)
+    if cmd == "/login":
+        return SlashResult(handled=True, action="login")
+    if cmd == "/logout":
+        return SlashResult(handled=True, action="logout")
+    if cmd == "/clear":
+        return SlashResult(handled=True, action="clear", message="Screen cleared, counters reset.")
+    if cmd in ("/cost", "/usage"):
+        return SlashResult(handled=True, action="cost",
+                           message=f"This session: {ctx.session_tokens} tokens (~${ctx.session_cost:.4f}). "
+                                   f"LLM turns don't spend credits.")
+    if cmd == "/status":
+        auth = "signed in" if ctx.logged_in else "not signed in (/login)"
+        msg = (f"surface: {ctx.surface}   mode: {ctx.mode}   {auth}\n"
+               f"cwd: {ctx.workspace}   git: {ctx.git_branch}\n"
+               f"tokens: {ctx.session_tokens} (~${ctx.session_cost:.4f})   webbee v{ctx.version}")
+        return SlashResult(handled=True, action="status", message=msg)
+    if cmd == "/mode":
+        if not args:
+            return SlashResult(handled=True, action="mode", new_mode=None,
+                               message=f"Current mode: {ctx.mode}. Available: {', '.join(_MODES)}.")
+        want = args[0].lower()
+        if want not in _MODES:
+            return SlashResult(handled=True, action="mode", new_mode=None,
+                               message=f"Unknown mode '{want}'. Available: {', '.join(_MODES)}.")
+        return SlashResult(handled=True, action="mode", new_mode=want,
+                           message=f"Mode → {want}.")
+    return SlashResult(handled=True, message=f"Unknown command '{cmd}'. /help for the list.")

webbee-0.1.0/src/webbee/config.py

@@ -0,0 +1,14 @@
+import os
+from dataclasses import dataclass
+
+@dataclass(frozen=True)
+class Config:
+    api_url: str
+    panel_url: str
+
+    @classmethod
+    def from_env(cls) -> "Config":
+        return cls(
+            api_url=os.environ.get("IMPERAL_API_URL", "https://auth.imperal.io").rstrip("/"),
+            panel_url=os.environ.get("IMPERAL_PANEL_URL", "https://panel.imperal.io").rstrip("/"),
+        )

webbee-0.1.0/src/webbee/events.py

@@ -0,0 +1,17 @@
+from typing import Protocol, runtime_checkable
+
+
+@runtime_checkable
+class TurnSink(Protocol):
+    """Everything a running coding turn tells the UI. The renderer (render.py)
+    implements this with Rich; tests implement it with a recording fake.
+    session.py imports ONLY this — never Rich — so the SSE loop stays testable."""
+
+    def tool_start(self, tool: str, args: dict) -> None: ...
+    def tool_result(self, tool: str, ok: bool, summary: str) -> None: ...
+    async def ask_consent(self, app_id: str, tool: str, args: dict) -> str: ...
+    def panel_release(self, panel_url: str, summary: str) -> None: ...
+    def progress(self, text: str) -> None: ...
+    def usage(self, tokens: int, cost_usd: float) -> None: ...
+    def plan_blocked(self, tool: str) -> None: ...
+    def user_echo(self, text: str) -> None: ...