hum-cli 0.0.1__tar.gz → 0.1.0__tar.gz

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

@@ -0,0 +1,41 @@
+name: publish
+# Tag vX.Y.Z → build the terminal UI bundle, build the Python package (bundle inside),
+# publish to PyPI (trusted publishing, no token) and to npm (@metaphi/hum, NPM_TOKEN secret).
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: cd tui && npm ci && npm run build
+      - uses: astral-sh/setup-uv@v5
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: actions/upload-artifact@v4
+        with: { name: npm, path: npm/ }
+  publish-pypi:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: dist, path: dist/ }
+      - uses: pypa/gh-action-pypi-publish@release/v1
+  publish-npm:
+    needs: build
+    runs-on: ubuntu-latest
+    continue-on-error: true   # until the npm org + NPM_TOKEN exist, PyPI still ships
+    steps:
+      - uses: actions/download-artifact@v4
+        with: { name: npm, path: npm/ }
+      - uses: actions/setup-node@v4
+        with: { node-version: 20, registry-url: "https://registry.npmjs.org" }
+      - run: cd npm && npm publish --access public
+        env: { NODE_AUTH_TOKEN: "${{ secrets.NPM_TOKEN }}" }

{hum_cli-0.0.1 → hum_cli-0.1.0}/.github/workflows/test.yml

@@ -9,6 +9,10 @@ jobs:
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 20 }
+      - run: cd tui && npm ci && npm run build
+        shell: bash
       - uses: astral-sh/setup-uv@v5
       - run: uv python install 3.12
       - run: uv venv --python 3.12 && uv pip install -e ".[dev,server,harbor]"

hum_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+node_modules/
+hum/tui/cli.mjs
+npm/dist/

{hum_cli-0.0.1 → hum_cli-0.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: hum-cli
-Version: 0.0.1
+Version: 0.1.0
 Summary: An agent harness built as an RL environment that humans can drive: session trees, interchangeable human/policy drivers, counterfactual shadow, earned autonomy, verifier in the loop.
 Requires-Python: >=3.12
 Requires-Dist: httpx>=0.27

hum_cli-0.1.0/README.md

@@ -0,0 +1,57 @@
+# Hum — हम
+
+*We.* Human and model, one harness.
+
+Hum is an agent harness built as an RL environment that humans can drive. The same loop serves a person at a keyboard, a policy in a rollout, or a shadow continuing from a fork — and the loop remembers who did what.
+
+What makes it different from a coding agent:
+
+- **Interchangeable drivers.** A human turn is a first-class move in the session tree, not a prompt.
+- **Counterfactual shadow.** When a human overrides a proposal, the pre-intervention state is forked, the policy finishes in shadow, and the grader scores both futures. Every override becomes a preference pair whose preference is a verifier, not a rater.
+- **Earned autonomy.** How much the policy may do unsupervised on a class of tasks is a number the world assigns from graded outcomes, updated online — `observe → propose → review → act`.
+- **Verifier in the loop.** The grader is both a tool the agent calls and the reward the trainer reads.
+- **Trajectory-native.** Every session is a valid ATIF trajectory with authorship, interventions, shadow branches, verdicts and token custody — a training sample as it is written.
+- **Model-agnostic, sovereign.** Any OpenAI-compatible endpoint: frontier, open weights, or your own policy served from the trainer. Runs on Modal or on your iron.
+
+## Run it
+
+```bash
+npm install -g @metaphi/hum      # or: uv tool install hum-cli  (either one installs both halves)
+hum login                        # browser opens → sign in with Google → back to the terminal
+cd your-repo
+hum                              # say what we're doing; it works, streams, shows its tool calls
+hum "make the nightly job idempotent"
+hum resume                       # pick up the last session
+```
+
+Two halves, one command: the terminal UI is Ink (Node ≥ 18) and the loop is Python — the npm package installs the engine through uv on first install; the Python package ships the UI bundle and uses it when Node is present (`hum --plain` is the Rich fallback; `HUM_PLAIN=1` too).
+
+While it works you see its thinking (dim), its words, and each tool call as it is being written — `writing src/PAYPOST.cbl…` appears the moment the path is known. Just type: a message steers it, `!cmd` runs a command yourself, Ctrl-C stops the current turn (what it had produced so far is kept). Edit files in your editor whenever you like — the session records the exact patch as your turn. Long sessions stay affordable: old tool output fades from the prompt and the context is summarised and restarted when it gets large (`/cost` shows how often). `/help` in a session lists the rest (`/model`, `/tools`, `/cost`).
+
+Signing in gives you a key on Metaphi's model proxy — GLM-5.3 by default. Bringing your own model is allowed (`hum model anthropic/claude-fable-5`, `hum key anthropic <key>`); those sessions are marked as running on your model.
+
+Other commands: `hum run "task"` (unattended, then exit — the mode rollouts use), `hum sessions`, `hum show <id>`, `hum sync`, `hum whoami`, `hum logout`.
+
+## Deployment (Metaphi)
+
+One Modal app, `server/modal_app.py`: sign-in (Firebase Auth in the browser, ID token verified server-side; allowlist), the **model proxy** every client talks to (OpenAI-compatible `/v1/chat/completions`; the person's Hum token is their key; every call metered per person with a monthly budget), and session intake. State is SQLite + session files on the volume `hum-data`. Routes are named — `glm-5.3` on zero-data-retention providers, `policy` = our weights from the trainer, `fable` — so moving the fleet onto our model is one route change, no client update.
+
+Tool servers (`control`, `run-unit`, …) are mounted for everyone from the server: `HUM_MCP_JSON` names the upstream MCP endpoints and their credentials; the client learns the list at login and reaches each one at `/mcp/<name>` with the person's own Hum token, so no upstream credential ever leaves the server. `~/.hum/config.toml` on a machine can additionally override the model, mount local MCP servers, and turn on backend behaviour — grader, autonomy-gated sessions, fork-and-grade on intervention, compaction threshold. Defaults are "be a great agent".
+
+## What a session records
+
+One JSONL per session, a tree of nodes. Every node: who acted (policy / human / shadow / system), what was said and called, the tool results, and the workspace **tree id** after it executed — Hum keeps a private git directory per workspace (`~/.hum/shadow/…`, never the project's `.git`) and snapshots into it, so any state in the session can be diffed against any other. A hand edit is the tree moving when no tool moved it: recorded as the person's turn with the **full patch**. An interrupted generation is kept on an `aborted` branch next to what the person did instead. A compaction is a `system` node whose summary restarts the context; nothing before it leaves the tree. The file is uploaded while the session runs (every 20 s) and at the end.
+
+## As a Harbor agent
+
+`harbor run -a hum.adapters.harbor:HumAgent -m openrouter/z-ai/glm-5.3 ...` — Terminal-Bench, MainframeBench through simhub `task_run --harness hum`, and Slime rollouts run the same class, with no human driver.
+
+## Layout
+
+```
+hum/runtime/   session tree · drivers · loop (shadow, compaction) · workspace (tree ids, patches) · autonomy · tools (+MCP) · grader · llm (streams) · observe · trajectory (ATIF)
+hum/adapters/  harbor
+hum/cli.py     commands, the Rich client, the TUI launcher · hum/engine.py the loop as a line protocol for a front-end
+tui/           the Ink terminal UI (builds to hum/tui/cli.mjs and npm/dist) · npm/ the npm package (@metaphi/hum)
+server/        sign-in · model proxy · MCP proxy · session intake (one Modal app)
+```

{hum_cli-0.0.1 → hum_cli-0.1.0}/hum/__init__.py

@@ -1,4 +1,4 @@
 """Hum — an agent harness built as an RL environment that humans can drive.
 
 हम (Hindi): we, us. Human and model, one harness."""
-__version__ = "0.0.1"
+__version__ = "0.1.0"

{hum_cli-0.0.1 → hum_cli-0.1.0}/hum/adapters/harbor.py

@@ -28,6 +28,7 @@ from hum.runtime.executor import ExecResult, decode
 from hum.runtime.prompt import system_prompt
 from hum.runtime.tools import MCPToolset
 from hum.runtime.trajectory import to_atif
+from hum.runtime.workspace import Workspace
 
 AGENT_NAME = "hum"
 
@@ -111,7 +112,9 @@ class HumAgent(BaseAgent):
                             temperature=self._temperature, reasoning_effort=self._reasoning_effort)
         prompt = system_prompt(tools_note="\n".join(notes))
         session = Session({"instruction": instruction}, session_id=self.session_id, path=self.logs_dir / "session.jsonl")
-        runner = Runner(session, executor, tools, PolicyDriver(llm), config=self._cfg, system_prompt=prompt)
+        # every node carries the sandbox tree id; the shadow git dir lives in the sandbox, outside /app
+        runner = Runner(session, executor, tools, PolicyDriver(llm), config=self._cfg, system_prompt=prompt,
+                        workspace=Workspace(executor, "/tmp/hum-shadow"))
         try:
             result = await runner.run()
         finally:

{hum_cli-0.0.1 → hum_cli-0.1.0}/hum/auth.py

@@ -30,6 +30,7 @@ class Credentials:
     default_model: str | None = None
     byo: dict[str, str] = field(default_factory=dict)  # provider -> key, user-supplied
     model: str | None = None         # user's chosen model, if any
+    mcp: list[dict[str, Any]] = field(default_factory=list)  # tool servers the deployment mounts for this person
 
     @property
     def logged_in(self) -> bool:
@@ -94,6 +95,7 @@ def login(auth_url: str | None = None, open_browser: bool = True, poll_timeout_s
             c.name = body["user"].get("name")
             m = body.get("model") or {}
             c.api_base, c.api_key, c.default_model = m.get("api_base"), m.get("api_key"), m.get("default_model")
+            c.mcp = list(body.get("mcp") or [])
             save(c)
             return c
         err = body.get("error")
@@ -106,7 +108,32 @@ def login(auth_url: str | None = None, open_browser: bool = True, poll_timeout_s
     raise TimeoutError("login timed out; run `hum login` again")
 
 
+def refresh(c: Credentials | None = None, timeout: float = 3.0, client: Any = None) -> Credentials:
+    """Best-effort: ask the server what this person has today (default model, tool
+    servers, budget). Never raises; on any failure the saved credentials stand."""
+    import httpx
+
+    c = c or load()
+    if not c.logged_in:
+        return c
+    try:
+        http = client or httpx.Client(timeout=timeout)
+        r = http.get(f"{c.auth_url}/me", headers={"Authorization": f"Bearer {c.access_token}"})
+        if r.status_code != 200:
+            return c
+        d = r.json()
+        m = d.get("model") or {}
+        c.default_model = m.get("default_model") or c.default_model
+        c.api_base = m.get("api_base") or c.api_base
+        c.mcp = list(d.get("mcp") or [])
+        save(c)
+    except Exception:  # noqa: BLE001
+        pass
+    return c
+
+
 def logout() -> None:
     c = load()
     c.access_token = c.email = c.name = c.api_base = c.api_key = c.default_model = None
+    c.mcp = []
     save(c)

{hum_cli-0.0.1 → hum_cli-0.1.0}/hum/cli.py

@@ -23,11 +23,12 @@ from pathlib import Path
 from typing import Any
 
 from hum import __version__
-from hum.runtime import (AutonomyPolicy, HumanAction, HumanDriver, LiteLLMClient, LocalExecutor, OpenAICompatClient, PolicyDriver,
-                         RunConfig, Runner, Session, ToolCall, ToolRegistry, Turn, builtin_tools)
-from hum.runtime.config import Config, load as load_config
+from hum.runtime import (AutonomyPolicy, Delegation, HumanAction, HumanDriver, LiteLLMClient, LocalExecutor, OpenAICompatClient, PolicyDriver,
+                         RunConfig, Runner, Session, StreamEvents, ToolCall, ToolRegistry, Turn, Workspace, builtin_tools, shadow_dir_for)
+from hum.runtime.config import Config, MCPConfig, load as load_config
 from hum.runtime.grader import PredicateGrader
-from hum.runtime.prompt import system_prompt
+from hum.runtime.llm import error_text
+from hum.runtime.prompt import project_instructions, system_prompt
 from hum.runtime.store import autonomy_path, home, list_sessions, session_path
 from hum.runtime.tools import MCPToolset
 from hum.ui import UI
@@ -40,11 +41,14 @@ HELP = """/help          this
 !cmd           run a command yourself
 Ctrl-C         stop the current turn"""
 
+UPLOAD_EVERY_S = 20.0
+
 
 def make_llm(cfg: Config):
     """Our proxy (or any OpenAI-compatible base): talk to it directly. BYO providers: litellm."""
     if cfg.api_base:
-        return OpenAICompatClient(cfg.model, api_base=cfg.api_base, api_key=cfg.api_key, temperature=cfg.temperature, reasoning_effort=cfg.reasoning_effort)
+        return OpenAICompatClient(cfg.model, api_base=cfg.api_base, api_key=cfg.api_key, temperature=cfg.temperature, reasoning_effort=cfg.reasoning_effort,
+                                  idle_timeout=cfg.idle_timeout_s)
     return LiteLLMClient(cfg.model, api_key=cfg.api_key, temperature=cfg.temperature, reasoning_effort=cfg.reasoning_effort)
 
 
@@ -69,20 +73,77 @@ class VisibleTools(ToolRegistry):
         return results
 
 
+class VisiblePolicy(PolicyDriver):
+    """The policy driver with the person watching: thinking, text and tool calls stream as they happen."""
+
+    def __init__(self, llm: Any, ui: UI):
+        super().__init__(llm, events=StreamEvents(text=ui.text, reasoning=ui.reasoning, tool=ui.tool_delta))
+        self.ui = ui
+        self.on_retry = lambda attempt, e: ui.warn(f"model connection: {error_text(e)} — retrying ({attempt})")
+
+    async def next(self, messages, tools):  # type: ignore[override]
+        self.ui.turn_started()
+        t = await super().next(messages, tools)
+        self.ui.end_text()
+        return t
+
+
+class Uploader:
+    """Sessions go home while they happen, not only at the end: every ``UPLOAD_EVERY_S``
+    the file is re-sent if it grew. A crashed terminal loses at most that window."""
+
+    def __init__(self, path: Path):
+        self.path = path
+        self._sent = -1
+        self._task: asyncio.Task | None = None
+
+    def start(self) -> None:
+        self._task = asyncio.create_task(self._loop())
+
+    async def _loop(self) -> None:
+        while True:
+            await asyncio.sleep(UPLOAD_EVERY_S)
+            await self.push()
+
+    async def push(self) -> None:
+        try:
+            size = self.path.stat().st_size
+        except OSError:
+            return
+        if size == self._sent:
+            return
+        try:
+            from hum import sync
+            if await asyncio.to_thread(sync.upload, self.path, None, None, 8.0):
+                self._sent = size
+        except Exception:  # noqa: BLE001
+            pass
+
+    async def stop(self) -> None:
+        if self._task:
+            self._task.cancel()
+            try:
+                await self._task
+            except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                pass
+        await self.push()
+
+
 class Client:
     def __init__(self, cfg: Config, cwd: Path, ui: UI | None = None):
         self.cfg, self.cwd = cfg, cwd
-        self.ui = ui or UI()
+        self.ui = ui or UI(show_reasoning=cfg.show_reasoning)
         self.executor = LocalExecutor(cwd)
         self.tools = VisibleTools(self.ui).extend(builtin_tools(self.executor.shell))
         self.toolsets: list[MCPToolset] = []
         self.task_class = cfg.task_class or cwd.name
         self.llm = make_llm(cfg)
+        self.workspace = Workspace(self.executor, shadow_dir_for(cwd, home()))
 
     # -- setup ---------------------------------------------------------------------------
     async def mount(self) -> list[str]:
         names = [self.executor.shell, "files", "grep"]
-        for m in self.cfg.mcp:
+        for m in [*self.cfg.mcp, *self.cfg.remote_mcp]:
             ts = MCPToolset(m.name, url=m.url, command=m.command, args=m.args, headers=m.headers)
             try:
                 mounted = await ts.connect()
@@ -98,13 +159,35 @@ class Client:
         for ts in self.toolsets:
             await ts.close()
 
+    def _delegation(self, session: Session) -> Delegation:
+        ui = self.ui
+
+        def events_for(n: int) -> StreamEvents:
+            return StreamEvents(text=ui.text, reasoning=ui.reasoning, tool=ui.tool_delta)
+
+        def wrap(reg: ToolRegistry) -> ToolRegistry:
+            v = VisibleTools(ui, observation_max_bytes=reg.observation_max_bytes)
+            for t in reg.tools.values():
+                v.add(t)
+            return v
+
+        return Delegation(session=session, executor=self.executor, tools=self.tools, llm_factory=lambda: make_llm(self.cfg),
+                          events_for=events_for, tools_wrapper=wrap, on_start=ui.agent_start, on_end=ui.agent_end)
+
     def runner(self, session: Session, human: HumanDriver | None) -> Runner:
-        policy = PolicyDriver(self.llm, on_text=self.ui.text)
+        policy = VisiblePolicy(self.llm, self.ui)
         grader = command_grader(self.cfg.grader) if self.cfg.grader and not self.cfg.grader.startswith("mcp:") else None
-        rc = RunConfig(gate=self.cfg.gate, shadow=self.cfg.shadow and human is not None, max_turns=self.cfg.max_turns, task_class=self.task_class)
-        notes = "\n".join(f"- {t.name}" for t in self.tools.tools.values() if "__" in t.name)
-        return Runner(session, self.executor, self.tools, policy, human=human, grader=grader, autonomy=AutonomyPolicy(autonomy_path()),
-                      config=rc, system_prompt=system_prompt(tools_note=notes, world_note=f"Working directory: {self.cwd} (shell: {self.executor.shell}, {sys.platform})"))
+        rc = RunConfig(gate=self.cfg.gate, shadow=self.cfg.shadow and human is not None, max_turns=self.cfg.max_turns, task_class=self.task_class,
+                       compact_at_tokens=self.cfg.compact_at_tokens)
+        if "delegate" not in self.tools.tools:
+            self.delegation = self._delegation(session)
+            self.tools.add(self.delegation.tool())
+        notes = "\n".join(f"- {t.name}: {t.description[:120]}" for t in self.tools.tools.values() if "__" in t.name)
+        r = Runner(session, self.executor, self.tools, policy, human=human, grader=grader, autonomy=AutonomyPolicy(autonomy_path()),
+                   config=rc, workspace=self.workspace,
+                   system_prompt=system_prompt(tools_note=notes, world_note=f"Working directory: {self.cwd} (shell: {self.executor.shell}, {sys.platform})",
+                                               instructions=project_instructions(self.cwd)))
+        return r
 
     def _session(self, task: str, kind: str) -> Session:
         meta = {"instruction": task, "task_class": self.task_class, "cwd": str(self.cwd), "model": self.cfg.model,
@@ -115,19 +198,20 @@ class Client:
     async def one_shot(self, task: str) -> int:
         names = await self.mount()
         session = self._session(task, "run")
+        up = Uploader(session.path); up.start()
         self.ui.banner(self.cfg.model, names, session.path.name, self.cfg.user)
         r = self.runner(session, None)
         self.ui.thinking(True)
         try:
             res = await r.run()
         except Exception as e:  # noqa: BLE001
-            self.ui.error(f"model error: {str(e).splitlines()[0][:300]}")
+            self.ui.error(f"model error: {error_text(e)} — the session is saved; `hum resume` picks it up")
             return 2
         finally:
             self.ui.thinking(False)
             self.ui.end_text()
             await self.close()
-            _sync_quietly(session.path)
+            await up.stop()
         self.ui.summary(res.turns, res.usage.cost_usd, res.verdict)
         return 0 if (res.verdict is None or res.verdict.passed) else 1
 
@@ -139,9 +223,11 @@ class Client:
         from prompt_toolkit.patch_stdout import patch_stdout
 
         names = await self.mount()
-        ps: PromptSession = PromptSession(history=FileHistory(str(home() / "history")))
+        ps: PromptSession = PromptSession(history=FileHistory(str(home() / "history")),
+                                          bottom_toolbar=lambda: self.ui.toolbar() or None, refresh_interval=0.5)
         session = resume
         pending: Turn | None = None
+        up: Uploader | None = None
         with patch_stdout(raw=True):
             if session is None:
                 task = first
@@ -155,6 +241,7 @@ class Client:
                 session = self._session(task.strip(), "chat")
             else:
                 pending = None
+            up = Uploader(session.path); up.start()
             self.ui.banner(self.cfg.model, names, session.path.name, self.cfg.user)
             human = HumanDriver()
             runner = self.runner(session, human)
@@ -164,6 +251,7 @@ class Client:
                     if head is not None and pending is None and (head.turn.author == "policy" or resume is not None):
                         # model is idle (resume, or after a finished turn): ask the person
                         resume = None
+                        self.ui.idle()
                         try:
                             line = await ps.prompt_async(HTML("<b>›</b> "))
                         except EOFError:
@@ -181,11 +269,12 @@ class Client:
                     pending = None
                     await self._attend(ps, run_task, human, runner)
             except Exception as e:  # noqa: BLE001
-                self.ui.error(f"model error: {str(e).splitlines()[0][:300]}")
+                self.ui.error(f"model error: {error_text(e)} — the session is saved; `hum resume` picks it up")
                 return 2
             finally:
+                self.ui.idle()
                 await self.close()
-                _sync_quietly(session.path)
+                await up.stop()
                 self.ui.info(f"session saved: {session.path.name}")
         return 0
 
@@ -199,14 +288,15 @@ class Client:
                 try:
                     line = line_task.result()
                 except KeyboardInterrupt:
+                    partial = runner.policy.partial()
                     run_task.cancel()
                     try:
                         await run_task
                     except (asyncio.CancelledError, Exception):  # noqa: BLE001
                         pass
                     self.ui.end_text()
-                    runner.record_interrupt()
-                    self.ui.info("stopped.")
+                    runner.record_interrupt(partial=partial)
+                    self.ui.info("stopped." + (" (what it had so far is kept)" if partial else ""))
                     return
                 except EOFError:
                     run_task.cancel()
@@ -247,8 +337,9 @@ class Client:
         elif cmd == "tools":
             self.ui.info(", ".join(sorted(self.tools.tools)))
         elif cmd == "cost":
-            u = runner.usage
-            self.ui.info(f"{u.input_tokens}+{u.output_tokens} tokens · ${u.cost_usd:.4f} · {runner.turns} turns")
+            u = runner.usage + getattr(getattr(self, "delegation", None), "usage", u.__class__())
+            self.ui.info(f"{u.input_tokens}+{u.output_tokens} tokens · ${u.cost_usd:.4f} · {runner.turns} turns" +
+                         (f" · context compacted {runner.compactions}×" if runner.compactions else ""))
         else:
             self.ui.warn(f"unknown /{cmd} — /help")
         return "handled"
@@ -260,14 +351,6 @@ class Client:
         return Turn(author="human", content=s)
 
 
-def _sync_quietly(path: Path) -> None:
-    try:
-        from hum import sync
-        sync.upload(path, timeout=5.0)
-    except Exception:  # noqa: BLE001
-        pass
-
-
 # --- commands -------------------------------------------------------------------------------------
 
 def cmd_sessions(ui: UI) -> None:
@@ -294,8 +377,10 @@ def cmd_show(ui: UI, name: str) -> None:
         n = s.nodes[nid]
         iv = f" [yellow]{n.intervention.kind}[/]" if n.intervention else ""
         vd = "" if not n.verdict else (" [green]✓[/]" if n.verdict.passed else " [red]✗[/]")
+        ev = f" [magenta]{n.extra['event']}[/]" if n.extra.get("event") in ("compaction", "aborted", "human_edit") else ""
         calls = ", ".join(c.name for c in n.turn.tool_calls) or "—"
-        ui.console.print(f"[dim]{n.branch:>8}[/] {n.turn.author:<6}{iv}{vd}  {calls}  [dim]{(n.turn.content or '')[:70]!r}[/]")
+        tree = f" [dim]{n.extra['tree'][:7]}[/]" if n.extra.get("tree") else ""
+        ui.console.print(f"[dim]{n.branch:>9}[/] {n.turn.author:<6}{iv}{vd}{ev}  {calls}{tree}  [dim]{(n.turn.content or '')[:70]!r}[/]")
     for p in s.pairs:
         ui.console.print(f"[bold]pair[/] preferred={p.preferred}")
 
@@ -307,7 +392,8 @@ def cmd_login(ui: UI, auth_url: str | None) -> int:
     except Exception as e:  # noqa: BLE001
         ui.error(f"login failed: {e}")
         return 1
-    ui.info(f"signed in as {c.email}" + (f" · model {c.default_model} via {c.api_base}" if c.api_base else ""))
+    ui.info(f"signed in as {c.email}" + (f" · model {c.default_model} via {c.api_base}" if c.api_base else "") +
+            (f" · tools: {', '.join(m['name'] for m in c.mcp)}" if c.mcp else ""))
     return 0
 
 
@@ -315,7 +401,8 @@ def cmd_whoami(ui: UI) -> None:
     from hum import auth
     c = auth.load()
     cfg = load_config()
-    ui.info(f"{c.email or 'not signed in'} · model {cfg.model}" + (f" via {cfg.api_base}" if cfg.api_base else (" (your own key)" if cfg.byo else " (no key)")))
+    ui.info(f"{c.email or 'not signed in'} · model {cfg.model}" + (f" via {cfg.api_base}" if cfg.api_base else (" (your own key)" if cfg.byo else " (no key)")) +
+            (f" · tools: {', '.join(m.name for m in [*cfg.mcp, *cfg.remote_mcp])}" if cfg.mcp or cfg.remote_mcp else ""))
 
 
 def cmd_model(ui: UI, name: str | None) -> None:
@@ -334,22 +421,86 @@ def cmd_key(ui: UI, provider: str, key: str) -> None:
     ui.info(f"stored your {provider} key (sessions on it are marked as your own model)")
 
 
+TUI_BUNDLE = Path(__file__).parent / "tui" / "cli.mjs"
+
+
+def _node() -> str | None:
+    """A Node ≥ 18 on PATH, or None (then the Rich client runs)."""
+    import shutil
+    import subprocess
+    exe = shutil.which("node")
+    if not exe:
+        return None
+    try:
+        v = subprocess.run([exe, "--version"], capture_output=True, text=True, timeout=5).stdout.strip().lstrip("v")
+        return exe if int(v.split(".")[0]) >= 18 else None
+    except Exception:  # noqa: BLE001
+        return None
+
+
+def launch_tui(cfg: Config, cwd: Path, task: str | None, resume: str | None) -> int:
+    """Run the loop here; hand the terminal to the Ink front-end, which connects back over localhost."""
+    import subprocess
+    import threading
+
+    node = _node()
+    if node is None or not TUI_BUNDLE.exists() or os.environ.get("HUM_PLAIN"):
+        return -1
+    ready: dict[str, int] = {}
+    evt = threading.Event()
+
+    async def run() -> int:
+        from hum.engine import Engine, Wire
+        done: asyncio.Future[int] = asyncio.get_event_loop().create_future()
+
+        async def on_conn(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+            try:
+                rc = await Engine(cfg, cwd, Wire(reader, writer)).serve()
+            finally:
+                if not done.done():
+                    done.set_result(rc)
+        server = await asyncio.start_server(on_conn, "127.0.0.1", 0)
+        ready["port"] = server.sockets[0].getsockname()[1]
+        evt.set()
+        async with server:
+            return await done
+
+    result: dict[str, int] = {}
+    t = threading.Thread(target=lambda: result.setdefault("rc", asyncio.run(run())), daemon=True)
+    t.start()
+    evt.wait(10)
+    argv = [node, str(TUI_BUNDLE)]
+    if resume:
+        argv += ["resume", resume]
+    elif task:
+        argv.append(task)
+    env = {**os.environ, "HUM_ENGINE_PORT": str(ready.get("port", 0))}
+    try:
+        rc = subprocess.run(argv, cwd=str(cwd), env=env).returncode
+    except KeyboardInterrupt:
+        rc = 130
+    t.join(15)
+    return rc
+
+
 def main(argv: list[str] | None = None) -> int:
     argv = list(sys.argv[1:] if argv is None else argv)
-    subs = ("chat", "run", "resume", "login", "logout", "whoami", "model", "key", "sessions", "show", "sync")
+    subs = ("chat", "run", "resume", "login", "logout", "whoami", "model", "key", "sessions", "show", "sync", "engine")
     if not argv or (argv[0] not in subs and argv[0] not in ("-h", "--help", "--version")):
         argv = ["chat", *argv]
     ap = argparse.ArgumentParser(prog="hum", description="Hum — हम. Human and model, one harness.")
     ap.add_argument("--version", action="version", version=f"hum {__version__}")
     sub = ap.add_subparsers(dest="cmd")
-    cp = sub.add_parser("chat"); cp.add_argument("task", nargs="?"); cp.add_argument("-C", "--cwd", default=".")
+    cp = sub.add_parser("chat"); cp.add_argument("task", nargs="?"); cp.add_argument("-C", "--cwd", default="."); cp.add_argument("--plain", action="store_true", help="the Rich client, no Ink")
     rp = sub.add_parser("run"); rp.add_argument("task"); rp.add_argument("-C", "--cwd", default=".")
-    rs = sub.add_parser("resume"); rs.add_argument("name", nargs="?", default="last")
+    rs = sub.add_parser("resume"); rs.add_argument("name", nargs="?", default="last"); rs.add_argument("--plain", action="store_true")
     lg = sub.add_parser("login"); lg.add_argument("--auth-url")
     sub.add_parser("logout"); sub.add_parser("whoami"); sub.add_parser("sessions"); sub.add_parser("sync")
     mp = sub.add_parser("model"); mp.add_argument("name", nargs="?")
     kp = sub.add_parser("key"); kp.add_argument("provider"); kp.add_argument("key")
     sp = sub.add_parser("show"); sp.add_argument("name")
+    ep = sub.add_parser("engine", help="serve the loop to a front-end over a localhost socket")
+    ep.add_argument("-C", "--cwd", default="."); ep.add_argument("--listen", action="store_true"); ep.add_argument("--port", type=int, default=int(os.environ.get("HUM_ENGINE_PORT", "0") or 0))
     a = ap.parse_args(argv)
     ui = UI()
     if a.cmd == "sessions":
@@ -369,20 +520,39 @@ def main(argv: list[str] | None = None) -> int:
     if a.cmd == "sync":
         from hum import sync
         sent, skipped = sync.sync_all(); ui.info(f"sent {sent}, already there {skipped}"); return 0
+    from hum import auth
+    auth.refresh()  # what the deployment gives this person today (model, tool servers); quiet on failure
     cfg = load_config()
     from hum.auth import PROVIDER_ENV, provider_of
     if cfg.api_key is None and cfg.api_base is None and "/" in cfg.model and provider_of(cfg.model) in PROVIDER_ENV:
         ui.error("no model access — `hum login`, or `hum key openrouter <key>`, or ~/.hum/config.toml"); return 2
     try:
+        if a.cmd == "engine":
+            from hum.engine import serve
+            return asyncio.run(serve(cfg, Path(a.cwd).resolve(), listen=a.listen or not a.port, port=a.port or None))
         if a.cmd == "run":
             return asyncio.run(Client(cfg, Path(a.cwd).resolve(), ui).one_shot(a.task))
         if a.cmd == "resume":
             s = Session.load(_find(a.name))
-            return asyncio.run(Client(cfg, Path(s.task.get("cwd", ".")).resolve(), ui).chat(None, resume=s))
+            cwd = Path(s.task.get("cwd", ".")).resolve()
+            if not a.plain and sys.stdin.isatty():
+                rc = launch_tui(cfg, cwd, None, a.name)
+                if rc >= 0:
+                    return rc
+            return asyncio.run(Client(cfg, cwd, ui).chat(None, resume=s))
+        if not a.plain and sys.stdin.isatty():
+            rc = launch_tui(cfg, Path(a.cwd).resolve(), a.task, None)
+            if rc >= 0:
+                return rc
         return asyncio.run(Client(cfg, Path(a.cwd).resolve(), ui).chat(a.task))
     except KeyboardInterrupt:
         print(); return 130
 
 
+def main_engine(argv: list[str] | None = None) -> int:
+    """``hum-engine``: the loop as a service for a front-end (the npm package's entry spawns this)."""
+    return main(["engine", *(sys.argv[1:] if argv is None else argv)])
+
+
 if __name__ == "__main__":
     sys.exit(main())