@foxden-app/foxclaw 0.3.17 → 0.3.19

package/skills/foxclaw/SKILL.md

@@ -21,10 +21,11 @@ Follow this order every time:
 
 1. Decide whether this is a local Mac install or a remote Mac over SSH.
 2. Confirm where the bridge repo should live. If the repo is not already present, clone it or let bootstrap clone it.
-3. Decide the Telegram mode before writing `.env`:
-   - private chat only
-   - one allowed group
-   - one allowed topic inside one group
+3. Decide the Telegram mode before writing `.env`:
+   - private chat only
+   - one allowed group
+   - one allowed topic inside one group
+   - parallel bots on one host, using comma-separated tokens and independent Codex runtimes
 4. Collect the Telegram values and filesystem paths listed below.
 5. Run the correct bootstrap script with explicit arguments.
 6. Run post-install validation.
@@ -37,7 +38,7 @@ Do not stop after "install completed" if the user asked for a working bot.
 
 Collect these values before running bootstrap:
 
-- `TG_BOT_TOKEN`
+- `TG_BOT_TOKENS` (one or more bot tokens separated by commas)
 - `TG_ALLOWED_USER_ID`
 - `DEFAULT_CWD`
 
@@ -61,20 +62,23 @@ Defaults:
 
 Telegram behavior:
 
-- private chat with `TG_ALLOWED_USER_ID` remains available even when `TG_ALLOWED_CHAT_ID` or `TG_ALLOWED_TOPIC_ID` is set
-- `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` choose the default group or topic scope; they do not disable private chat
+- private chat with `TG_ALLOWED_USER_ID` remains available even when `TG_ALLOWED_CHAT_ID` or `TG_ALLOWED_TOPIC_ID` is set
+- `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` choose the default group or topic scope; they do not disable private chat
+- when `TG_BOT_TOKENS` contains multiple bots, one FoxClaw service starts independent Codex app-servers and auth selections per bot
+- in a group with multiple configured bots, address a bot by mention, reply, or suffixed command such as `/status@botname`
 
 If `TG_ALLOWED_CHAT_ID` or `TG_ALLOWED_TOPIC_ID` is missing, read [references/telegram-setup.md](./references/telegram-setup.md) and explicitly guide the user through collecting it.
 
 ## Deployment Rules
 
-1. If the user is deploying to a second Mac, prefer one bot per device.
-2. If no unique bot token has been provided for the second Mac, bootstrap with `--no-start`.
-3. If group or topic mode is involved, read [references/telegram-setup.md](./references/telegram-setup.md) before continuing.
-4. Always explain to the user which values will be written into `.env` before starting bootstrap.
-5. After bootstrap, check `codex login status`. If authentication is missing, tell the user to run `codex login` or open `codex app` on that Mac.
-6. If the user only says "set it up" and has not given all required values, ask for the missing values directly instead of guessing Telegram IDs.
-7. If the user wants a fully usable setup, continue until first-message validation is done or clearly blocked by Telegram-side prerequisites.
+1. If the user is deploying to a second Mac, do not reuse a token that another running host is polling.
+2. On one capable host, use multiple tokens in `TG_BOT_TOKENS` when the user wants parallel Codex conversations.
+3. If no unique bot token has been provided for another host, bootstrap with `--no-start`.
+4. If group or topic mode is involved, read [references/telegram-setup.md](./references/telegram-setup.md) before continuing.
+5. Always explain to the user which values will be written into `.env` before starting bootstrap.
+6. After bootstrap, check `codex login status`. If authentication is missing, tell the user to run `codex login` or open `codex app` on that Mac.
+7. If the user only says "set it up" and has not given all required values, ask for the missing values directly instead of guessing Telegram IDs.
+8. If the user wants a fully usable setup, continue until first-message validation is done or clearly blocked by Telegram-side prerequisites.
 
 ## What To Ask The User
 
@@ -82,7 +86,7 @@ Use short direct questions when values are missing. The minimum useful checklist
 
 1. Where should the repo live on the target Mac?
 2. Which directory should be the bridge's default working directory?
-3. What is the Telegram bot token?
+3. What are the Telegram bot tokens? Use one token for a single conversation lane or multiple comma-separated tokens for parallel lanes.
 4. What is the Telegram numeric user id allowed to control the bridge?
 5. Are we using private chat only, a group, or a specific topic?
 6. If group/topic mode: what are the `TG_ALLOWED_CHAT_ID` and `TG_ALLOWED_TOPIC_ID` values?
@@ -95,7 +99,7 @@ Run:
 
 ```bash
 python3 "$CODEX_HOME/skills/foxclaw/scripts/bootstrap_host.py" \
-  --tg-bot-token "<BOT_TOKEN>" \
+  --tg-bot-tokens "<BOT_TOKEN_OR_COMMA_SEPARATED_TOKENS>" \
   --tg-allowed-user-id "<USER_ID>" \
   --default-cwd "<ABSOLUTE_CWD>" \
   --tg-allowed-chat-id "<CHAT_ID>" \
@@ -117,7 +121,7 @@ Run:
 python3 "$CODEX_HOME/skills/foxclaw/scripts/bootstrap_remote.py" \
   --ssh-host "<USER@HOST>" \
   --install-dir "<REMOTE_INSTALL_DIR>" \
-  --tg-bot-token "<BOT_TOKEN>" \
+  --tg-bot-tokens "<BOT_TOKEN_OR_COMMA_SEPARATED_TOKENS>" \
   --tg-allowed-user-id "<USER_ID>" \
   --default-cwd "<REMOTE_ABSOLUTE_CWD>" \
   --tg-allowed-chat-id "<CHAT_ID>" \
@@ -146,8 +150,8 @@ Do this whenever the bridge has been started:
 
 1. Tell the user exactly where to send the first test message:
    - private chat mode: send `/help` to the bot in private chat
-   - group mode: send `/help@botname` or `/help` in the configured default scope
-   - topic mode: send `/help` inside the configured topic, then send one plain-language message
+   - group mode: send `/help@botname` in the configured scope; in multi-bot mode all group traffic must explicitly address the intended bot
+   - topic mode: send `/help@botname` inside the configured topic, then send one message mentioning the bot
 2. After the user sends that message, verify the bridge is listening:
    - `node dist/main.js status`
    - launchd or service log if there is no reply
@@ -188,12 +192,15 @@ Use this checklist when the user asks for standard closing actions, release wrap
    - For macOS launchd, use the launchd install/start path from this skill and verify with `node dist/main.js status`.
    - Verify the running service reports the expected FoxClaw version in `status`.
    - If `doctor` fails only because `DEFAULT_CWD` is missing, report that separately; do not treat it as evidence that the service update failed.
+   - `/update` now attempts to update globally npm/pnpm-managed Codex CLI installations and refuses to restart while any configured bot runtime is busy.
 7. Publish to npm when requested:
    - Prefer GitHub Actions trusted publishing via `.github/workflows/publish.yml`: bump and commit the package version, push `main`, then push a matching `v<version>` tag. The tag version must match `package.json`.
+   - Treat `workflow_dispatch` only as a retry path from an existing matching release tag; do not manually run publishing from `main`.
    - Configure npmjs.com trusted publishing for `foxden-app/foxclaw` and workflow `publish.yml`; do not store npm tokens if OIDC trusted publishing is available.
    - Temporary fallback: store an npm automation/bypass-2FA token as the GitHub Actions secret `NPM_TOKEN`. Never print the token or commit it.
    - Check `npm whoami` and `npm view @foxden-app/foxclaw version`.
    - If the target version is already published, bump with `npm version patch --no-git-tag-version` before validation and commit.
+   - If a workflow fails before `npm publish`, inspect that failed GitHub Actions step before attributing it to npm trusted publishing.
    - Manual fallback only: run `BROWSER=true npm publish` in a TTY.
    - If npm returns `ENEEDAUTH`, report that npm publish is blocked by registry login and leave the package unreported as published.
    - Never print npm tokens or `.npmrc` auth values.

package/skills/foxclaw/references/telegram-setup.md

@@ -18,7 +18,7 @@ Rules:
 
 ## Required Values
 
-- `TG_BOT_TOKEN`
+- `TG_BOT_TOKENS` (one token, or comma-separated tokens for parallel Codex runtimes)
 - `TG_ALLOWED_USER_ID`
 - `DEFAULT_CWD`
 
@@ -29,12 +29,13 @@ Optional values:
 
 Behavior:
 
-- No `TG_ALLOWED_CHAT_ID`: private-chat mode
+- No `TG_ALLOWED_CHAT_ID`: private-chat mode
 - `TG_ALLOWED_CHAT_ID` only: the whole group becomes the default scope
 - `TG_ALLOWED_CHAT_ID` + `TG_ALLOWED_TOPIC_ID`: that topic becomes the default scope
-- Private chat with `TG_ALLOWED_USER_ID` still works in every mode above
+- Private chat with `TG_ALLOWED_USER_ID` still works in every mode above
+- Multiple tokens start independent Codex runtimes in one FoxClaw service; group messages must mention or reply to the intended bot
 
-If multiple bots share one group, keep the same `TG_ALLOWED_CHAT_ID` and give each bot a different `TG_ALLOWED_TOPIC_ID`.
+If multiple bots share one group, keep the same `TG_ALLOWED_CHAT_ID`; use explicit `@botname` mentions or replies. Separate topics are still useful for organization.
 
 ## Path Guidance
 

package/skills/foxclaw/scripts/bootstrap_host.py

@@ -24,8 +24,9 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--repo-url")
     parser.add_argument("--repo-ref")
     parser.add_argument("--install-dir")
-    parser.add_argument("--default-cwd")
-    parser.add_argument("--tg-bot-token")
+    parser.add_argument("--default-cwd")
+    parser.add_argument("--tg-bot-tokens")
+    parser.add_argument("--tg-bot-token")
     parser.add_argument("--tg-allowed-user-id")
     parser.add_argument("--tg-allowed-chat-id")
     parser.add_argument("--tg-allowed-topic-id")
@@ -41,8 +42,9 @@ def merged_config(args: argparse.Namespace) -> dict:
         "repo_url": REPO_URL_DEFAULT,
         "repo_ref": REPO_REF_DEFAULT,
         "install_dir": os.path.expanduser("~/foxclaw"),
-        "default_cwd": os.path.expanduser("~/foxclaw"),
-        "tg_bot_token": None,
+        "default_cwd": os.path.expanduser("~/foxclaw"),
+        "tg_bot_tokens": None,
+        "tg_bot_token": None,
         "tg_allowed_user_id": None,
         "tg_allowed_chat_id": None,
         "tg_allowed_topic_id": None,
@@ -58,8 +60,9 @@ def merged_config(args: argparse.Namespace) -> dict:
         "repo_url": args.repo_url,
         "repo_ref": args.repo_ref,
         "install_dir": args.install_dir,
-        "default_cwd": args.default_cwd,
-        "tg_bot_token": args.tg_bot_token,
+        "default_cwd": args.default_cwd,
+        "tg_bot_tokens": args.tg_bot_tokens,
+        "tg_bot_token": args.tg_bot_token,
         "tg_allowed_user_id": args.tg_allowed_user_id,
         "tg_allowed_chat_id": args.tg_allowed_chat_id,
         "tg_allowed_topic_id": args.tg_allowed_topic_id,
@@ -252,7 +255,7 @@ def ensure_repo(config: dict) -> None:
 def write_env_file(config: dict, codex_bin: str) -> str:
     env_path = os.path.join(config["install_dir"], ".env")
     lines = [
-        f"TG_BOT_TOKEN={config['tg_bot_token']}",
+        f"TG_BOT_TOKENS={config['tg_bot_tokens']}",
         f"TG_ALLOWED_USER_ID={config['tg_allowed_user_id']}",
         f"TG_ALLOWED_CHAT_ID={config['tg_allowed_chat_id'] or ''}",
         f"TG_ALLOWED_TOPIC_ID={config['tg_allowed_topic_id'] or ''}",
@@ -311,7 +314,7 @@ def main() -> None:
 
     args = parse_args()
     config = merged_config(args)
-    config["tg_bot_token"] = require(config["tg_bot_token"], "TG_BOT_TOKEN")
+    config["tg_bot_tokens"] = require(config["tg_bot_tokens"] or config["tg_bot_token"], "TG_BOT_TOKENS")
     config["tg_allowed_user_id"] = require(config["tg_allowed_user_id"], "TG_ALLOWED_USER_ID")
     os.makedirs(config["default_cwd"], exist_ok=True)
 

package/skills/foxclaw/scripts/bootstrap_remote.py

@@ -14,7 +14,8 @@ def parse_args() -> argparse.Namespace:
     parser.add_argument("--repo-ref", default="main")
     parser.add_argument("--install-dir", default="~/foxclaw")
     parser.add_argument("--default-cwd", required=True)
-    parser.add_argument("--tg-bot-token", required=True)
+    parser.add_argument("--tg-bot-tokens")
+    parser.add_argument("--tg-bot-token")
     parser.add_argument("--tg-allowed-user-id", required=True)
     parser.add_argument("--tg-allowed-chat-id")
     parser.add_argument("--tg-allowed-topic-id")
@@ -25,8 +26,11 @@ def parse_args() -> argparse.Namespace:
     return parser.parse_args()
 
 
-def main() -> None:
-    args = parse_args()
+def main() -> None:
+    args = parse_args()
+    tg_bot_tokens = args.tg_bot_tokens or args.tg_bot_token
+    if not tg_bot_tokens:
+        raise SystemExit("--tg-bot-tokens is required")
     script_path = os.path.join(os.path.dirname(__file__), "bootstrap_host.py")
     with open(script_path, "rb") as handle:
         script_bytes = handle.read()
@@ -36,7 +40,7 @@ def main() -> None:
         "repo_ref": args.repo_ref,
         "install_dir": args.install_dir,
         "default_cwd": args.default_cwd,
-        "tg_bot_token": args.tg_bot_token,
+        "tg_bot_tokens": tg_bot_tokens,
         "tg_allowed_user_id": args.tg_allowed_user_id,
         "tg_allowed_chat_id": args.tg_allowed_chat_id,
         "tg_allowed_topic_id": args.tg_allowed_topic_id,

package/skills/npm-publish/SKILL.md

@@ -73,6 +73,8 @@ Use this path when the repo has `.github/workflows/publish.yml` and npmjs.com ha
    npm view <package-name> version
    ```
 
+If the workflow provides `workflow_dispatch` as a recovery path, dispatch it only from an existing release tag whose version matches `package.json`. Do not dispatch publishing from a branch containing an unpublished version unless the workflow explicitly resolves and validates a release tag.
+
 Do not store or print npm tokens when trusted publishing is available. If trusted publishing is not configured on npmjs.com, the workflow can use a GitHub Actions secret named `NPM_TOKEN` as a temporary fallback. Store only automation/bypass-2FA tokens there, never paste tokens in chat or commit them.
 
 ### Manual Publish
@@ -124,4 +126,5 @@ Press ENTER to open in the browser...
 - If `xdg-open` fails because the environment has no browser, rerun with `BROWSER=true npm publish`.
 - If the auth link expires or the publish process exits, rerun `BROWSER=true npm publish` to generate a new link.
 - If the user provides a classic authenticator OTP instead of using the web link, publish can be retried with `npm publish --otp <code>`, but prefer web auth when the user asks for a clickable confirmation link.
+- If a GitHub Actions release fails before the `npm publish` step, such as during checkout or action download authentication, do not diagnose it as a trusted publishing rejection. Inspect the failed step and GitHub Actions status first.
 - Never print npm tokens or `.npmrc` auth values.