hum-cli 0.0.1__py3-none-any.whl

hum/__init__.py

@@ -0,0 +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"

hum/adapters/harbor.py

@@ -0,0 +1,128 @@
+"""Harbor adapter: the runtime as a Harbor ``BaseAgent``.
+
+This is how the harness enters every arena that already speaks Harbor —
+Terminal-Bench, MainframeBench through simhub's task_run, and Slime rollouts
+(the policy is served at an OpenAI-compatible endpoint; Harbor passes it as
+``-m openai/policy`` with ``OPENAI_BASE_URL``). Same class, no human driver.
+
+Register with ``harbor run --agent-import-path hum.adapters.harbor:HumAgent``.
+"""
+from __future__ import annotations
+
+import base64
+import json
+import shlex
+import uuid
+from pathlib import Path
+from typing import Any
+
+from harbor.agents.base import BaseAgent
+from harbor.agents.model_connection import ModelConnectionSpec
+from harbor.environments.base import BaseEnvironment
+from harbor.models.agent.context import AgentContext
+from harbor.models.trajectories import Trajectory
+
+from hum import __version__
+from hum.runtime import LiteLLMClient, PolicyDriver, RunConfig, Runner, Session, ToolRegistry, builtin_tools
+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
+
+AGENT_NAME = "hum"
+
+
+class HarborExecutor:
+    """Executor over a Harbor environment. Files move as base64 through exec so
+    no host-side temp paths are involved; snapshots are tarballs in the sandbox."""
+
+    def __init__(self, env: BaseEnvironment, cwd: str = "/app"):
+        self.env, self.cwd = env, cwd
+
+    async def exec(self, command: str, cwd: str | None = None, timeout_sec: int | None = None) -> ExecResult:
+        r = await self.env.exec(command, cwd=cwd or self.cwd, timeout_sec=timeout_sec)
+        return ExecResult(stdout=r.stdout or "", stderr=r.stderr or "", returncode=r.return_code if r.return_code is not None else 0)
+
+    async def read(self, path: str) -> bytes:
+        r = await self.env.exec(f"base64 -w0 {shlex.quote(path)}", cwd=self.cwd, timeout_sec=60)
+        if r.return_code not in (0, None):
+            raise FileNotFoundError(r.stderr or path)
+        return base64.b64decode(r.stdout or "")
+
+    async def write(self, path: str, data: bytes) -> None:
+        b64 = base64.b64encode(data).decode()
+        r = await self.env.exec(f"mkdir -p $(dirname {shlex.quote(path)}) && echo {b64} | base64 -d > {shlex.quote(path)}", cwd=self.cwd, timeout_sec=60)
+        if r.return_code not in (0, None):
+            raise OSError(r.stderr or f"write failed: {path}")
+
+    async def snapshot(self) -> str:
+        sid = uuid.uuid4().hex[:12]
+        await self.env.exec(f"mkdir -p /tmp/harness_snap && tar czf /tmp/harness_snap/{sid}.tgz -C {shlex.quote(self.cwd)} .", timeout_sec=600)
+        return sid
+
+    async def fork(self, snapshot_id: str):
+        # One sandbox per trial: shadow forks need a second sandbox, which Harbor
+        # does not hand out. Unattended runs never fork; attended runs use the
+        # hosted-session executor instead.
+        raise NotImplementedError("HarborExecutor cannot fork; run attended sessions on a forkable executor")
+
+    async def close(self) -> None:
+        return None
+
+
+class HumAgent(BaseAgent):
+    SUPPORTS_ATIF = True
+    MODEL_CONNECTION = ModelConnectionSpec()  # provider inferred from the model name (openai/..., anthropic/..., openrouter/...)
+
+    def __init__(self, logs_dir: Path, model_name: str | None = None, *args: Any, temperature: float | None = None,
+                 reasoning_effort: str | None = None, max_turns: int = 200, max_wall_s: float = 3600.0,
+                 observation_max_bytes: int = 16_000, **kwargs: Any):
+        super().__init__(logs_dir, model_name, *args, **kwargs)
+        self._temperature = temperature
+        self._reasoning_effort = reasoning_effort
+        self._cfg = RunConfig(max_turns=int(max_turns), max_wall_s=float(max_wall_s), shadow=False)
+        self._obs_bytes = int(observation_max_bytes)
+        self._toolsets: list[MCPToolset] = []
+
+    @staticmethod
+    def name() -> str:
+        return AGENT_NAME
+
+    def version(self) -> str | None:
+        return __version__
+
+    async def setup(self, environment: BaseEnvironment) -> None:
+        return None  # nothing is installed in the sandbox; the loop runs host-side
+
+    async def run(self, instruction: str, environment: BaseEnvironment, context: AgentContext) -> None:
+        executor = HarborExecutor(environment)
+        tools = ToolRegistry(observation_max_bytes=self._obs_bytes).extend(builtin_tools())
+        notes = []
+        for s in self.mcp_servers or []:
+            ts = MCPToolset(s.name, url=s.url, command=s.command, args=s.args) if s.transport == "stdio" or s.url else None
+            if ts is None:
+                continue
+            mounted = await ts.connect()
+            tools.extend(mounted)
+            self._toolsets.append(ts)
+            notes.append(f"- {s.name}: " + ", ".join(t.name for t in mounted))
+        conn = self.model_connection
+        llm = LiteLLMClient(self.model_name or "", api_base=conn.base_url, api_key=conn.api_key,
+                            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)
+        try:
+            result = await runner.run()
+        finally:
+            for ts in self._toolsets:
+                await ts.close()
+            traj = to_atif(session, agent_name=AGENT_NAME, agent_version=__version__ or "0", model_name=self.model_name,
+                           system_prompt=prompt, tool_definitions=tools.to_openai())
+            Trajectory.model_validate(traj)  # stay a valid ATIF document
+            (self.logs_dir / "trajectory.json").write_text(json.dumps(traj, ensure_ascii=False, indent=1))
+        context.n_input_tokens = result.usage.input_tokens
+        context.n_output_tokens = result.usage.output_tokens
+        context.n_cache_tokens = result.usage.cache_tokens
+        context.cost_usd = result.usage.cost_usd
+        context.metadata = {"harness": AGENT_NAME, "turns": result.turns, "stop_reason": result.stop_reason}

hum/auth.py

@@ -0,0 +1,112 @@
+"""Sign-in from the terminal: ``hum login`` opens the browser (device-code flow,
+RFC 8628), the person signs in with Google, the terminal receives a Hum token
+plus their key on our model proxy. Credentials live in ~/.hum/credentials.json
+(mode 0600). BYO provider keys live next to them.
+"""
+from __future__ import annotations
+
+import json
+import os
+import time
+import webbrowser
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+
+from hum import __version__
+from hum.runtime.store import home
+
+DEFAULT_AUTH_URL = os.environ.get("HUM_AUTH_URL", "https://metaphi-ai--hum-web.modal.run")
+
+
+@dataclass
+class Credentials:
+    auth_url: str = DEFAULT_AUTH_URL
+    access_token: str | None = None
+    email: str | None = None
+    name: str | None = None
+    api_base: str | None = None      # our proxy
+    api_key: str | None = None       # this person's key on it
+    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
+
+    @property
+    def logged_in(self) -> bool:
+        return bool(self.access_token and self.email)
+
+
+def path() -> Path:
+    return home() / "credentials.json"
+
+
+def load() -> Credentials:
+    p = path()
+    if not p.exists():
+        return Credentials()
+    try:
+        d = json.loads(p.read_text())
+        return Credentials(**{k: v for k, v in d.items() if k in Credentials.__dataclass_fields__})
+    except Exception:  # noqa: BLE001
+        return Credentials()
+
+
+def save(c: Credentials) -> None:
+    p = path()
+    p.write_text(json.dumps(asdict(c), indent=1))
+    os.chmod(p, 0o600)
+
+
+PROVIDER_ENV = {"openrouter": "OPENROUTER_API_KEY", "anthropic": "ANTHROPIC_API_KEY", "openai": "OPENAI_API_KEY", "gemini": "GEMINI_API_KEY"}
+
+
+def provider_of(model: str) -> str:
+    return model.split("/", 1)[0] if "/" in model else "openai"
+
+
+def login(auth_url: str | None = None, open_browser: bool = True, poll_timeout_s: float = 600.0, client: Any = None) -> Credentials:
+    """Device-code flow. ``client`` is an httpx.Client (tests inject one)."""
+    import httpx
+
+    base = (auth_url or load().auth_url or DEFAULT_AUTH_URL).rstrip("/")
+    http = client or httpx.Client(timeout=20.0)
+    r = http.post(f"{base}/device/code", json={"client": "hum-cli", "version": __version__})
+    r.raise_for_status()
+    d = r.json()
+    uri = d.get("verification_uri_complete") or d["verification_uri"]
+    print(f"\nOpen {uri}\nand confirm the code  {d['user_code']}\n")
+    if open_browser:
+        try:
+            webbrowser.open(uri)
+        except Exception:  # noqa: BLE001
+            pass
+    interval = float(d.get("interval", 3))
+    deadline = time.monotonic() + min(poll_timeout_s, float(d.get("expires_in", 600)))
+    while time.monotonic() < deadline:
+        time.sleep(interval)
+        t = http.post(f"{base}/device/token", json={"device_code": d["device_code"]})
+        body = t.json()
+        if t.status_code == 200 and body.get("access_token"):
+            c = load()
+            c.auth_url = base
+            c.access_token = body["access_token"]
+            c.email = body["user"]["email"]
+            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")
+            save(c)
+            return c
+        err = body.get("error")
+        if err == "slow_down":
+            interval += 2
+        elif err in ("authorization_pending", None):
+            continue
+        else:
+            raise RuntimeError(f"login failed: {err}")
+    raise TimeoutError("login timed out; run `hum login` again")
+
+
+def logout() -> None:
+    c = load()
+    c.access_token = c.email = c.name = c.api_base = c.api_key = c.default_model = None
+    save(c)

hum/cli.py

@@ -0,0 +1,388 @@
+"""Hum's terminal client.
+
+    hum [task]            talk to it in the current directory
+    hum run "task"        one task, unattended, then exit
+    hum resume [id]       pick up a session
+    hum login / logout / whoami
+    hum model [name]      choose the model (blank: show)
+    hum key <provider> <key>   bring your own provider key
+    hum sessions / show <id> / sync
+
+To the person it's a coding agent. Everything they do — a message, a hand
+edit, a command they ran, an interrupt — is recorded as their turn in the
+session tree; the backend learns from that. Configuration is the deployment's
+(~/.hum/config.toml), not the user's.
+"""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import os
+import sys
+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.grader import PredicateGrader
+from hum.runtime.prompt import 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
+
+HELP = """/help          this
+/model [name]  show or switch the model for this session
+/tools         what's mounted
+/cost          tokens and cost so far
+/quit          leave (Ctrl-D works too)
+!cmd           run a command yourself
+Ctrl-C         stop the current turn"""
+
+
+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 LiteLLMClient(cfg.model, api_key=cfg.api_key, temperature=cfg.temperature, reasoning_effort=cfg.reasoning_effort)
+
+
+def command_grader(cmd: str) -> PredicateGrader:
+    async def fn(ex: Any, task: dict[str, Any]) -> tuple[bool, float, dict[str, Any]]:
+        r = await ex.exec(cmd, timeout_sec=900)
+        return r.returncode == 0, 1.0 if r.returncode == 0 else 0.0, {"command": cmd, "returncode": r.returncode, "tail": r.text[-2000:]}
+    return PredicateGrader(f"cmd:{cmd}", fn)
+
+
+class VisibleTools(ToolRegistry):
+    def __init__(self, ui: UI, **kw: Any):
+        super().__init__(**kw)
+        self.ui = ui
+
+    async def call_many(self, calls, executor, parallel=True):  # type: ignore[override]
+        for c in calls:
+            self.ui.call(c)
+        results = await super().call_many(calls, executor, parallel)
+        for r in results:
+            self.ui.result(r)
+        return results
+
+
+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.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)
+
+    # -- setup ---------------------------------------------------------------------------
+    async def mount(self) -> list[str]:
+        names = [self.executor.shell, "files", "grep"]
+        for m in self.cfg.mcp:
+            ts = MCPToolset(m.name, url=m.url, command=m.command, args=m.args, headers=m.headers)
+            try:
+                mounted = await ts.connect()
+            except Exception as e:  # noqa: BLE001
+                self.ui.warn(f"{m.name}: unavailable ({str(e).splitlines()[0][:120]})")
+                continue
+            self.tools.extend(mounted)
+            self.toolsets.append(ts)
+            names.append(m.name)
+        return names
+
+    async def close(self) -> None:
+        for ts in self.toolsets:
+            await ts.close()
+
+    def runner(self, session: Session, human: HumanDriver | None) -> Runner:
+        policy = PolicyDriver(self.llm, on_text=self.ui.text)
+        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})"))
+
+    def _session(self, task: str, kind: str) -> Session:
+        meta = {"instruction": task, "task_class": self.task_class, "cwd": str(self.cwd), "model": self.cfg.model,
+                "byo": self.cfg.byo, "user": self.cfg.user, "client": f"hum-cli/{__version__}"}
+        return Session(meta, path=session_path(kind))
+
+    # -- unattended ----------------------------------------------------------------------------
+    async def one_shot(self, task: str) -> int:
+        names = await self.mount()
+        session = self._session(task, "run")
+        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]}")
+            return 2
+        finally:
+            self.ui.thinking(False)
+            self.ui.end_text()
+            await self.close()
+            _sync_quietly(session.path)
+        self.ui.summary(res.turns, res.usage.cost_usd, res.verdict)
+        return 0 if (res.verdict is None or res.verdict.passed) else 1
+
+    # -- conversation ------------------------------------------------------------------------------
+    async def chat(self, first: str | None, resume: Session | None = None) -> int:
+        from prompt_toolkit import PromptSession
+        from prompt_toolkit.formatted_text import HTML
+        from prompt_toolkit.history import FileHistory
+        from prompt_toolkit.patch_stdout import patch_stdout
+
+        names = await self.mount()
+        ps: PromptSession = PromptSession(history=FileHistory(str(home() / "history")))
+        session = resume
+        pending: Turn | None = None
+        with patch_stdout(raw=True):
+            if session is None:
+                task = first
+                if not task:
+                    try:
+                        task = (await ps.prompt_async(HTML("<b>›</b> "))).strip()
+                    except (EOFError, KeyboardInterrupt):
+                        await self.close(); return 0
+                    if not task:
+                        await self.close(); return 0
+                session = self._session(task.strip(), "chat")
+            else:
+                pending = None
+            self.ui.banner(self.cfg.model, names, session.path.name, self.cfg.user)
+            human = HumanDriver()
+            runner = self.runner(session, human)
+            try:
+                while True:
+                    head = session.head("main")
+                    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
+                        try:
+                            line = await ps.prompt_async(HTML("<b>›</b> "))
+                        except EOFError:
+                            break
+                        except KeyboardInterrupt:
+                            self.ui.info("Ctrl-D or /quit to leave")
+                            continue
+                        cmd = self._slash(line, session, runner)
+                        if cmd == "quit":
+                            break
+                        if cmd == "handled" or not line.strip():
+                            continue
+                        pending = self._as_turn(line)
+                    run_task = asyncio.create_task(runner.run(continue_from=head.id if head else None, initial=pending))
+                    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]}")
+                return 2
+            finally:
+                await self.close()
+                _sync_quietly(session.path)
+                self.ui.info(f"session saved: {session.path.name}")
+        return 0
+
+    async def _attend(self, ps: Any, run_task: asyncio.Task, human: HumanDriver, runner: Runner) -> None:
+        """While the model works: the person can type (steering) or Ctrl-C (stop)."""
+        from prompt_toolkit.formatted_text import HTML
+        while not run_task.done():
+            line_task = asyncio.create_task(ps.prompt_async(HTML("<style fg='#888'>  </style>")))
+            done, _ = await asyncio.wait({run_task, line_task}, return_when=asyncio.FIRST_COMPLETED)
+            if line_task in done:
+                try:
+                    line = line_task.result()
+                except KeyboardInterrupt:
+                    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.")
+                    return
+                except EOFError:
+                    run_task.cancel()
+                    raise
+                if line.strip():
+                    if self._slash(line, runner.session, runner) == "quit":
+                        run_task.cancel(); raise EOFError
+                    human.send(HumanAction(turn=self._as_turn(line)))
+            else:
+                line_task.cancel()
+                try:
+                    await line_task
+                except (asyncio.CancelledError, Exception):  # noqa: BLE001
+                    pass
+        try:
+            res = await run_task
+        except asyncio.CancelledError:
+            return
+        self.ui.end_text()
+        if res.stop_reason != "done":
+            self.ui.info(f"— {res.stop_reason}")
+
+    def _slash(self, line: str, session: Session, runner: Runner) -> str | None:
+        s = line.strip()
+        if not s.startswith("/"):
+            return None
+        cmd, _, arg = s[1:].partition(" ")
+        if cmd in ("quit", "exit", "q"):
+            return "quit"
+        if cmd == "help":
+            self.ui.info(HELP)
+        elif cmd == "model":
+            if arg:
+                self.cfg.model = arg.strip(); self.llm = make_llm(self.cfg); runner.policy.llm = self.llm
+                self.ui.info(f"model → {self.cfg.model}" + ("  (your own key)" if self.cfg.byo else ""))
+            else:
+                self.ui.info(f"model: {self.cfg.model}" + (f" via {self.cfg.api_base}" if self.cfg.api_base else ""))
+        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")
+        else:
+            self.ui.warn(f"unknown /{cmd} — /help")
+        return "handled"
+
+    def _as_turn(self, line: str) -> Turn:
+        s = line.strip()
+        if s.startswith("!"):
+            return Turn(author="human", tool_calls=[ToolCall(id=f"h{os.urandom(3).hex()}", name=self.executor.shell, arguments={"command": s[1:].strip()})])
+        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:
+    for p in list_sessions():
+        try:
+            s = Session.load(p)
+            hv = sum(1 for n in s.nodes.values() if n.intervention)
+            ui.console.print(f"[dim]{p.stem}[/]  {len(s.order):>3} turns  {hv:>2} yours  {s.task.get('instruction', '')[:70]}")
+        except Exception as e:  # noqa: BLE001
+            ui.console.print(f"[dim]{p.name}[/]  (unreadable: {e})")
+
+
+def _find(name: str) -> Path:
+    ms = [p for p in list_sessions() if name in p.name] if name and name != "last" else list_sessions()
+    if not ms:
+        sys.exit(f"no session matching {name!r}")
+    return ms[-1]
+
+
+def cmd_show(ui: UI, name: str) -> None:
+    s = Session.load(_find(name))
+    ui.console.print(f"[bold]{s.task.get('instruction')}[/]  [dim]{s.task.get('model')} · {s.task.get('cwd')}[/]")
+    for nid in s.order:
+        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]✗[/]")
+        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}[/]")
+    for p in s.pairs:
+        ui.console.print(f"[bold]pair[/] preferred={p.preferred}")
+
+
+def cmd_login(ui: UI, auth_url: str | None) -> int:
+    from hum import auth
+    try:
+        c = auth.login(auth_url)
+    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 ""))
+    return 0
+
+
+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)")))
+
+
+def cmd_model(ui: UI, name: str | None) -> None:
+    from hum import auth
+    c = auth.load()
+    if name:
+        c.model = None if name in ("default", "-") else name
+        auth.save(c)
+    cfg = load_config()
+    ui.info(f"model: {cfg.model}" + ("  (your own key)" if cfg.byo else (f"  via {cfg.api_base}" if cfg.api_base else "  (no key — `hum login` or `hum key <provider> <key>`)")))
+
+
+def cmd_key(ui: UI, provider: str, key: str) -> None:
+    from hum import auth
+    c = auth.load(); c.byo[provider] = key; auth.save(c)
+    ui.info(f"stored your {provider} key (sessions on it are marked as your own model)")
+
+
+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")
+    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=".")
+    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")
+    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")
+    a = ap.parse_args(argv)
+    ui = UI()
+    if a.cmd == "sessions":
+        cmd_sessions(ui); return 0
+    if a.cmd == "show":
+        cmd_show(ui, a.name); return 0
+    if a.cmd == "login":
+        return cmd_login(ui, a.auth_url)
+    if a.cmd == "logout":
+        from hum import auth; auth.logout(); ui.info("signed out"); return 0
+    if a.cmd == "whoami":
+        cmd_whoami(ui); return 0
+    if a.cmd == "model":
+        cmd_model(ui, a.name); return 0
+    if a.cmd == "key":
+        cmd_key(ui, a.provider, a.key); return 0
+    if a.cmd == "sync":
+        from hum import sync
+        sent, skipped = sync.sync_all(); ui.info(f"sent {sent}, already there {skipped}"); return 0
+    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 == "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))
+        return asyncio.run(Client(cfg, Path(a.cwd).resolve(), ui).chat(a.task))
+    except KeyboardInterrupt:
+        print(); return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hum/runtime/__init__.py

@@ -0,0 +1,10 @@
+from .models import (Author, Intervention, InterventionKind, Node, PreferencePair,
+                     ToolCall, ToolResult, Turn, Usage, Verdict)
+from .session import Session
+from .executor import ExecResult, Executor, LocalExecutor
+from .tools import Tool, ToolRegistry, builtin_tools
+from .llm import LLM, LiteLLMClient, OpenAICompatClient, ScriptedLLM
+from .drivers import HumanAction, HumanDriver, PolicyDriver
+from .grader import Grader
+from .autonomy import AutonomyPolicy, Level
+from .loop import RunConfig, Runner, RunResult