octomate-cli 0.0.2__py3-none-any.whl

octomate_cli/__init__.py

@@ -0,0 +1,8 @@
+"""Octomate's client half: the operator CLI, the native-session hook clients, and the
+transcript tail.
+
+Deliberately light: a client machine installs octomate-cli without the server.
+Commands that need the server (`serve`, config-derived defaults) import it lazily
+and say so plainly when it is absent. Shared stream and deployment contracts live
+in octomate_protocol, which depends on neither application.
+"""

octomate_cli/config.py

@@ -0,0 +1,281 @@
+"""The client's own configuration — the two facts the CLI needs to reach Octomate:
+where the server is, and the credential its hook routers require. A settings class,
+the way the deployment's own config is one, so the variables, the files and their
+precedence are declared in `CLISettings` rather than assembled by hand, and every
+command reads the one `cli_settings()` object rather than building its own. Owned here
+so a machine holding only octomate-cli never touches the server's config.
+
+The stdlib hook scripts (`emit.py`, `launch.py`) cannot use it, and that is not an
+oversight to be tidied away later. They exist to stay off the import cost of a
+package on a hook the session blocks on, several times a turn: `tomllib` costs ~7ms
+against `pydantic_settings`' ~230ms, on a script whose whole budget is ~25ms. So they
+re-spell the variable names and the same file precedence in stdlib. Two tests in
+`tests/agent/test_codex_emit.py` are what stop them drifting — one holds the names
+against `CLISettings.env`, the other that both halves still pick the same file — so
+a renamed field fails a test rather than a session going unauthenticated.
+"""
+
+from __future__ import annotations
+
+import json
+import secrets
+import tomllib
+from enum import Enum
+from functools import cache
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from pydantic import Field
+from pydantic_settings import (
+    BaseSettings,
+    PydanticBaseSettingsSource,
+    SettingsConfigDict,
+    TomlConfigSettingsSource,
+)
+from rich.console import Console
+from rich.panel import Panel
+
+# Guidance goes to stderr, so a caller reading this command's stdout gets the file
+# report alone.
+console = Console(stderr=True)
+
+
+class Scope(str, Enum):
+    user = "user"
+    project = "project"
+
+
+# The two files, as `toml_file` wants them and as the source of both spellings below.
+# Left unexpanded on purpose: pydantic resolves `~` and the relative path per settings
+# object rather than at import, which is what lets one process read the cli.toml of
+# whatever directory it was started in — a hook's cwd is its session's.
+USER_CONFIG = "~/.config/octomate/cli.toml"
+PROJECT_CONFIG = ".octomate/cli.toml"
+
+
+def user_config_path() -> Path:
+    """`~/.config/octomate/cli.toml` — where CLI tools keep their config, git and
+    ruff alike."""
+    return Path(USER_CONFIG).expanduser()
+
+
+def project_config_path() -> Path:
+    """`./.octomate/cli.toml` — beside the directory a session runs in, the way
+    `.claude/settings.json` scopes Claude. On a server machine `.octomate/` is also
+    the data directory; the two uses share the name, not their files."""
+    return Path.cwd() / PROJECT_CONFIG
+
+
+class CLISettings(BaseSettings):
+    """What this machine's client half knows, resolved the same way everywhere.
+
+    Reached through `cli_settings()` rather than constructed: one object per process,
+    which is what a command or a hook is.
+    """
+
+    model_config = SettingsConfigDict(
+        # The reason there is a prefix: the server's settings read `OCTOMATE__` with
+        # `__` between the levels, so a client variable under that prefix would read
+        # as a deployment key — and one of them, the retired deployment secret,
+        # literally was.
+        env_prefix="OCTOMATE_CLI_",
+        # An exported-but-empty variable means unset, and the files under it still
+        # answer — what a shell that cleared one intends.
+        env_ignore_empty=True,
+        # Weakest first: within one TOML source the later file wins, so the project's
+        # own beats the machine's. That is how one directory aims at a different
+        # server (a debug instance) without touching the default.
+        toml_file=(USER_CONFIG, PROJECT_CONFIG),
+    )
+
+    url: str | None = Field(
+        default=None,
+        description=(
+            "Octomate's base URL (`http://host:port`), resolved when a hook fires "
+            "rather than pinned at install time — so switching servers is a config "
+            "switch, not a re-install. An explicit `--url` beats it."
+        ),
+    )
+    secret: str | None = Field(
+        default=None,
+        description=(
+            "This person's own bearer, which the hook routers and the served MCP "
+            "endpoints authenticate. Minted by `octomate configure` and registered "
+            "by an admin under `users.<name>.secret`."
+        ),
+    )
+
+    @classmethod
+    def env(cls, field: str) -> str:
+        """`CLISettings.env("secret")` — the variable that field reads.
+
+        The class is asked every time rather than a constant standing beside it, so
+        no variable name is ever spelled by hand: this composes from the prefix
+        pydantic is holding, and a renamed field changes what every message says.
+
+        A method and not `__class_getitem__`, which would read better at the ~20 call
+        sites: a subscript on a class is a *type* to a type checker, so pyright reads
+        `CLISettings["secret"]` as specialising the model and calls the result
+        `type[CLISettings]` whatever the override returns. Every site would be
+        mistyped, and silently so wherever the value is only interpolated.
+
+        `.get` with a default rather than a subscript because the key is optional in
+        `SettingsConfigDict`, and an absent prefix is the empty one.
+        """
+        return f"{cls.model_config.get('env_prefix', '')}{field}".upper()
+
+    @classmethod
+    def settings_customise_sources(
+        cls,
+        settings_cls: type[BaseSettings],
+        init_settings: PydanticBaseSettingsSource,
+        env_settings: PydanticBaseSettingsSource,
+        dotenv_settings: PydanticBaseSettingsSource,
+        file_secret_settings: PydanticBaseSettingsSource,
+    ) -> tuple[PydanticBaseSettingsSource, ...]:
+        """Which kinds of source there are, and in what order — per key, following
+        Claude's own settings pattern: an explicit value wins, then the environment,
+        then the files. Which files is `toml_file`'s to say, above.
+
+        The environment is ahead of the files for the cases with no home to write
+        into, a container or a CI step. Everywhere else the files are the durable
+        home and what `configure` writes: they survive launch paths the environment
+        does not — a GUI-launched editor never sourced a shell profile — and they are
+        per-user, where an exported credential is inherited by everything that shell
+        starts.
+
+        No dotenv and no secrets dir: `./.env` on a server machine is the
+        *deployment's* environment, and reading it here would let a server's file
+        decide a person's credential.
+        """
+        return (init_settings, env_settings, TomlConfigSettingsSource(settings_cls))
+
+
+@cache
+def cli_settings() -> CLISettings:
+    """This process's client config — the one object every command reads.
+
+    Typer has nothing like FastAPI's `Depends` to hand a command its config, and its
+    one shared-state channel, `ctx.obj`, is untyped and reaches only commands invoked
+    through the root app. So the dependency is this function, and every call site
+    asks it rather than building a settings object of its own.
+
+    Cached because a process is one CLI invocation or one hook, and neither moves its
+    own environment or working directory while it runs. Not for speed: a settings
+    object costs ~0.13ms to build and no invocation wants more than two. The suite is
+    the one process that plays many, and `tests/conftest.py` clears this between them.
+    """
+    return CLISettings()
+
+
+def load_config(path: Path) -> dict[str, object]:
+    """One file's table, `{}` when absent — what `configure` reads back before
+    rewriting it, so keys it does not own survive. A file that does not parse is an
+    operator's mistake worth a precise error, not a silent fallback."""
+    try:
+        text = path.read_text()
+    except OSError:
+        return {}
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        raise typer.BadParameter(f"{path}: {error}") from None
+
+
+def configure(
+    url: Annotated[
+        str | None,
+        typer.Option(help="Octomate's base URL (http://host:port)."),
+    ] = None,
+    secret: Annotated[
+        str | None,
+        typer.Option(
+            help="Your own credential. Omitted, the one already resolving is kept, "
+            "and one is generated when nothing resolves anywhere."
+        ),
+    ] = None,
+    scope: Annotated[
+        Scope,
+        typer.Option(
+            help="Which file to write: 'user' (~/.config/octomate/cli.toml) or "
+            "'project' (./.octomate/cli.toml, resolved first)."
+        ),
+    ] = Scope.user,
+) -> None:
+    """Write the client config every hook, tail and MCP entry on this machine reads.
+
+    The first of the three steps that set a person up: this mints the credential and
+    puts it somewhere durable, the panel it prints says how to get it registered, and
+    the runtimes' own `hooks install` / `mcp install` come last, once there is
+    something for them to resolve.
+
+    The environment still overrides both scopes, and a `--url` pinned at install time
+    beats everything — the files are the durable floor, so ingest works from any
+    launch path on a machine where octomate-cli is the only thing installed.
+    """
+    path = project_config_path() if scope is Scope.project else user_config_path()
+    current = load_config(path)
+    if url is not None:
+        current["url"] = url
+    generated = False
+    if secret is None:
+        secret = cli_settings().secret
+        if secret is None:
+            secret = secrets.token_urlsafe(32)
+            generated = True
+    current["secret"] = secret
+
+    # json.dumps output is a valid TOML basic string: the escapes JSON emits are the
+    # subset TOML shares, so no hand-rolled quoting and no extra dependency.
+    content = "".join(
+        f"{key} = {json.dumps(value)}\n"
+        for key, value in current.items()
+        if isinstance(value, str)
+    )
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(content)
+    path.chmod(0o600)  # it holds a credential
+    # The one command that moves what `cli_settings()` answers, so it is the one that
+    # has to drop the cached answer: anything reading after this wants the file just
+    # written, not the object built before it existed.
+    cli_settings.cache_clear()
+
+    address = current.get("url") or f"(unset — hooks need ${CLISettings.env('url')})"
+    typer.echo(f"Wrote {path}")
+    typer.echo(f"  url:    {address}")
+    typer.echo(f"  secret: {'generated' if generated else 'kept'}")
+    # Prose is left for rich to wrap; lines meant to be copied are kept short enough
+    # to survive intact, since a token split across two lines is worse than no help.
+    steps = [
+        "Point your runtimes at it. Each writes down what it resolves here, so "
+        "these come after the credential exists — and again if it moves:",
+        "",
+        "  [cyan]octomate claude hooks install[/]   [cyan]octomate claude mcp install[/]",
+        "  [cyan]octomate codex hooks install[/]    [cyan]octomate codex mcp install[/]",
+    ]
+    if not generated:
+        console.print(Panel("\n".join(steps), title="[bold]next[/]", padding=(1, 2)))
+        return
+    # A generated token is url-safe and a supplied one never reaches here, so no
+    # value below can carry markup.
+    console.print(
+        Panel(
+            "\n".join(
+                [
+                    "[yellow]Octomate cannot see this credential yet[/], and its "
+                    "routers refuse a bearer they do not know. Give it to the "
+                    "server's admin to add as yours:",
+                    "",
+                    "  [dim]users:[/]",
+                    "    [dim]<your username>:[/]",
+                    f"      [dim]secret:[/] [green]{secret}[/]",
+                    "",
+                    *steps,
+                ]
+            ),
+            title="[bold yellow]register this credential[/]",
+            border_style="yellow",
+            padding=(1, 2),
+        )
+    )

octomate_cli/emit.py

@@ -0,0 +1,153 @@
+"""Forward a native session's hook payload from stdin to Octomate's hook router.
+
+Both agents' installers write `command` hooks that run this script — Codex because it
+has no `http` hook handler at all, Claude so the settings file stays free of hosts and
+credentials: with no `--url` pinned, the router's address is resolved when the hook
+fires, from `OCTOMATE_CLI_URL` or the client config file, and switching servers is an
+environment switch, not a re-install. The transport is HTTP either way: this only
+carries stdin to the router at `<base>{--path}`.
+
+Run by absolute path, never as `python -m octomate...`, and imports nothing from
+octomate. Both matter: `octomate/__init__.py` builds `Octomate`, which pulls in
+pydantic-ai and costs ~1.9s to import — per hook, on a handler the session blocks on,
+several times a turn. By path with stdlib only it is ~25ms, because Python never
+imports the package.
+
+Anything added here must keep that property: stdlib imports only. The environment
+variable names, the hook path, and the client-config resolution below are duplicated
+from `octomate_cli/config.py` and `octomate_cli/tentacles/codex/hooks.py` (and octomate's
+`tentacles/codex/hooks.py` holds `DRIVEN_ENV`) for the same reason — this
+module cannot import them without paying for a package. Change them together; the
+tests hold the copies to the canonical ones.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tomllib
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+SECRET_ENV = "OCTOMATE_CLI_SECRET"
+OCTOMATE_URL_ENV = "OCTOMATE_CLI_URL"
+DRIVEN_ENV = "OCTOMATE_CODEX_DRIVEN"
+CODEX_HOOK_PATH = "/hooks/codex"
+HOOK_TIMEOUT = 10
+
+USAGE = "usage: emit.py --path <hook-path> [--url <hook-url>]"
+
+
+def config_files() -> tuple[Path, Path]:
+    """Project scope first, then user scope — hooks run with cwd at the directory the
+    session lives in, so `./.octomate/cli.toml` is that project's own override."""
+    return (
+        Path.cwd() / ".octomate" / "cli.toml",
+        Path.home() / ".config" / "octomate" / "cli.toml",
+    )
+
+
+def file_config(path: Path) -> dict[str, object]:
+    """One file's table, `{}` when absent. A file that does not parse is reported and
+    treated as absent: this runs on the blocking path of someone's session, where a
+    traceback helps nobody."""
+    try:
+        text = path.read_text()
+    except OSError:
+        return {}
+    try:
+        return tomllib.loads(text)
+    except tomllib.TOMLDecodeError as error:
+        print(f"octomate: ignoring unparseable {path}: {error}", file=sys.stderr)
+        return {}
+
+
+def resolved(key: str, env: str, tables: list[dict[str, object]]) -> str | None:
+    """The client's precedence: the environment, then the config files in scope
+    order."""
+    value = os.environ.get(env)
+    if value:
+        return value
+    for table in tables:
+        from_file = table.get(key)
+        if isinstance(from_file, str) and from_file:
+            return from_file
+    return None
+
+
+def main(url: str, secret: str | None) -> int:
+    payload = json.load(sys.stdin)
+    if os.environ.get(DRIVEN_ENV) == "1":
+        # Octomate is driving this session itself and already records the run; the
+        # router drops the event rather than writing the conversation a second time.
+        payload["octomate_driven"] = True
+
+    if not secret:
+        print(
+            f"octomate: no credential — {SECRET_ENV} is unset and the "
+            "client config holds none, so this session is not being ingested. "
+            "Run `octomate configure`.",
+            file=sys.stderr,
+        )
+        return 1
+
+    request = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode(),
+        headers={
+            "Content-Type": "application/json",
+            "Authorization": f"Bearer {secret}",
+        },
+    )
+    try:
+        urllib.request.urlopen(request, timeout=HOOK_TIMEOUT).close()
+    except (urllib.error.URLError, OSError) as error:
+        # Report and get out of the way. A session is a person's own work, and Octomate
+        # only observes it; an ingest that cannot deliver must not take the turn down
+        # with it.
+        print(f"octomate: hook delivery to {url} failed: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    path: str | None = None
+    url: str | None = None
+    while args:
+        flag = args.pop(0)
+        if flag == "--path" and args:
+            path = args.pop(0)
+        elif flag == "--url" and args:
+            url = args.pop(0)
+        else:
+            print(USAGE, file=sys.stderr)
+            raise SystemExit(2)
+    # `--url` alone is the previous generation's installed form; honoring it keeps
+    # hooks written before `--path` existed delivering until their next re-install.
+    if path is None and url is None:
+        print(USAGE, file=sys.stderr)
+        raise SystemExit(2)
+    tables = [file_config(candidate) for candidate in config_files()]
+    if url is None:
+        base = resolved("url", OCTOMATE_URL_ENV, tables)
+        url = base.rstrip("/") + str(path) if base else None
+    if url is None:
+        print(
+            f"octomate: no target — {OCTOMATE_URL_ENV} is unset, the client config "
+            "names no url, and no --url was pinned. This session is not being "
+            "ingested; run `octomate configure`.",
+            file=sys.stderr,
+        )
+        status = 1
+    else:
+        status = main(url, resolved("secret", SECRET_ENV, tables))
+    if path is None or path == CODEX_HOOK_PATH:
+        # Codex reads stdout as the hook's decision; an empty object decides nothing,
+        # which is what an observer should do. A Claude hook's stdout is injected into
+        # the turn's context instead, so on Claude's path silence is the only correct
+        # answer.
+        print("{}")
+    raise SystemExit(status)

octomate_cli/launch.py

@@ -0,0 +1,146 @@
+"""Spawn the transcript tail for a native session — the launcher hook.
+
+The forwarding hooks carry the ledger to Octomate over HTTP, but they can start
+nothing on this machine; the transcript stream needs a local process, and this
+command hook is what starts it. It fires on every prompt, spawns `octomate <agent>
+tail` detached, and returns at once so the turn never waits — the tail itself refuses
+to run twice per session, so the repeated fire is the liveness check, not a leak.
+On a Codex `SubagentStop`, the event's `agent_transcript_path` rides along as
+`--agent-path`: the running tail cannot see which sibling rollout is a child of its
+session, so the hook that knows hands it the path (the tail spools it and exits when
+one already holds the session).
+
+The stream address is pinned only when the install pinned `--url`; otherwise it is
+derived when the hook fires, from `OCTOMATE_CLI_URL` or the client config file — the
+same resolution the forwarding hooks follow. With none of them, nothing spawns and
+nothing is said: the emit hook on the same event already complained on stderr.
+
+Run by absolute path, never as `python -m octomate...`, and imports nothing from
+octomate: `octomate/__init__.py` builds `Octomate`, which costs ~1.9s to import, and
+this command is on the blocking path of every prompt. The spawned tail pays that cost
+detached, off it. Anything added here must keep the stdlib-only property; the
+environment variable name and the client-config resolution are duplicated from
+`octomate_cli/config.py` for the same reason — change them together.
+
+Prints nothing on success: a `UserPromptSubmit` hook's stdout is injected into the
+turn's context, so silence is the only correct answer.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+import sys
+import tomllib
+from pathlib import Path
+
+OCTOMATE_URL_ENV = "OCTOMATE_CLI_URL"
+
+USAGE = (
+    "usage: launch.py [--url <stream-url>] [--path <hook-path>] "
+    "[--agent <claude|codex>] --octomate <bin>"
+)
+
+
+def config_files() -> tuple[Path, Path]:
+    """Project scope first, then user scope — mirroring `emit.py`'s resolution."""
+    return (
+        Path.cwd() / ".octomate" / "cli.toml",
+        Path.home() / ".config" / "octomate" / "cli.toml",
+    )
+
+
+def configured_base() -> str | None:
+    """The server base from the environment, then the config files in scope order. A
+    file that does not parse counts as absent — the emit hook on the same event
+    reports it."""
+    value = os.environ.get(OCTOMATE_URL_ENV)
+    if value:
+        return value
+    for path in config_files():
+        try:
+            table = tomllib.loads(path.read_text())
+        except (OSError, tomllib.TOMLDecodeError):
+            continue
+        url = table.get("url")
+        if isinstance(url, str) and url:
+            return url
+    return None
+
+
+def stream_url(url: str | None, path: str | None) -> str | None:
+    """The pinned stream URL, or one derived from the resolved base — the same
+    `http(s) → ws(s)` + `/stream` derivation the installer's `stream_url_for` does,
+    duplicated here because this script cannot import the package."""
+    if url is not None:
+        return url
+    base = configured_base()
+    if base is None or path is None:
+        return None
+    scheme, _, rest = base.rstrip("/").partition("://")
+    return f"{'wss' if scheme == 'https' else 'ws'}://{rest}{path}/stream"
+
+
+def main(url: str | None, path: str | None, agent: str, octomate_bin: str) -> int:
+    event = json.load(sys.stdin)
+    session_id = event.get("session_id")
+    transcript_path = event.get("transcript_path")
+    if not isinstance(session_id, str) or not isinstance(transcript_path, str):
+        # An event that names no transcript has nothing to tail; the forwarding hooks
+        # still carry the ledger, so this is not the place to complain.
+        return 0
+    target = stream_url(url, path)
+    if target is None:
+        return 0
+    command = [
+        octomate_bin,
+        agent,
+        "tail",
+        "--session",
+        session_id,
+        "--path",
+        transcript_path,
+        "--url",
+        target,
+    ]
+    cwd = event.get("cwd")
+    if isinstance(cwd, str) and cwd:
+        command += ["--cwd", cwd]
+    agent_path = event.get("agent_transcript_path")
+    if isinstance(agent_path, str) and agent_path:
+        command += ["--agent-path", agent_path]
+    subprocess.Popen(
+        command,
+        stdin=subprocess.DEVNULL,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        # Detached: the tail outlives this hook and never holds the turn.
+        start_new_session=True,
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    args = sys.argv[1:]
+    url: str | None = None
+    path: str | None = None
+    agent = "claude"
+    octomate_bin: str | None = None
+    while args:
+        flag = args.pop(0)
+        if flag == "--url" and args:
+            url = args.pop(0)
+        elif flag == "--path" and args:
+            path = args.pop(0)
+        elif flag == "--agent" and args:
+            agent = args.pop(0)
+        elif flag == "--octomate" and args:
+            octomate_bin = args.pop(0)
+        else:
+            print(USAGE, file=sys.stderr)
+            raise SystemExit(2)
+    if octomate_bin is None or (url is None and path is None):
+        print(USAGE, file=sys.stderr)
+        raise SystemExit(2)
+    raise SystemExit(main(url, path, agent, octomate_bin))

octomate_cli/main.py

@@ -0,0 +1,53 @@
+"""The root Typer app behind the `octomate` command: each agent's command group,
+configure, serve, and upgrade.
+
+Every group is mounted whatever the machine holds — server or client — so the surface
+stays discoverable; a command that needs the absent half says so when invoked rather
+than vanishing.
+"""
+
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+from typing import Annotated
+
+import typer
+
+from octomate_cli.config import configure
+from octomate_cli.serve import serve, upgrade
+from octomate_cli.tentacles.claude import claude_typer
+from octomate_cli.tentacles.codex import codex_typer
+from octomate_cli.tentacles.deepseek import deepseek_typer
+
+app = typer.Typer(help="Octomate operator CLI.", no_args_is_help=True)
+app.command("serve")(serve)
+app.command("upgrade")(upgrade)
+# One credential per person, written here and read by every agent's hooks, tail and
+# MCP entry alike.
+app.command("configure")(configure)
+app.add_typer(claude_typer, name="claude")
+app.add_typer(codex_typer, name="codex")
+app.add_typer(deepseek_typer, name="deepseek")
+
+
+@app.callback(invoke_without_command=True)
+def options(
+    show_version: Annotated[
+        bool,
+        typer.Option(
+            "--version", is_eager=True, help="Show installed package versions."
+        ),
+    ] = False,
+) -> None:
+    if show_version:
+        for package in ("octomate-cli", "octomate-protocol", "octomate"):
+            try:
+                installed = version(package)
+            except PackageNotFoundError:
+                continue
+            typer.echo(f"{package} {installed}")
+        raise typer.Exit()
+
+
+if __name__ == "__main__":
+    app()