PyPI - muse-cli - Versions diffs - 0.2.1__tar.gz → 0.3.0__tar.gz - Mend

muse-cli 0.2.1tar.gz → 0.3.0tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

{muse_cli-0.2.1 → muse_cli-0.3.0}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: muse-cli
-Version: 0.2.1
+Version: 0.3.0
 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
@@ -66,29 +66,124 @@ A command-line client for your personal muse.ai AI agent: chat from the terminal
 uv tool install muse-cli      # or: pipx install muse-cli   /   pip install muse-cli
 ```
-Then log in and check the connection:
+The command is `muse-cli`. The name `muse` belongs to Muse Code on many machines.
+Want the agent skill too? The installer sets up the CLI and copies the skill
+to `~/.agents/skills/muse-cli`:
 ```bash
-# 1. Install agent-browser (reads cookies from Chrome):
+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`.
+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
+any other command.
+## Log in once
+muse-cli borrows the login you already have in Chrome, saves those cookies
+to `~/.config/muse-cli/cookies.txt` (mode `600`, only your user can read it),
+and after that talks to muse.ai directly. Access tokens are fetched fresh
+on every command. When a command later says the cookies expired, repeat this
+section.
+Do the steps in order. Each one checks itself before you continue.
+### 1. Install the cookie reader
+`auth export` uses [agent-browser](https://github.com/vercel-labs/agent-browser)
+to read Chrome's cookies. That package comes from npm, so you need Node.js first.
+```bash
+node --version    # if this fails, install Node.js LTS from https://nodejs.org
+                  # and open a new terminal
 npm i -g agent-browser
-# 2. Log in to https://muse.ai/ in Chrome
-# 3. Export your session (one time; re-run when it expires):
+agent-browser --version
+```
+`npm i -g` needs permission to write to npm's global bin directory. If it
+errors with `EACCES`, pick one and use it from then on: configure an
+[npm prefix you own](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally),
+or run the install with the same rights you use for other global npm tools.
+Then check `command -v agent-browser` prints a path.
+### 2. Let Chrome share cookies
+Open **Google Chrome**, the same profile you use for muse.ai. Paste this in
+the address bar:
+```
+chrome://inspect/#remote-debugging
+```
+Turn on remote debugging. The checkbox reads **Allow remote debugging for
+this browser instance**. Leave Chrome open.
+Turn this on while Chrome is already open and muse.ai is loaded. The export
+can see that window only after the switch is on. The page is in Chrome 144
+and newer.
+Stay in this window. Starting a second Chrome with
+`--remote-debugging-port` opens a different profile, and that profile does
+not have your muse.ai login.
+### 3. Be logged in, on a muse.ai tab
+In that same Chrome window, open https://muse.ai/ and log in. Leave the tab
+open. The exporter reads whichever tab is active, so the muse.ai tab has to
+be the one in front when you run the next command.
+### 4. Save the login
+```bash
 muse-cli auth export
+```
-muse-cli status
+Chrome may ask to allow the debugging connection. Click **Allow**. If the
+command already failed, run it again after you click Allow.
+Success looks like this (the count varies):
+```
+saved 12 muse.ai cookies to /home/you/.config/muse-cli/cookies.txt
 ```
-Want the agent skill too? The installer sets up the CLI and copies the skill
-to `~/.agents/skills/muse-cli`:
+The command prints the fix on the failure itself. These are the ones it
+recognizes:
+| What it says | What to do |
+| --- | --- |
+| No running Chrome / remote debugging | The switch in step 2 is off. Turn it on in the Chrome you already have open, then run the command again. |
+| No muse.ai tab | Step 3. Open https://muse.ai/ in that same window and leave the tab open. |
+| No `hatch_sess` | The tab is open and you are logged out. Log in, then export again. The cookies file already on disk is left as it was. |
+| `agent-browser` is not installed | Step 1. `node --version`, then `npm i -g agent-browser`, then a new terminal. |
+| Daemon already running | A previous attempt is stuck. `agent-browser close`, then `muse-cli auth export`. |
+### 5. Check the connection
 ```bash
-curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
+muse-cli status
 ```
-Upgrade with `uv tool upgrade muse-cli`, remove with `uv tool uninstall muse-cli`.
+You get JSON with your VM id, how many chats you have, the unread count, and
+your identity. That means install and login both worked.
+### Copy cookies by hand
-The command is `muse-cli`, not `muse`, because `muse` clashes with Muse Code
-on many machines.
+Use this when you don't have Node, or you don't want remote debugging on.
+1. In Chrome, open https://muse.ai/ and log in.
+2. Open DevTools (F12, or Ctrl+Shift+I) → **Application** → **Cookies** → `https://muse.ai`.
+3. Copy the cookies onto one line. `hatch_sess` has to be there. Separate cookies with `; ` (semicolon, space). A Netscape cookie jar (what curl writes) and a JSON object such as `{"hatch_sess": "..."}` also work.
+```bash
+mkdir -p ~/.config/muse-cli
+printf '%s\n' 'hatch_sess=the-value-from-devtools; other_cookie=other_value' > ~/.config/muse-cli/cookies.txt
+chmod 600 ~/.config/muse-cli/cookies.txt
+muse-cli status
+```
 ## Usage
@@ -166,12 +261,13 @@ pyproject.toml
 ## Setup notes
-- `auth export` reads cookies from a running Chrome via
-  [agent-browser](https://github.com/nikships/foundry) (`npm i -g agent-browser`).
-  No Chrome? Copy your `muse.ai` cookies into `~/.config/muse-cli/cookies.txt`
-  by hand (Netscape jar or `name=value; ...` format, needs `hatch_sess`).
-- Cookies live at `~/.config/muse-cli/cookies.txt` (mode 600). Access and
-  gateway tokens are fetched fresh on every run, nothing long-lived is stored.
+- Login is the [Log in once](#log-in-once) section above. Cookies live at
+  `~/.config/muse-cli/cookies.txt` (mode 600). Access and gateway tokens are
+  fetched fresh on every run.
+- `auth export` reads those cookies from Google Chrome through
+  [agent-browser](https://github.com/vercel-labs/agent-browser). Chrome has
+  to be open, with remote debugging on
+  (`chrome://inspect/#remote-debugging`) and a logged-in muse.ai tab in front.
 - Respect muse.ai's terms and rate limits. Internal APIs are unversioned and
   can change; if calls fail, re-derive from a fresh app bundle.

{muse_cli-0.2.1 → muse_cli-0.3.0}/README.md RENAMED Viewed

@@ -29,29 +29,124 @@ A command-line client for your personal muse.ai AI agent: chat from the terminal
 uv tool install muse-cli      # or: pipx install muse-cli   /   pip install muse-cli
 ```
-Then log in and check the connection:
+The command is `muse-cli`. The name `muse` belongs to Muse Code on many machines.
+Want the agent skill too? The installer sets up the CLI and copies the skill
+to `~/.agents/skills/muse-cli`:
 ```bash
-# 1. Install agent-browser (reads cookies from Chrome):
+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`.
+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
+any other command.
+## Log in once
+muse-cli borrows the login you already have in Chrome, saves those cookies
+to `~/.config/muse-cli/cookies.txt` (mode `600`, only your user can read it),
+and after that talks to muse.ai directly. Access tokens are fetched fresh
+on every command. When a command later says the cookies expired, repeat this
+section.
+Do the steps in order. Each one checks itself before you continue.
+### 1. Install the cookie reader
+`auth export` uses [agent-browser](https://github.com/vercel-labs/agent-browser)
+to read Chrome's cookies. That package comes from npm, so you need Node.js first.
+```bash
+node --version    # if this fails, install Node.js LTS from https://nodejs.org
+                  # and open a new terminal
 npm i -g agent-browser
-# 2. Log in to https://muse.ai/ in Chrome
-# 3. Export your session (one time; re-run when it expires):
+agent-browser --version
+```
+`npm i -g` needs permission to write to npm's global bin directory. If it
+errors with `EACCES`, pick one and use it from then on: configure an
+[npm prefix you own](https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally),
+or run the install with the same rights you use for other global npm tools.
+Then check `command -v agent-browser` prints a path.
+### 2. Let Chrome share cookies
+Open **Google Chrome**, the same profile you use for muse.ai. Paste this in
+the address bar:
+```
+chrome://inspect/#remote-debugging
+```
+Turn on remote debugging. The checkbox reads **Allow remote debugging for
+this browser instance**. Leave Chrome open.
+Turn this on while Chrome is already open and muse.ai is loaded. The export
+can see that window only after the switch is on. The page is in Chrome 144
+and newer.
+Stay in this window. Starting a second Chrome with
+`--remote-debugging-port` opens a different profile, and that profile does
+not have your muse.ai login.
+### 3. Be logged in, on a muse.ai tab
+In that same Chrome window, open https://muse.ai/ and log in. Leave the tab
+open. The exporter reads whichever tab is active, so the muse.ai tab has to
+be the one in front when you run the next command.
+### 4. Save the login
+```bash
 muse-cli auth export
+```
-muse-cli status
+Chrome may ask to allow the debugging connection. Click **Allow**. If the
+command already failed, run it again after you click Allow.
+Success looks like this (the count varies):
+```
+saved 12 muse.ai cookies to /home/you/.config/muse-cli/cookies.txt
 ```
-Want the agent skill too? The installer sets up the CLI and copies the skill
-to `~/.agents/skills/muse-cli`:
+The command prints the fix on the failure itself. These are the ones it
+recognizes:
+| What it says | What to do |
+| --- | --- |
+| No running Chrome / remote debugging | The switch in step 2 is off. Turn it on in the Chrome you already have open, then run the command again. |
+| No muse.ai tab | Step 3. Open https://muse.ai/ in that same window and leave the tab open. |
+| No `hatch_sess` | The tab is open and you are logged out. Log in, then export again. The cookies file already on disk is left as it was. |
+| `agent-browser` is not installed | Step 1. `node --version`, then `npm i -g agent-browser`, then a new terminal. |
+| Daemon already running | A previous attempt is stuck. `agent-browser close`, then `muse-cli auth export`. |
+### 5. Check the connection
 ```bash
-curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
+muse-cli status
 ```
-Upgrade with `uv tool upgrade muse-cli`, remove with `uv tool uninstall muse-cli`.
+You get JSON with your VM id, how many chats you have, the unread count, and
+your identity. That means install and login both worked.
+### Copy cookies by hand
-The command is `muse-cli`, not `muse`, because `muse` clashes with Muse Code
-on many machines.
+Use this when you don't have Node, or you don't want remote debugging on.
+1. In Chrome, open https://muse.ai/ and log in.
+2. Open DevTools (F12, or Ctrl+Shift+I) → **Application** → **Cookies** → `https://muse.ai`.
+3. Copy the cookies onto one line. `hatch_sess` has to be there. Separate cookies with `; ` (semicolon, space). A Netscape cookie jar (what curl writes) and a JSON object such as `{"hatch_sess": "..."}` also work.
+```bash
+mkdir -p ~/.config/muse-cli
+printf '%s\n' 'hatch_sess=the-value-from-devtools; other_cookie=other_value' > ~/.config/muse-cli/cookies.txt
+chmod 600 ~/.config/muse-cli/cookies.txt
+muse-cli status
+```
 ## Usage
@@ -129,12 +224,13 @@ pyproject.toml
 ## Setup notes
-- `auth export` reads cookies from a running Chrome via
-  [agent-browser](https://github.com/nikships/foundry) (`npm i -g agent-browser`).
-  No Chrome? Copy your `muse.ai` cookies into `~/.config/muse-cli/cookies.txt`
-  by hand (Netscape jar or `name=value; ...` format, needs `hatch_sess`).
-- Cookies live at `~/.config/muse-cli/cookies.txt` (mode 600). Access and
-  gateway tokens are fetched fresh on every run, nothing long-lived is stored.
+- Login is the [Log in once](#log-in-once) section above. Cookies live at
+  `~/.config/muse-cli/cookies.txt` (mode 600). Access and gateway tokens are
+  fetched fresh on every run.
+- `auth export` reads those cookies from Google Chrome through
+  [agent-browser](https://github.com/vercel-labs/agent-browser). Chrome has
+  to be open, with remote debugging on
+  (`chrome://inspect/#remote-debugging`) and a logged-in muse.ai tab in front.
 - Respect muse.ai's terms and rate limits. Internal APIs are unversioned and
   can change; if calls fail, re-derive from a fresh app bundle.

{muse_cli-0.2.1 → muse_cli-0.3.0}/docs/PROTOCOL.md RENAMED Viewed

@@ -74,6 +74,9 @@ chat / feed / goals / ideas / sessions / ...
   delete: `{method: "/api/session/<op>", session_id}`.
 - `api.idea-cards.execute`: `{ideaCardId, mode: "full"}` plus path param.
 - POSTs to muse.ai need browser `Sec-Fetch-*` headers or they return 403.
-- `auth export` must focus a muse.ai tab before reading cookies (the export
-  follows the active tab) and must never overwrite a working jar without a
-  `hatch_sess` in the new one.
+- `auth export` reads cookies from the user's own Google Chrome through
+  agent-browser `--auto-connect`. Chrome 144+ shares that profile only after
+  remote debugging is enabled at `chrome://inspect/#remote-debugging`. The
+  export follows the active tab, so a muse.ai tab has to be focused first,
+  and it must never overwrite a working jar without a `hatch_sess` in the
+  new one. A freshly launched browser has no login; do not fall back to one.

muse_cli-0.3.0/skills/muse-cli/SKILL.md ADDED Viewed

@@ -0,0 +1,180 @@
+---
+name: muse-cli
+description: Manage a personal muse.ai agent from the terminal (send messages, read chats, watch live events, feed/goals/ideas/sessions). Use when asked to message, check, or automate someone's Muse personal AI, work with muse.ai chats/threads/feed/goals outside the browser, or when the muse-cli tool itself needs installing or auth setup.
+---
+# muse-cli: drive a muse.ai personal agent from the terminal
+Assume a bare machine: only this skill is present. No repo clone, no
+dependencies, no auth. Work top to bottom; stop at the first step that
+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.
+## 1. Install
+```bash
+curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
+```
+This installs the CLI from PyPI with `uv tool install muse-cli` (its own
+isolated environment) and this skill (to `~/.agents/skills/muse-cli`). CLI
+only? `uv tool install muse-cli`, `pipx install muse-cli`, or
+`pip install muse-cli` all work. The command is `muse-cli` (`muse` clashes
+with Muse Code, don't use it). Verify before continuing:
+```bash
+command -v muse-cli
+muse-cli --help >/dev/null && echo cli-ok   # proves the install + deps resolve
+```
+## 2. Auth
+The CLI stores the user's muse.ai browser login at
+`~/.config/muse-cli/cookies.txt` (mode 0600). Chrome hides those cookies
+until remote debugging is on. Walk the user through the steps below and wait
+for them. Do not run `muse-cli auth export` before they say the Chrome
+switch is on and a logged-in muse.ai tab is open.
+Access and gateway tokens are fetched fresh on every run; only cookies
+persist. When a later command fails with `auth error`, the cookies expired:
+repeat 2b (or 2c).
+### 2a. Cookie reader
+```bash
+command -v node >/dev/null && node --version
+command -v npm >/dev/null && npm --version
+command -v agent-browser >/dev/null && agent-browser --version
+```
+If `agent-browser` is missing and `npm` works:
+```bash
+npm i -g agent-browser
+agent-browser --version   # must print a version
+command -v agent-browser  # must print a path
+```
+`EACCES` from `npm i -g` means npm cannot write its global bin directory.
+Stop and tell the user. They fix it with an npm prefix they own
+(https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally)
+or by installing with the same rights they use for other global npm tools.
+Do not sudo unless they tell you to.
+If `node` or `npm` is missing, stop. Tell them to install Node.js LTS from
+https://nodejs.org, open a new terminal, and come back. Offer 2c if they
+would rather not install Node.
+### 2b. Chrome, then export
+Tell the user to do all of this in the Google Chrome window they already
+use for muse.ai. Needs Chrome 144 or newer. Wait until they confirm:
+1. Address bar: `chrome://inspect/#remote-debugging`
+2. Turn on remote debugging ("Allow remote debugging for this browser instance").
+3. Open https://muse.ai/ and log in. Leave that tab in front. The export
+   reads the active tab.
+Then:
+```bash
+muse-cli auth export
+test -s ~/.config/muse-cli/cookies.txt && echo auth-ok
+```
+If Chrome shows an Allow prompt, they click Allow. If the command failed
+before that click, run it once more.
+Success is a line like `saved N muse.ai cookies to ~/.config/muse-cli/cookies.txt`.
+If it fails, the CLI prints the next step. Map it like this, and do not retry
+in a loop:
+- "No running Chrome" or "remote-debugging-port": the switch in step 2 is
+  off, or they are in a different Chrome. Send them back to the steps above.
+  Do not tell them to launch Chrome with `--remote-debugging-port`. That
+  opens another profile, and it does not have their muse.ai login.
+- "no muse.ai tab": Chrome connected. They still need https://muse.ai/ open
+  and in front in that same window.
+- "no hatch_sess" / "do not include hatch_sess": the tab is open and they
+  are logged out. The cookies file on disk was kept.
+- "daemon already running": `agent-browser close`, then `muse-cli auth export` once.
+- `agent-browser` not found: back to 2a.
+### 2c. Copy cookies by hand
+Use this when Node is unavailable, or the user does not want remote debugging on.
+1. They are logged in at https://muse.ai/ in Chrome.
+2. DevTools (F12) → Application → Cookies → `https://muse.ai`.
+3. Write one line to `~/.config/muse-cli/cookies.txt`. `hatch_sess` is required.
+   Separate cookies with `; `:
+```
+hatch_sess=VALUE; other_name=other_value
+```
+A Netscape jar or `{"hatch_sess": "..."}` JSON also works.
+4. `chmod 600 ~/.config/muse-cli/cookies.txt`
+5. `test -s ~/.config/muse-cli/cookies.txt && echo auth-ok`, then `muse-cli status`.
+   Stop if status fails and report the error text.
+## 3. Verify end to end
+```bash
+muse-cli status    # VM id, chat count, unread, identity: install + auth proven
+```
+## Everyday commands
+```bash
+muse-cli threads                                        # main chat + side chats (session_ids)
+muse-cli history --limit 5                              # recent main-chat messages
+muse-cli history --thread <session-id> --limit 5        # one side chat
+muse-cli send "message" --wait 120                      # send + wait for the reply
+muse-cli send "message" --thread <session-id> --wait 0  # fire and forget to a side chat
+muse-cli watch --timeout 60                             # tail live agent events
+muse-cli feed --limit 5
+muse-cli goals
+muse-cli ideas
+muse-cli unread
+muse-cli seen <thread-id>
+```
+Management (visible side effects, confirm with the user first when destructive):
+```bash
+muse-cli feed-react <unit-id> love
+muse-cli idea-exec <idea-id>          # the agent acts on the idea (real work)
+muse-cli session-start --title "x"    # new side chat
+muse-cli session-rename <id> "title"  # also: pin, unpin, archive, unarchive, delete
+muse-cli wake
+```
+## Escape hatch
+`muse-cli raw <method> --body '{...}' [--param k=v]` calls any of the 258
+gateway methods in `routes.json`. Prefer the named commands above; use raw
+only for methods with no wrapper.
+## Gotchas
+- `send` returns `{"sent": true, "reply": {...}}`, polling history until the
+  reply lands (up to `--wait`). If `reply` is missing, the agent was slower
+  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).
+- `history` without `--thread` reads the main chat only.
+- The gateway API is unversioned. Whole classes of calls failing at once means
+  the protocol drifted: see `docs/PROTOCOL.md` for the re-derivation notes,
+  don't guess at crypto or framing.
+- 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
+  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.2.1 → muse_cli-0.3.0}/src/muse_cli/__init__.py RENAMED Viewed

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

{muse_cli-0.2.1 → muse_cli-0.3.0}/src/muse_cli/cli.py RENAMED Viewed

@@ -1,8 +1,10 @@
-"""muse-cli: CLI for your personal muse.ai agent. No browser needed (after cookie export).
+"""muse-cli: CLI for your personal muse.ai agent. No browser needed after cookie export.
-Setup:
-  1. Log in to https://muse.ai/ in Chrome (Auth profile).
-  2. muse-cli auth export   # saves session cookies locally (chmod 600)
+One-time setup (also printed by `muse-cli auth export` when a step is missing):
+  1. npm i -g agent-browser
+  2. In Chrome, open chrome://inspect/#remote-debugging and turn remote debugging on.
+  3. Open https://muse.ai/ in that same window and log in. Leave the tab open.
+  4. muse-cli auth export   # saves session cookies locally (chmod 600)
 Then: muse-cli status | muse-cli threads | muse-cli history | muse-cli send "hello" | ...
 """
@@ -15,6 +17,7 @@ import time
 from . import __version__
 from .gateway import Gateway, AuthError, GatewayError, load_cookies
+from .update import cmd_update, finish_update_check, start_update_check
 CONFIG_DIR = os.path.expanduser("~/.config/muse-cli")
 CONFIG_FILE = os.path.join(CONFIG_DIR, "config.json")
@@ -44,8 +47,11 @@ def load_config():
 def connect(cfg):
     if not os.path.exists(cfg["cookies_file"]):
-        raise AuthError(f"no cookies at {cfg['cookies_file']}; log in to https://muse.ai/ "
-                        "in Chrome, then run `muse-cli auth export`")
+        raise AuthError(
+            f"no cookies at {cfg['cookies_file']}. Run `muse-cli auth export` "
+            "and follow the steps it prints: turn on Chrome remote debugging at "
+            "chrome://inspect/#remote-debugging, open https://muse.ai/ in that "
+            "window, then export again.")
     cookies = load_cookies(cfg["cookies_file"])
     if not cookies.strip():
         raise AuthError(f"cookies file {cfg['cookies_file']} is empty; run `muse-cli auth export`")
@@ -56,70 +62,175 @@ def out(obj):
     print(json.dumps(obj, indent=2, ensure_ascii=False))
+def _parse_browser_doc(stdout):
+    """agent-browser prints a JSON envelope, sometimes after a warning line."""
+    text = (stdout or "").strip()
+    if not text:
+        return None
+    blobs = [text]
+    for line in reversed(text.splitlines()):
+        line = line.strip()
+        if line.startswith("{") and line not in blobs:
+            blobs.append(line)
+    for blob in blobs:
+        try:
+            doc = json.loads(blob)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(doc, dict):
+            return doc
+    return None
 def _browser_run(argv):
-    """Run agent-browser, parsing its JSON envelope. NOTE: it exits 0 even
-    on failure, reporting {"success": false, "error": ...} on stdout."""
+    """Run agent-browser and return the JSON envelope's data.
+    On failure the tool prints {"success": false, "error": ...}. Some versions
+    exit 0 anyway, some exit non-zero; trust the envelope when it is there.
+    """
     import subprocess
     r = subprocess.run(argv, capture_output=True, text=True)
-    if r.returncode != 0:
-        raise RuntimeError((r.stderr or r.stdout)[:200] or f"exit {r.returncode}")
-    try:
-        doc = json.loads(r.stdout)
-    except json.JSONDecodeError:
-        raise RuntimeError((r.stdout or r.stderr)[:200] or "empty output")
+    doc = _parse_browser_doc(r.stdout) or _parse_browser_doc(r.stderr)
     if isinstance(doc, dict) and doc.get("success") is False:
-        raise RuntimeError(str(doc.get("error") or "unknown error")[:200])
+        raise RuntimeError(str(doc.get("error") or "unknown error")[:400])
+    if r.returncode != 0 or doc is None:
+        msg = (r.stderr or r.stdout or "").strip()
+        raise RuntimeError(msg[:400] or f"exit {r.returncode}")
     return doc.get("data", {}) if isinstance(doc, dict) else doc
-def _browser_cookies(headed):
-    """Read the cookie jar via agent-browser. Headed auto-connect attaches
-    to the user's real Chrome; plain mode uses a fresh browser (no login)."""
-    base = ["agent-browser"] + (["--headed", "--auto-connect"] if headed else [])
-    if shutil.which("agent-browser") is None:
-        print("agent-browser not found; install it with: npm i -g agent-browser", file=sys.stderr)
-        print("alternative: export cookies by hand, see README Setup notes.", file=sys.stderr)
-        sys.exit(1)
+def _export_error_kind(err):
+    e = (err or "").lower()
+    if "daemon already running" in e:
+        return "daemon"
+    if ("no running chrome" in e or "remote-debugging" in e
+            or "auto-launch failed" in e or "auto-connect" in e):
+        return "debug"
+    if err == "no muse.ai tab open in Chrome":
+        return "tab"
+    return "other"
+def _print_hand_copy():
+    print("Copy the login by hand instead:", file=sys.stderr)
+    print("  1. In Chrome, open https://muse.ai/ and log in.", file=sys.stderr)
+    print("  2. DevTools (F12) → Application → Cookies → https://muse.ai", file=sys.stderr)
+    print("  3. Write one line to ~/.config/muse-cli/cookies.txt", file=sys.stderr)
+    print("       hatch_sess=VALUE; other_name=other_value", file=sys.stderr)
+    print("     hatch_sess is required. Separate cookies with '; '.", file=sys.stderr)
+    print("  4. chmod 600 ~/.config/muse-cli/cookies.txt", file=sys.stderr)
+    print("  5. muse-cli status", file=sys.stderr)
+def _print_chrome_debug_steps():
+    print("Turn on remote debugging so muse-cli can read the muse.ai cookies.", file=sys.stderr)
+    print("Do this in the Chrome window where you already use muse.ai:", file=sys.stderr)
+    print(file=sys.stderr)
+    print("  1. Open chrome://inspect/#remote-debugging", file=sys.stderr)
+    print("  2. Turn on remote debugging", file=sys.stderr)
+    print('     ("Allow remote debugging for this browser instance").', file=sys.stderr)
+    print("  3. Open https://muse.ai/ and log in. Leave that tab open.", file=sys.stderr)
+    print("  4. Run `muse-cli auth export` again.", file=sys.stderr)
+    print("     If Chrome asks to allow the connection, click Allow.", file=sys.stderr)
+    print("     If this command already failed, run it again after Allow.", file=sys.stderr)
+    print(file=sys.stderr)
+    print("Stay in that same window. A second Chrome started with", file=sys.stderr)
+    print("--remote-debugging-port is another profile and has no muse.ai login.", file=sys.stderr)
+    print(file=sys.stderr)
+    print("Success looks like:", file=sys.stderr)
+    print(f"  saved N muse.ai cookies to {COOKIES_FILE}", file=sys.stderr)
+    print(file=sys.stderr)
+    _print_hand_copy()
+def _print_need_agent_browser():
+    print("agent-browser is not installed, so muse-cli cannot read Chrome's cookies.", file=sys.stderr)
+    print(file=sys.stderr)
+    print("  1. Install Node.js LTS if `node --version` fails: https://nodejs.org", file=sys.stderr)
+    print("  2. Open a new terminal, then:", file=sys.stderr)
+    print("       npm i -g agent-browser", file=sys.stderr)
+    print("       agent-browser --version", file=sys.stderr)
+    print("  3. Run `muse-cli auth export` again and follow the Chrome steps it prints.", file=sys.stderr)
+    print(file=sys.stderr)
+    _print_hand_copy()
+def _print_export_failure(err):
+    kind = _export_error_kind(err)
+    print("cookie export failed.", file=sys.stderr)
+    if kind == "daemon":
+        print("agent-browser is still running from an earlier attempt. Close it, then retry:", file=sys.stderr)
+        print("  agent-browser close", file=sys.stderr)
+        print("  muse-cli auth export", file=sys.stderr)
+        print(file=sys.stderr)
+        _print_chrome_debug_steps()
+        return
+    if kind == "debug":
+        _print_chrome_debug_steps()
+        return
+    if kind == "tab":
+        print("Chrome is connected, but no muse.ai tab is open.", file=sys.stderr)
+        print("Open https://muse.ai/, log in, leave that tab open, and run", file=sys.stderr)
+        print("`muse-cli auth export` again.", file=sys.stderr)
+        return
+    print(err, file=sys.stderr)
+    print(file=sys.stderr)
+    print("Check both of these, then run `muse-cli auth export` again:", file=sys.stderr)
+    print("  - chrome://inspect/#remote-debugging has remote debugging on", file=sys.stderr)
+    print("  - https://muse.ai/ is open in that same Chrome and you are logged in", file=sys.stderr)
+    print(file=sys.stderr)
+    _print_hand_copy()
+def _browser_cookies():
+    """Read muse.ai cookies from the user's Chrome via agent-browser.
+    Auto-connect attaches to the real profile. A fresh browser has no login,
+    so this never falls back to launching one.
+    """
+    base = ["agent-browser", "--headed", "--auto-connect"]
     last_err = "unknown error"
-    for _ in range(3):
+    for attempt in range(3):
         try:
-            if headed:
-                # Cookies follow the active tab: focus a muse.ai tab first,
-                # else the export comes back empty even when logged in.
-                data = _browser_run(base + ["tab", "list", "--json"])
-                tabs = data.get("tabs", []) if isinstance(data, dict) else []
-                muse_tabs = [t for t in tabs
-                             if isinstance(t, dict) and "muse.ai" in (t.get("url") or "")
-                             and (t.get("id") or t.get("tabId"))]
-                if not muse_tabs:
-                    return None, "no muse.ai tab open in Chrome"
-                _browser_run(base + ["tab", muse_tabs[0].get("id") or muse_tabs[0]["tabId"]])
+            # Cookies follow the active tab: focus a muse.ai tab first,
+            # else the export comes back empty even when logged in.
+            data = _browser_run(base + ["tab", "list", "--json"])
+            tabs = data.get("tabs", []) if isinstance(data, dict) else []
+            muse_tabs = [t for t in tabs
+                         if isinstance(t, dict) and "muse.ai" in (t.get("url") or "")
+                         and (t.get("id") or t.get("tabId"))]
+            if not muse_tabs:
+                return None, "no muse.ai tab open in Chrome"
+            _browser_run(base + ["tab", muse_tabs[0].get("id") or muse_tabs[0]["tabId"]])
             data = _browser_run(base + ["cookies", "get", "--json"])
             jar = data.get("cookies", []) if isinstance(data, dict) else []
             return [c for c in jar if "muse.ai" in c.get("domain", "")], None
         except RuntimeError as e:
             last_err = str(e)
+            # Missing debug port and a stuck daemon will not change on retry.
+            if _export_error_kind(last_err) in ("debug", "daemon") or attempt == 2:
+                return None, last_err
             time.sleep(2)
     return None, last_err
 def cmd_auth_export(_args):
     os.makedirs(CONFIG_DIR, exist_ok=True)
-    jar, err = _browser_cookies(headed=True)
-    if jar is None and err != "no muse.ai tab open in Chrome":
-        # Headed attach failed (no Chrome, old agent-browser, ...): a plain
-        # browser shares no login, so this is a last resort at best.
-        jar, err = _browser_cookies(headed=False)
+    if shutil.which("agent-browser") is None:
+        _print_need_agent_browser()
+        sys.exit(1)
+    print("Reading muse.ai cookies from Chrome...", file=sys.stderr)
+    jar, err = _browser_cookies()
     if jar is None:
-        print(f"cookie export failed: {err}", file=sys.stderr)
-        print("is Chrome running with muse.ai open?", file=sys.stderr)
-        print("alternative: export cookies by hand, see README Setup.", file=sys.stderr)
+        _print_export_failure(err)
         sys.exit(1)
     # Never clobber a working login with an empty or logged-out jar.
     if not any(c["name"] == "hatch_sess" for c in jar):
-        print("refusing to overwrite cookies: no hatch_sess in export "
-              "(are you logged in to muse.ai?). Existing file left intact.",
+        print("Chrome answered, but the cookies do not include hatch_sess.", file=sys.stderr)
+        print("That cookie is set only after you log in at https://muse.ai/.", file=sys.stderr)
+        print("Log in, leave the muse.ai tab open, and run `muse-cli auth export` again.",
               file=sys.stderr)
+        print(f"Left {COOKIES_FILE} unchanged.", file=sys.stderr)
         sys.exit(1)
     lines = ["# Netscape HTTP Cookie File"]
     for c in jar:
@@ -476,7 +587,32 @@ def main():
     sub = ap.add_subparsers(dest="cmd", required=True)
     p = sub.add_parser("auth", help="auth helpers"); a = p.add_subparsers(dest="op", required=True)
-    a.add_parser("export", help="export Chrome session cookies for the CLI").set_defaults(fn=cmd_auth_export)
+    export_help = (
+        "Copy your muse.ai login out of Google Chrome into\n"
+        "~/.config/muse-cli/cookies.txt (mode 600).\n"
+        "\n"
+        "Chrome shares those cookies only after remote debugging is on.\n"
+        "In the Chrome window you already use for muse.ai:\n"
+        "\n"
+        "  1. Open chrome://inspect/#remote-debugging\n"
+        "  2. Turn on remote debugging\n"
+        '     ("Allow remote debugging for this browser instance")\n'
+        "  3. Open https://muse.ai/ and log in. Leave that tab open.\n"
+        "  4. Run this command. If Chrome asks to allow the connection,\n"
+        "     click Allow, then run it again if it failed before the click.\n"
+        "\n"
+        "Requires agent-browser: npm i -g agent-browser\n"
+        "(install Node.js LTS from https://nodejs.org first if npm is missing).\n"
+        "\n"
+        "Stay in that same Chrome. Starting another Chrome with\n"
+        "--remote-debugging-port uses a different profile and has no muse.ai login."
+    )
+    a.add_parser(
+        "export",
+        help="copy the muse.ai login out of Chrome (remote debugging must be on)",
+        description=export_help,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    ).set_defaults(fn=cmd_auth_export)
     sub.add_parser("status", help="VM, session count, unread, identity").set_defaults(fn=cmd_status)
     p = sub.add_parser("threads", help="list chats and side chats")
@@ -520,23 +656,30 @@ 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("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)")
     p.add_argument("--timeout", type=int, default=30); p.set_defaults(fn=cmd_raw)
     args = ap.parse_args()
+    # A piped command prints JSON. The notice stays off unless both streams
+    # are a terminal, and `update` is already doing the upgrade.
+    notice = None if args.cmd == "update" else start_update_check()
     try:
-        args.fn(args)
-    except AuthError as e:
-        print(f"auth error: {e}", file=sys.stderr)
-        sys.exit(2)
-    except GatewayError as e:
-        print(f"gateway error: {e}", file=sys.stderr)
-        sys.exit(3)
-    except TimeoutError as e:
-        print(f"timeout: {e}", file=sys.stderr)
-        sys.exit(4)
+        try:
+            args.fn(args)
+        except AuthError as e:
+            print(f"auth error: {e}", file=sys.stderr)
+            sys.exit(2)
+        except GatewayError as e:
+            print(f"gateway error: {e}", file=sys.stderr)
+            sys.exit(3)
+        except TimeoutError as e:
+            print(f"timeout: {e}", file=sys.stderr)
+            sys.exit(4)
+    finally:
+        finish_update_check(notice)
 if __name__ == "__main__":

muse_cli-0.3.0/src/muse_cli/update.py ADDED Viewed

@@ -0,0 +1,150 @@
+"""Tell an interactive user when a newer muse-cli is on PyPI.
+Same shape as `gh` and `uv`: look at most once a day, never on a pipe or in
+CI, never fail the command, and print the upgrade command instead of
+replacing the install. uv tools do not upgrade themselves.
+"""
+import json
+import os
+import shutil
+import sys
+import threading
+import time
+import urllib.request
+from . import __version__
+CHECK_INTERVAL = 24 * 60 * 60
+FAIL_BACKOFF = 60 * 60
+STATE_FILE = os.path.expanduser("~/.config/muse-cli/update.json")
+PYPI_URL = "https://pypi.org/pypi/muse-cli/json"
+def version_key(value):
+    """Stable x.y.z as a tuple. Pre-releases and junk compare as absent."""
+    text = str(value).strip().lstrip("v").split("+", 1)[0]
+    if not text or any(c.isalpha() for c in text):
+        return None
+    try:
+        return tuple(int(part) for part in text.split("."))
+    except ValueError:
+        return None
+def is_newer(latest, current):
+    new, old = version_key(latest), version_key(current)
+    return bool(new and old and new > old)
+def upgrade_argv():
+    """The upgrade command for this install. uv tool, pipx, or pip."""
+    prefix = os.path.realpath(sys.prefix)
+    sep = os.sep
+    if f"{sep}uv{sep}tools{sep}" in prefix:
+        return ["uv", "tool", "upgrade", "muse-cli"]
+    if f"{sep}pipx{sep}" in prefix:
+        return ["pipx", "upgrade", "muse-cli"]
+    return [sys.executable, "-m", "pip", "install", "-U", "muse-cli"]
+def upgrade_command():
+    return " ".join(upgrade_argv())
+def _should_check():
+    if os.environ.get("MUSE_NO_UPDATE_CHECK"):
+        return False
+    if os.environ.get("CI"):
+        return False
+    try:
+        return sys.stdout.isatty() and sys.stderr.isatty()
+    except (AttributeError, ValueError):
+        return False
+def _load_state():
+    try:
+        with open(STATE_FILE) as fh:
+            data = json.load(fh)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+def _save_state(data):
+    try:
+        os.makedirs(os.path.dirname(STATE_FILE), exist_ok=True)
+        tmp = STATE_FILE + ".tmp"
+        with open(tmp, "w") as fh:
+            json.dump(data, fh)
+        os.replace(tmp, STATE_FILE)
+    except OSError:
+        pass
+def _fetch_latest():
+    req = urllib.request.Request(
+        PYPI_URL,
+        headers={"Accept": "application/json", "User-Agent": f"muse-cli/{__version__}"},
+    )
+    with urllib.request.urlopen(req, timeout=2) as resp:
+        payload = json.loads(resp.read().decode())
+    return str(payload["info"]["version"])
+def start_update_check():
+    """Begin a check, or return a cached result. None when the notice is off."""
+    if not _should_check():
+        return None
+    state = _load_state()
+    latest = state.get("latest") or ""
+    checked = float(state.get("checked_at") or 0)
+    if latest and time.time() - checked < CHECK_INTERVAL:
+        return {"latest": latest}
+    holder = {"latest": None, "thread": None}
+    def work():
+        try:
+            found = _fetch_latest()
+            holder["latest"] = found
+            _save_state({"checked_at": time.time(), "latest": found})
+        except Exception:
+            # Offline or PyPI blip: try again in an hour, keep any known version.
+            holder["latest"] = latest or None
+            _save_state({
+                "checked_at": time.time() - CHECK_INTERVAL + FAIL_BACKOFF,
+                "latest": latest,
+            })
+    thread = threading.Thread(target=work, daemon=True)
+    holder["thread"] = thread
+    thread.start()
+    return holder
+def finish_update_check(holder):
+    """Print the notice on stderr once the check has had a moment to finish."""
+    if not holder:
+        return
+    thread = holder.get("thread")
+    if thread is not None:
+        thread.join(timeout=1.5)
+    latest = holder.get("latest")
+    if not is_newer(latest, __version__):
+        return
+    print(
+        f"\nA new release of muse-cli is available: {__version__} → {latest}\n"
+        f"To upgrade, run: {upgrade_command()}\n",
+        file=sys.stderr,
+    )
+def cmd_update(_args):
+    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)
+        print(f"To upgrade, run: {upgrade_command()}", file=sys.stderr)
+        sys.exit(1)
+    print(f"running: {upgrade_command()}", file=sys.stderr)
+    import subprocess
+    raise SystemExit(subprocess.call(argv))

muse_cli-0.2.1/skills/muse-cli/SKILL.md DELETED Viewed

@@ -1,104 +0,0 @@
----
-name: muse-cli
-description: Manage a personal muse.ai agent from the terminal (send messages, read chats, watch live events, feed/goals/ideas/sessions). Use when asked to message, check, or automate someone's Muse personal AI, work with muse.ai chats/threads/feed/goals outside the browser, or when the muse-cli tool itself needs installing or auth setup.
----
-# muse-cli: drive a muse.ai personal agent from the terminal
-Assume a bare machine: only this skill is present. No repo clone, no
-dependencies, no auth. Work top to bottom; stop at the first step that
-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.
-## 1. Install
-```bash
-curl -fsSL https://raw.githubusercontent.com/nikships/muse-cli/main/install.sh | bash
-```
-This installs the CLI from PyPI with `uv tool install muse-cli` (its own
-isolated environment) and this skill (to `~/.agents/skills/muse-cli`). CLI
-only? `uv tool install muse-cli`, `pipx install muse-cli`, or
-`pip install muse-cli` all work. The command is `muse-cli` (`muse` clashes
-with Muse Code, don't use it). Verify before continuing:
-```bash
-command -v muse-cli
-muse-cli --help >/dev/null && echo cli-ok   # proves the install + deps resolve
-```
-## 2. Auth
-The user must be logged in to https://muse.ai/ in Chrome first. `auth export`
-reads Chrome's cookies through
-[agent-browser](https://github.com/nikships/foundry); install it if missing,
-then:
-```bash
-npm i -g agent-browser   # one-time; skip if already installed
-muse-cli auth export     # saves muse.ai cookies to ~/.config/muse-cli/cookies.txt (0600)
-test -s ~/.config/muse-cli/cookies.txt && echo auth-ok
-```
-No Chrome? Copy the `muse.ai` cookies by hand (DevTools → Application →
-Cookies; needs `hatch_sess`) into `~/.config/muse-cli/cookies.txt` as
-Netscape-jar or `name=value; ...` text.
-Access and gateway tokens are fetched fresh on every run; only cookies
-persist. When commands later fail with `auth error`, cookies expired:
-re-run `auth export`.
-## 3. Verify end to end
-```bash
-muse-cli status    # VM id, chat count, unread, identity: install + auth proven
-```
-## Everyday commands
-```bash
-muse-cli threads                                        # main chat + side chats (session_ids)
-muse-cli history --limit 5                              # recent main-chat messages
-muse-cli history --thread <session-id> --limit 5        # one side chat
-muse-cli send "message" --wait 120                      # send + wait for the reply
-muse-cli send "message" --thread <session-id> --wait 0  # fire and forget to a side chat
-muse-cli watch --timeout 60                             # tail live agent events
-muse-cli feed --limit 5
-muse-cli goals
-muse-cli ideas
-muse-cli unread
-muse-cli seen <thread-id>
-```
-Management (visible side effects, confirm with the user first when destructive):
-```bash
-muse-cli feed-react <unit-id> love
-muse-cli idea-exec <idea-id>          # the agent acts on the idea (real work)
-muse-cli session-start --title "x"    # new side chat
-muse-cli session-rename <id> "title"  # also: pin, unpin, archive, unarchive, delete
-muse-cli wake
-```
-## Escape hatch
-`muse-cli raw <method> --body '{...}' [--param k=v]` calls any of the 258
-gateway methods in `routes.json`. Prefer the named commands above; use raw
-only for methods with no wrapper.
-## Gotchas
-- `send` returns `{"sent": true, "reply": {...}}`, polling history until the
-  reply lands (up to `--wait`). If `reply` is missing, the agent was slower
-  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).
-- `history` without `--thread` reads the main chat only.
-- The gateway API is unversioned. Whole classes of calls failing at once means
-  the protocol drifted: see `docs/PROTOCOL.md` for the re-derivation notes,
-  don't guess at crypto or framing.
-- Respect rate limits. Writes (send, react, execute, session ops) act as the
-  user in their agent: announce them before running, never loop them.