muse-cli 0.3.3__tar.gz → 0.3.5__tar.gz

{muse_cli-0.3.3 → muse_cli-0.3.5}/.gitignore

@@ -5,6 +5,7 @@ __pycache__/
 *.egg-info/
 dist/
 build/
+uv.lock
 
 # Local secrets and state (never commit)
 cookies.txt

{muse_cli-0.3.3 → muse_cli-0.3.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: muse-cli
-Version: 0.3.3
+Version: 0.3.5
 Summary: Command-line client for your personal muse.ai AI agent: chat, automate, and manage side chats, feed, goals, ideas, and sessions from the terminal. No browser needed.
 Project-URL: Homepage, https://github.com/nikships/muse-cli
 Project-URL: Documentation, https://github.com/nikships/muse-cli#readme
@@ -84,7 +84,7 @@ to `~/.agents/skills/muse-cli`:
 curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
 ```
 
-Upgrade with `muse-cli update`. In a terminal it also checks PyPI once a day and, when a newer release exists, prints that command on stderr. It does not upgrade itself. Set `MUSE_NO_UPDATE_CHECK=1` to silence the notice. The check stays quiet when output is piped or `CI` is set. Remove with `uv tool uninstall muse-cli`.
+Upgrade with `muse-cli update`. It also refreshes the agent skill if you installed one (the skill ships inside the package, so it always matches the CLI). `muse-cli update --skill` refreshes or installs just the skill, with no package upgrade, which is handy after `pip` or `pipx` installs. In a terminal it also checks PyPI once a day and, when a newer release exists, prints that command on stderr. It does not upgrade itself. Set `MUSE_NO_UPDATE_CHECK=1` to silence the notice. The check stays quiet when output is piped or `CI` is set. Remove with `uv tool uninstall muse-cli`.
 
 Logging in is a separate one-time step. Chrome shares its cookies after you
 turn on remote debugging. Follow [Log in once](#log-in-once) before running
@@ -209,10 +209,12 @@ muse-cli history --limit 3 --download ./out       # save files from these messag
 muse-cli send "make a cat video" --wait 300 --download ./out
 muse-cli watch --thread <session-id>              # tail one side chat
 
+muse-cli unread                                   # unread counts
 muse-cli feed --limit 5
+muse-cli feed-status                              # also: feed-prompt
 muse-cli feed-react <unit-id> love
-muse-cli goals
-muse-cli ideas
+muse-cli goals                                    # one goal: muse-cli goal <id>
+muse-cli ideas                                    # one idea: muse-cli idea <id>
 muse-cli idea-exec <idea-id>                      # agent acts on the idea
 
 muse-cli session-start --title "trip planning"    # new side chat
@@ -268,17 +270,26 @@ uv run python -m unittest discover -s tests   # unit tests (no network)
 muse-cli/
 assets/              README artwork (generated with Muse Image)
 docs/PROTOCOL.md     protocol reference for re-derivation
+scripts/             release version bump (used by CI)
+site/                landing page (Firebase Hosting)
 skills/muse-cli/     agent skill
 src/muse_cli/
   cli.py             argument parsing and all commands
+  chat.py            interactive chat (the default command)
   gateway.py         gateway client (auth, Noise transport, subscriptions)
+  update.py          daily update notice and `muse-cli update`
+  skill.py           installs and refreshes the bundled agent skill
   routes.json        258 gateway methods extracted from the web client
   desc0.bin          protobuf descriptors for the wire framing
   desc1.bin
+tests/               unit tests (no network)
 install.sh           CLI + skill installer
 pyproject.toml
 ```
 
+See [AGENTS.md](https://github.com/nikships/muse-cli/blob/main/AGENTS.md) for
+release flow and contributor notes. Merging to `main` publishes a release.
+
 ## Setup notes
 
 - Login is the [Log in once](#log-in-once) section above. Cookies live at

{muse_cli-0.3.3 → muse_cli-0.3.5}/README.md

@@ -47,7 +47,7 @@ to `~/.agents/skills/muse-cli`:
 curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
 ```
 
-Upgrade with `muse-cli update`. In a terminal it also checks PyPI once a day and, when a newer release exists, prints that command on stderr. It does not upgrade itself. Set `MUSE_NO_UPDATE_CHECK=1` to silence the notice. The check stays quiet when output is piped or `CI` is set. Remove with `uv tool uninstall muse-cli`.
+Upgrade with `muse-cli update`. It also refreshes the agent skill if you installed one (the skill ships inside the package, so it always matches the CLI). `muse-cli update --skill` refreshes or installs just the skill, with no package upgrade, which is handy after `pip` or `pipx` installs. In a terminal it also checks PyPI once a day and, when a newer release exists, prints that command on stderr. It does not upgrade itself. Set `MUSE_NO_UPDATE_CHECK=1` to silence the notice. The check stays quiet when output is piped or `CI` is set. Remove with `uv tool uninstall muse-cli`.
 
 Logging in is a separate one-time step. Chrome shares its cookies after you
 turn on remote debugging. Follow [Log in once](#log-in-once) before running
@@ -172,10 +172,12 @@ muse-cli history --limit 3 --download ./out       # save files from these messag
 muse-cli send "make a cat video" --wait 300 --download ./out
 muse-cli watch --thread <session-id>              # tail one side chat
 
+muse-cli unread                                   # unread counts
 muse-cli feed --limit 5
+muse-cli feed-status                              # also: feed-prompt
 muse-cli feed-react <unit-id> love
-muse-cli goals
-muse-cli ideas
+muse-cli goals                                    # one goal: muse-cli goal <id>
+muse-cli ideas                                    # one idea: muse-cli idea <id>
 muse-cli idea-exec <idea-id>                      # agent acts on the idea
 
 muse-cli session-start --title "trip planning"    # new side chat
@@ -231,17 +233,26 @@ uv run python -m unittest discover -s tests   # unit tests (no network)
 muse-cli/
 assets/              README artwork (generated with Muse Image)
 docs/PROTOCOL.md     protocol reference for re-derivation
+scripts/             release version bump (used by CI)
+site/                landing page (Firebase Hosting)
 skills/muse-cli/     agent skill
 src/muse_cli/
   cli.py             argument parsing and all commands
+  chat.py            interactive chat (the default command)
   gateway.py         gateway client (auth, Noise transport, subscriptions)
+  update.py          daily update notice and `muse-cli update`
+  skill.py           installs and refreshes the bundled agent skill
   routes.json        258 gateway methods extracted from the web client
   desc0.bin          protobuf descriptors for the wire framing
   desc1.bin
+tests/               unit tests (no network)
 install.sh           CLI + skill installer
 pyproject.toml
 ```
 
+See [AGENTS.md](https://github.com/nikships/muse-cli/blob/main/AGENTS.md) for
+release flow and contributor notes. Merging to `main` publishes a release.
+
 ## Setup notes
 
 - Login is the [Log in once](#log-in-once) section above. Cookies live at

{muse_cli-0.3.3 → muse_cli-0.3.5}/docs/PROTOCOL.md

@@ -1,14 +1,14 @@
 # Protocol notes
 
-How `muse` talks to the muse.ai personal gateway. Derived from the web app's
-own client bundle and verified live. Internal APIs are unversioned and can
-change without notice; if calls start failing, re-derive from a fresh bundle
-(HAR capture + the `derive-client` workflow).
+How `muse-cli` talks to the muse.ai personal gateway. Derived from the web
+app's own client bundle and verified live. Internal APIs are unversioned and
+can change without notice; if calls start failing, re-derive from a fresh
+bundle (for example a HAR capture of the web app).
 
 ## Layers
 
 ```
-muse CLI
+muse-cli
   │  HTTPS (browser TLS fingerprint via curl-impersonated requests)
   ▼
 muse.ai            cookies → POST /api/auth/check → access_token

{muse_cli-0.3.3 → muse_cli-0.3.5}/pyproject.toml

@@ -75,6 +75,9 @@ path = "src/muse_cli/__init__.py"
 [tool.hatch.build.targets.wheel]
 packages = ["src/muse_cli"]
 
+[tool.hatch.build.targets.wheel.force-include]
+"skills/muse-cli/SKILL.md" = "muse_cli/SKILL.md"
+
 [tool.hatch.build.targets.sdist]
 include = [
     "src/muse_cli",

{muse_cli-0.3.3 → muse_cli-0.3.5}/skills/muse-cli/SKILL.md

@@ -11,7 +11,8 @@ fails and report it.
 
 The `muse-cli` package (on PyPI) talks to the muse.ai personal gateway
 directly. No browser needed after the one-time cookie export. Every command
-prints JSON.
+prints JSON except the interactive chat (`muse-cli` with no arguments, or
+`muse-cli chat`), which is a human REPL. Agents should never run it.
 
 ## 1. Install
 
@@ -143,9 +144,9 @@ muse-cli files --limit 20                               # images/videos the agen
 muse-cli download <seq|message-id|sandbox://...> -o DIR # save them locally
 muse-cli history --limit 3 --download DIR               # save files from these messages
 muse-cli send "make an image of X" --wait 300 --download DIR
-muse-cli feed --limit 5
-muse-cli goals
-muse-cli ideas
+muse-cli feed --limit 5                                 # also: feed-status, feed-prompt
+muse-cli goals                                          # one goal: muse-cli goal <id>
+muse-cli ideas                                          # one idea: muse-cli idea <id>
 muse-cli unread
 muse-cli seen <thread-id>
 ```
@@ -173,6 +174,9 @@ only for methods with no wrapper.
   than the wait: the message still landed, confirm with `history`. The reply
   is matched as a genuine answer, not background chatter.
 - `send --wait 0` is fire-and-forget (no polling).
+- Running `muse-cli` with no command opens the interactive chat and blocks on
+  stdin. From an agent, always pass an explicit command such as `status` or
+  `send`.
 - `history` without `--thread` reads the main chat only.
 - Agent media shows up as `sandbox://workspace/...` paths, often in a
   separate `delta.presentation` event after the text reply. `download` looks
@@ -184,6 +188,7 @@ only for methods with no wrapper.
 - Respect rate limits. Writes (send, react, execute, session ops) act as the
   user in their agent: announce them before running, never loop them.
 - A stderr line `A new release of muse-cli is available` is an upgrade
-  notice, not a failed command. Upgrade with `muse-cli update`. The check
+  notice, not a failed command. Upgrade with `muse-cli update`, which also refreshes this skill
+  (`muse-cli update --skill` refreshes only the skill). The check
   runs at most once a day, only in a terminal, and never changes the install
   by itself. `MUSE_NO_UPDATE_CHECK=1` silences it.

{muse_cli-0.3.3 → muse_cli-0.3.5}/src/muse_cli/__init__.py

@@ -1,3 +1,3 @@
 """muse-cli: talk to your personal muse.ai AI agent from the terminal."""
 
-__version__ = "0.3.3"
+__version__ = "0.3.5"

{muse_cli-0.3.3 → muse_cli-0.3.5}/src/muse_cli/chat.py

@@ -6,6 +6,13 @@ reader. Picks up the conversation you used last. Type /help for commands.
 import json
 import os
 import time
+# Enable GNU readline / libedit for line editing, history, and proper
+# CJK/wide-character deletion (wcwidth). It is a standard library C extension,
+# but unavailable on native Windows or stripped/minimal Python installations.
+try:
+    import readline
+except ImportError:
+    readline = None
 
 from .cli import CONFIG_DIR, cmd_auth_export, connect, fmt_event, load_config
 from .gateway import AuthError, GatewayError
@@ -14,6 +21,7 @@ WAIT = 300   # seconds to wait for the first reply
 QUIET = 10   # seconds of silence after a reply before taking the next message
 POLL = 1     # seconds between history reads while waiting for a reply
 STATE = os.path.join(CONFIG_DIR, "chat.json")
+HISTFILE = os.path.join(CONFIG_DIR, "chat_history")
 
 HELP = """Commands:
   /chats          list your conversations
@@ -214,6 +222,11 @@ def start():
 
 
 def cmd_chat(_args):
+    if readline is not None:
+        try:
+            readline.read_history_file(HISTFILE)
+        except OSError:
+            pass
     chat = start()
     print(f"Muse chat, in: {chat.st['title']}. Type /help for commands, /exit to quit.")
     try:
@@ -255,5 +268,12 @@ def cmd_chat(_args):
     except KeyboardInterrupt:
         pass
     finally:
+        if readline is not None:
+            try:
+                os.makedirs(CONFIG_DIR, exist_ok=True)
+                readline.set_history_length(1000)
+                readline.write_history_file(HISTFILE)
+            except OSError:
+                pass
         chat.gw.close()
     print("\nBye.")

{muse_cli-0.3.3 → muse_cli-0.3.5}/src/muse_cli/cli.py

@@ -15,6 +15,7 @@ import re
 import shutil
 import sys
 import time
+import urllib.parse
 
 from . import __version__
 from .gateway import Gateway, AuthError, GatewayError, load_cookies
@@ -29,7 +30,8 @@ def load_config():
     import secrets
     cfg = {}
     if os.path.exists(CONFIG_FILE):
-        cfg = json.load(open(CONFIG_FILE))
+        with open(CONFIG_FILE) as fh:
+            cfg = json.load(fh)
     changed = False
     cfg.setdefault("cookies_file", COOKIES_FILE)
     if "vm_id" not in cfg and os.environ.get("MUSE_VM_ID"):
@@ -42,7 +44,8 @@ def load_config():
             changed = True
     if changed:
         os.makedirs(CONFIG_DIR, exist_ok=True)
-        json.dump(cfg, open(CONFIG_FILE, "w"), indent=2)
+        with open(CONFIG_FILE, "w") as fh:
+            json.dump(cfg, fh, indent=2)
     return cfg
 
 
@@ -284,9 +287,11 @@ def cmd_auth_export(_args):
         ]))
     if os.path.exists(COOKIES_FILE):
         os.replace(COOKIES_FILE, COOKIES_FILE + ".bak")
-    with open(COOKIES_FILE, "w") as fh:
+    # Create the file at 0600 so the cookies are never readable by others,
+    # not even between the write and a later chmod.
+    fd = os.open(COOKIES_FILE, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as fh:
         fh.write("\n".join(lines) + "\n")
-    os.chmod(COOKIES_FILE, 0o600)
     print(f"saved {len(jar)} muse.ai cookies to {COOKIES_FILE}")
 
 
@@ -405,7 +410,9 @@ def event_resources(ev):
 
 
 def _local_name(path, directory):
-    name = os.path.basename(path.split("?", 1)[0].rstrip("/")) or "download"
+    name = os.path.basename(urllib.parse.unquote(path.split("?", 1)[0]).rstrip("/"))
+    if name in ("", ".", ".."):
+        name = "download"
     return os.path.join(directory, name)
 
 
@@ -897,7 +904,10 @@ def main():
             p.add_argument("title")
         p.set_defaults(fn=cmd_session_op(kind))
     sub.add_parser("wake", help="request a VM wake").set_defaults(fn=cmd_wake)
-    sub.add_parser("update", help="upgrade this install to the latest release").set_defaults(fn=cmd_update)
+    p = sub.add_parser("update", help="upgrade this install and its agent skill to the latest release")
+    p.add_argument("--skill", action="store_true",
+                   help="only install or refresh the agent skill (no package upgrade)")
+    p.set_defaults(fn=cmd_update)
     p = sub.add_parser("raw", help="call any gateway method (escape hatch)")
     p.add_argument("method"); p.add_argument("--body", default=None)
     p.add_argument("--param", action="append", default=[], help="path param k=v (repeatable)")

muse_cli-0.3.5/src/muse_cli/skill.py

@@ -0,0 +1,62 @@
+"""Install and refresh the muse-cli agent skill (SKILL.md).
+
+The skill ships inside the wheel, so it always matches the installed version.
+`install.sh` puts it in the same default location.
+"""
+import os
+import tempfile
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+
+
+def skill_path():
+    """Where coding agents look for the skill. MUSE_CLI_SKILLS matches install.sh."""
+    root = os.environ.get("MUSE_CLI_SKILLS") or os.path.expanduser("~/.agents/skills")
+    return os.path.join(root, "muse-cli", "SKILL.md")
+
+
+def bundled_skill():
+    """Path of the SKILL.md that belongs to this version, or None."""
+    candidates = (
+        os.path.join(HERE, "SKILL.md"),  # built wheel
+        os.path.join(HERE, "..", "..", "skills", "muse-cli", "SKILL.md"),  # source checkout
+    )
+    for path in candidates:
+        if os.path.isfile(path):
+            return os.path.normpath(path)
+    return None
+
+
+def sync_skill(create=False):
+    """Copy the bundled skill over the installed one.
+
+    Returns (status, path). Status is one of "updated", "installed", "current",
+    "absent" (not installed and create is False) or "no-source".
+    """
+    src = bundled_skill()
+    dest = skill_path()
+    if src is None:
+        return "no-source", dest
+    with open(src, "rb") as fh:
+        data = fh.read()
+    exists = os.path.exists(dest)
+    if exists:
+        with open(dest, "rb") as fh:
+            if fh.read() == data:
+                return "current", dest
+    elif not create:
+        return "absent", dest
+    directory = os.path.dirname(dest)
+    os.makedirs(directory, exist_ok=True)
+    mode = os.stat(dest).st_mode & 0o777 if exists else 0o644
+    fd, tmp = tempfile.mkstemp(dir=directory, prefix=".SKILL.md.")
+    try:
+        with os.fdopen(fd, "wb") as fh:
+            fh.write(data)
+        os.chmod(tmp, mode)
+        os.replace(tmp, dest)
+    except BaseException:
+        if os.path.exists(tmp):
+            os.unlink(tmp)
+        raise
+    return ("updated" if exists else "installed"), dest

{muse_cli-0.3.3 → muse_cli-0.3.5}/src/muse_cli/update.py

@@ -13,6 +13,7 @@ import time
 import urllib.request
 
 from . import __version__
+from .skill import skill_path
 
 CHECK_INTERVAL = 24 * 60 * 60
 FAIL_BACKOFF = 60 * 60
@@ -139,7 +140,27 @@ def finish_update_check(holder):
     )
 
 
-def cmd_update(_args):
+def sync_skill_cmd():
+    """Install or refresh the agent skill. Returns an exit code."""
+    from .skill import sync_skill
+    try:
+        status, path = sync_skill(create=True)
+    except OSError as e:
+        print(f"could not write the skill: {e}", file=sys.stderr)
+        return 1
+    messages = {
+        "updated": f"skill updated: {path}",
+        "installed": f"skill installed: {path}",
+        "current": f"skill already up to date: {path}",
+        "no-source": "this install has no bundled skill; run install.sh to fetch it",
+    }
+    print(messages[status], file=sys.stderr)
+    return 1 if status == "no-source" else 0
+
+
+def cmd_update(args):
+    if args.skill:
+        raise SystemExit(sync_skill_cmd())
     argv = upgrade_argv()
     if argv[0] != sys.executable and shutil.which(argv[0]) is None:
         print(f"{argv[0]} is not on PATH.", file=sys.stderr)
@@ -147,4 +168,11 @@ def cmd_update(_args):
         sys.exit(1)
     print(f"running: {upgrade_command()}", file=sys.stderr)
     import subprocess
-    raise SystemExit(subprocess.call(argv))
+    code = subprocess.call(argv)
+    if code == 0 and os.path.exists(skill_path()):
+        # The upgrade replaced this package on disk, so refresh the skill from
+        # a new interpreter that loads the new version's bundled copy.
+        refreshed = subprocess.call([sys.executable, "-m", "muse_cli", "update", "--skill"])
+        if refreshed != 0:
+            print("skill not refreshed; run `muse-cli update --skill`", file=sys.stderr)
+    raise SystemExit(code)