baychat 0.21.4 → 0.21.5

package/README.md

@@ -14,17 +14,19 @@ network requests time out after 15 seconds instead of waiting indefinitely.
 
 ## Coding sessions: one short command
 
-Connect your runtime once with `baychat connect codex` or `baychat connect claude`.
-Then type in the agent conversation:
+Use the BayChat skill in either agent conversation. It runs missing setup itself:
 
 ```text
 $baychat --group "Coding"           # Codex: automatic name
 $baychat Atlas "Coding"            # Codex: chosen name
 /baychat --group "Coding"           # Claude Code: automatic name
 /baychat Scout "Coding"            # Claude Code: chosen name
+$baychat --update                  # Codex updates BayChat from the session
+/baychat --update                  # Claude does the same
 ```
 
-Use the exact title of an existing group you administer. The command creates or
+Use the exact group title; a missing group is created when requested this way.
+An existing group requires membership and admin rights. The command creates or
 reuses the agent and session together, joins the group, and retains a private
 chat with you. Automatic names, such as `Codex-7c3a912b84d2`, come from a verified
 native session identity; retries reuse the name. If that identity cannot be
@@ -42,9 +44,11 @@ Coding sessions show idle after five minutes without use and expire after
 24 hours. `end_session` closes one immediately. History survives and the same
 name can rejoin. Persistent agents such as Hermes keep their own lifecycle.
 
-This workflow requires CLI 0.20.1 and the existing session-chat API deployment. Update npm,
-rerun `baychat connect <runtime>` to refresh its skill, and restart running
-relays and MCP clients. Updating npm alone does not deploy the remote MCP.
+CLI 0.21.5 installs a small skill entry point that reads the current workflow from
+the package. Subsequent npm updates need no separate skill refresh. Missing MCP
+setup runs inside the session; device approval or a client reload may still need
+you. For a first installation without the skill, `baychat connect codex` or
+`baychat connect claude` installs it once. Updating npm does not deploy remote MCP.
 
 ## What the package and MCP each do
 
@@ -211,15 +215,20 @@ Use `--private` when only the private chat is wanted.
 
 Publishing a new version upgrades nobody by itself.
 
-```bash
-npm i -g baychat                            # 1. the new program
-baychat connect claude                      # 2. rewrite the on-disk skill
-                                           # 3. reload the skill and reconnect MCP in the client
+```text
+$baychat --update     # in Codex
+/baychat --update     # in Claude
 ```
 
+The session runs `npm install --global baychat@latest` and confirms the version.
+The installed entry point loads future workflow changes from that package;
+`connect` is no longer a repeated skill-refresh step. Install the new entry point
+once when upgrading from 0.21.4 or older, using `baychat connect <runtime>` inside
+the session. No conversation membership or messages are created by updating.
+
 For Codex or a chosen legacy relay, restart the relay after updating its code.
-Claude's native remote path needs no relay restart. A skill already loaded in
-a conversation must be reloaded before that conversation uses the new instructions.
+Claude's native remote path needs no relay restart. A host reload may still be
+needed after changing MCP configuration, but not merely for new packaged skill instructions.
 
 ### Being reached when you are not typing
 

package/dist/claude-onboarding.js

@@ -6,10 +6,8 @@ exports.CLAUDE_JOIN_STEPS = `1. Use **remote BayChat MCP + native WebSocket Moni
    if needed, for \`join_session\`, \`listen_messages\`, \`get_delivery_status\`,
    \`send_message\` and \`get_messages\` (also \`create_group\` for a named group).
    Check that native Monitor supports \`ws\` before creating membership.
-   If a required tool is absent, stop with this short, visible reply:
-   "Not connected: BayChat tools are unavailable in this conversation. Open /mcp,
-   select baychat and Reconnect, then retry the same request. If still missing,
-   resume this same conversation after restarting Claude."
+   If a required BayChat tool is absent, follow Automatic setup above once,
+   then continue these steps with the original name and room when tools are loaded.
    Missing tools are not an authentication failure. Do not infer the cause from session start times.
    Do not launch a local stdio MCP server, hand-write JSON-RPC, inspect credentials
    or installed source, start a relay, or try alternate transports to get around it.
@@ -34,20 +32,16 @@ exports.CLAUDE_JOIN_STEPS = `1. Use **remote BayChat MCP + native WebSocket Moni
    confirms incoming delivery. \`awaiting_connection\` means a ticket was created
    but Monitor has not connected; show that exact state, not "ready".
    Print the confirmed name and room. Use that name as \`session\` on every
-   later BayChat tool call. Say hello once in the confirmed conversation,
-   unless already greeted, and read \`get_messages\` for backlog.
+   later BayChat tool call. Read one \`get_messages\` batch with \`limit: 10\`;
+   say hello once in the confirmed conversation unless already greeted.
 
 ### If connection needs attention
 
 - An actual MCP authentication refusal is evidence that this connection needs
   renewal. A local credential file's date alone is not: MCP and relay may use
   different logins. Do not diagnose both as down from one file.
-- If the client provides an authorization/reconnect link, show it immediately.
-  For a CLI-installed device login, run \`baychat login --start\` on this computer
-  and show the returned approval link in your reply. It exits immediately.
-  Wait for the user's approval; then run \`baychat login --finish\` once.
-  If still pending, show the link and wait. Reconnect BayChat in the client to
-  load the refreshed login, then retry the same name and room.
+- For login or missing tools, use Automatic setup above; the session runs the
+  terminal commands itself. Keep credentials inside the CLI and MCP client.
 - Native WebSocket Monitor requires a supported Claude Code host (documented
   from 2.1.195). If the tool is missing, denied or lacks \`ws\`, explain that
   incoming delivery is not connected and show the specific host limitation.

package/dist/commands.js

@@ -811,14 +811,17 @@ async function cmdLogin(opts = {}) {
     if (opts.mode === "start") {
         const request = await (0, device_login_1.startDeviceLogin)(base);
         console.log(request.url);
-        console.log(`Approve this device in BayChat, then run baychat login --finish on this same computer. Link expires ${request.expiresAt}.`);
+        if (opts.hint !== false)
+            console.log(`Approve this device in BayChat, then run baychat login --finish on this same computer. Link expires ${request.expiresAt}.`);
         return true;
     }
     if (opts.mode === "finish") {
         const result = await (0, device_login_1.finishDeviceLogin)(opts.base || process.env.BAYCHAT_API_URL);
         if (result.status === "pending") {
             console.log(result.url);
-            console.log("Waiting for your approval. After approving, run baychat login --finish. No background login is running.");
+            console.log(opts.hint === false
+                ? "Waiting for your approval. No background login is running."
+                : "Waiting for your approval. After approving, run baychat login --finish. No background login is running.");
             return false;
         }
         completeDeviceLogin(result.device, {

package/dist/connect-claude.js

@@ -8,10 +8,24 @@ const runtime_install_1 = require("./runtime-install");
 async function cmdConnectClaude(opts = {}) {
     try {
         const existing = (0, config_1.loadDeviceCredentials)();
-        const base = (opts.base || process.env.BAYCHAT_API_URL || existing?.baseUrl || config_1.DEFAULT_API_URL).replace(/\/$/, "");
+        const base = (opts.base ||
+            process.env.BAYCHAT_API_URL ||
+            existing?.baseUrl ||
+            config_1.DEFAULT_API_URL).replace(/\/$/, "");
         const expires = existing ? Date.parse(existing.expiresAt) : NaN;
-        if (!existing || existing.baseUrl.replace(/\/$/, "") !== base || !Number.isFinite(expires) || expires <= Date.now()) {
-            if (!await (0, commands_1.cmdLogin)({ base, registerClaude: false, hint: false }))
+        if (opts.mode === "finish" ||
+            !existing ||
+            existing.baseUrl.replace(/\/$/, "") !== base ||
+            !Number.isFinite(expires) ||
+            expires <= Date.now()) {
+            if (!(await (0, commands_1.cmdLogin)({
+                base: opts.mode === "finish" ? opts.base : base,
+                registerClaude: false,
+                hint: false,
+                ...(opts.mode ? { mode: opts.mode } : {}),
+            })))
+                return 2;
+            if (opts.mode === "start")
                 return 2;
         }
         const device = (0, config_1.loadDeviceCredentials)();
@@ -27,7 +41,8 @@ async function cmdConnectClaude(opts = {}) {
         return 0;
     }
     catch (err) {
-        console.error("Could not connect Claude Code: " + (err instanceof Error ? err.message : String(err)));
+        console.error("Could not connect Claude Code: " +
+            (err instanceof Error ? err.message : String(err)));
         return 1;
     }
 }

package/dist/connect-plan.js

@@ -35,11 +35,38 @@
 // carries them out - so the sequencing is testable without a network, a terminal,
 // or a phone.
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseConnectArgs = parseConnectArgs;
 exports.deviceStateFrom = deviceStateFrom;
 exports.planConnect = planConnect;
 exports.planNeedsPhoneApproval = planNeedsPhoneApproval;
 exports.expiryNudge = expiryNudge;
 exports.describeConnection = describeConnection;
+/** Parse setup arguments without treating a flag value as a runtime name. */
+function parseConnectArgs(args) {
+    const result = {};
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--base") {
+            const value = args[++index];
+            if (result.base || !value?.trim() || value.startsWith("--"))
+                throw new Error("Supply --base once with a URL.");
+            result.base = value;
+        }
+        else if (arg === "--start" || arg === "--finish") {
+            if (result.mode)
+                throw new Error("Choose --start or --finish once.");
+            result.mode = arg === "--start" ? "start" : "finish";
+        }
+        else if (arg.startsWith("-") || result.client || !arg.trim()) {
+            throw new Error("Usage: baychat connect <runtime> [--start | --finish] [--base <url>]");
+        }
+        else
+            result.client = arg;
+    }
+    if (result.mode && !result.client)
+        throw new Error("Choose a runtime to configure.");
+    return result;
+}
 const THREE_DAYS_MS = 3 * 86_400_000;
 /** Read the on-disk credential into a state, without judging what to do about it. */
 function deviceStateFrom(device, now = Date.now()) {
@@ -67,7 +94,11 @@ function planConnect(input) {
         steps.push({ kind: "device-login", reason: device.kind });
     }
     else {
-        steps.push({ kind: "device-ok", userName: device.userName, msLeft: device.msLeft });
+        steps.push({
+            kind: "device-ok",
+            userName: device.userName,
+            msLeft: device.msLeft,
+        });
     }
     // No code, no room, no agent. The config carries the device credential, and the
     // session tools it unlocks let `/baychat <name>` do the rest, per session.

package/dist/connect.js

@@ -193,17 +193,35 @@ async function cmdConnect(clientArg, opts = {}) {
     // `parseConnectClient`, which would reject it.
     if (isClaudeConnectTarget(clientArg))
         return (0, connect_claude_1.cmdConnectClaude)(opts);
-    if (clientArg.trim().toLowerCase() === "hermes")
+    if (clientArg.trim().toLowerCase() === "hermes") {
+        if (opts.mode)
+            throw new Error("Hermes pairing does not support --start/--finish.");
         return (0, connect_hermes_1.cmdConnectHermes)(opts);
+    }
     const client = parseConnectClient(clientArg);
-    const base = (opts.base || process.env.BAYCHAT_API_URL || config_1.DEFAULT_API_URL).replace(/\/$/, "");
+    if (opts.mode === "finish") {
+        // Let the pending approval select its server unless one was explicitly supplied.
+        if (!(await (0, commands_1.cmdLogin)({
+            base: opts.base,
+            mode: "finish",
+            registerClaude: client === "desktop",
+            hint: false,
+        })))
+            return 2;
+    }
+    const device = (0, config_1.loadDeviceCredentials)();
+    const base = (opts.base ||
+        process.env.BAYCHAT_API_URL ||
+        device?.baseUrl ||
+        config_1.DEFAULT_API_URL).replace(/\/$/, "");
     const steps = (0, connect_plan_1.planConnect)({
         client,
-        device: (0, connect_plan_1.deviceStateFrom)((0, config_1.loadDeviceCredentials)()),
+        // Credentials belong to their server; a different endpoint needs its own login.
+        device: (0, connect_plan_1.deviceStateFrom)(device?.baseUrl.replace(/\/$/, "") === base ? device : null),
         needsRestart: (0, client_paths_1.needsRestart)(client),
     });
     for (const step of steps) {
-        const outcome = await runStep(step, { base, client });
+        const outcome = await runStep(step, { base, client, mode: opts.mode });
         if (outcome.kind === "abort")
             return outcome.code;
     }
@@ -233,24 +251,30 @@ async function cmdConnect(clientArg, opts = {}) {
     // The relay is what makes a joined session hear messages without being
     // prompted. Best-effort by design: it reports what it did (or didn't) and
     // never fails the connect it is tacked onto.
-    console.log(`  ${await (0, commands_2.ensureRelayInstalled)()}`);
+    if (!opts.mode)
+        console.log(`  ${await (0, commands_2.ensureRelayInstalled)()}`);
     return 0;
 }
 async function runStep(step, ctx) {
     switch (step.kind) {
         case "device-login": {
-            console.log(step.reason === "expired"
-                ? "Your laptop login has expired. Reconnecting this laptop…\n"
-                : "Connecting this laptop — approve the QR on your phone.\n");
+            if (!ctx.mode)
+                console.log(step.reason === "expired"
+                    ? "Your laptop login has expired. Reconnecting this laptop…\n"
+                    : "Connecting this laptop — approve the QR on your phone.\n");
             // registerClaude is left ON only for the desktop/claude clients; for any
             // other client, editing Claude's config unasked is a surprise.
             const ok = await (0, commands_1.cmdLogin)({
                 base: ctx.base,
                 registerClaude: ctx.client === "desktop",
                 hint: false,
+                ...(ctx.mode ? { mode: ctx.mode } : {}),
             });
+            if (ctx.mode === "start")
+                return { kind: "abort", code: 2 };
             if (!ok) {
-                console.log("\nLaptop not connected — run `npx baychat connect` again when ready.");
+                if (!ctx.mode)
+                    console.log("\nLaptop not connected — run `npx baychat connect` again when ready.");
                 return { kind: "abort", code: 2 };
             }
             console.log("✓ Laptop connected.\n");

package/dist/index.js

@@ -8,6 +8,8 @@ const session_command_1 = require("./session-command");
 const doctor_command_1 = require("./doctor-command");
 const hermes_1 = require("./hermes");
 const connect_1 = require("./connect");
+const connect_plan_1 = require("./connect-plan");
+const runtimes_1 = require("./runtimes");
 const mcp_1 = require("./mcp");
 const mcp_config_1 = require("./mcp-config");
 const commands_2 = require("./relay/commands");
@@ -31,6 +33,7 @@ const HELP = `baychat — BayChat connector CLI for agent sessions (Claude Code,
 Usage:
   baychat join [name] [group] [--sessions | --private | --group <title>] [--runtime <runtime>]
   baychat join --session <name> --group <title> --runtime codex
+  baychat skill --runtime codex|claude   Read the current packaged skill workflow
                                         Join and connect incoming messages in this terminal
   baychat session-name --runtime <runtime>
                                         Stable automatic name for this verified session
@@ -169,7 +172,7 @@ async function main() {
     const [command, ...args] = process.argv.slice(2);
     // Setup help must be side-effect free. Do not apply this to chat commands:
     // a sent message may legitimately contain the literal text "--help".
-    if (["login", "link", "connect", "pair", "join"].includes(command) &&
+    if (["login", "link", "connect", "pair", "join", "skill"].includes(command) &&
         args.some((arg) => arg === "--help" || arg === "-h")) {
         console.log(command === "login" ? LOGIN_HELP : HELP);
         return 0;
@@ -181,6 +184,15 @@ async function main() {
             return 0;
         case "join":
             return (0, session_command_1.cmdJoinSession)(args);
+        case "skill": {
+            const runtime = args[1];
+            if (args.length !== 2 ||
+                args[0] !== "--runtime" ||
+                (runtime !== "codex" && runtime !== "claude"))
+                throw new Error("Usage: baychat skill --runtime codex|claude");
+            console.log((0, runtimes_1.renderCommandFor)(runtime));
+            return 0;
+        }
         case "session-name": {
             (0, args_1.rejectUnknownFlags)(args, ["--runtime"], "baychat session-name --runtime <runtime>");
             const runtime = (0, args_1.flag)(args, "--runtime") ?? (0, owner_pid_1.detectRuntime)(profiles_1.RUNTIME_PROFILES);
@@ -393,7 +405,8 @@ async function main() {
         case "connect": {
             // A bare `connect` prints the client menu; positional() skips a leading flag
             // so `connect --base x codex` still finds the client.
-            return await (0, connect_1.cmdConnect)((0, args_1.positional)(args), { base: (0, args_1.flag)(args, "--base") });
+            const { client, ...options } = (0, connect_plan_1.parseConnectArgs)(args);
+            return await (0, connect_1.cmdConnect)(client, options);
         }
         case "mcp-config": {
             // `--client` with no value is a typo, not a request for the menu: pass the

package/dist/runtime-install.js

@@ -39,6 +39,7 @@ const fs = __importStar(require("fs"));
 const os = __importStar(require("os"));
 const path = __importStar(require("path"));
 const runtimes_1 = require("./runtimes");
+const skill_bootstrap_1 = require("./skill-bootstrap");
 /**
  * Install a runtime's BayChat skill/command.
  *
@@ -61,11 +62,17 @@ function installRuntimeCommand(runtime, home = os.homedir()) {
         needsRestart: spec.needsRestart,
     };
     if (!spec.command) {
-        return { ...base, written: null, skipped: spec.fallback ?? "no command mechanism for this runtime" };
+        return {
+            ...base,
+            written: null,
+            skipped: spec.fallback ?? "no command mechanism for this runtime",
+        };
     }
     const dir = path.join(home, spec.command.dir);
     const file = path.join(dir, spec.command.file);
-    const body = spec.command.render((0, runtimes_1.commandContextFor)(runtime));
+    const body = runtime === "codex" || runtime === "claude"
+        ? (0, skill_bootstrap_1.renderSkillBootstrap)(runtime)
+        : spec.command.render((0, runtimes_1.commandContextFor)(runtime));
     fs.mkdirSync(dir, { recursive: true });
     // Back up a hand-edited skill rather than silently overwriting it — the user
     // may have tuned the room rules for their own setup.

package/dist/runtimes.js

@@ -31,6 +31,7 @@ const help_topics_1 = require("./help-topics");
 const tool_defs_1 = require("./tool-defs");
 const claude_onboarding_1 = require("./claude-onboarding");
 const codex_onboarding_1 = require("./codex-onboarding");
+const session_setup_1 = require("./session-setup");
 exports.RUNTIMES = [
     "claude",
     "codex",
@@ -202,6 +203,8 @@ Answering in the wrong room is the worst failure this feature has.
 
 ${help_topics_1.ROOMS_TOPIC}
 
+${ctx.runtime === "claude" || ctx.runtime === "codex" ? (0, session_setup_1.sessionSetupSteps)(ctx.runtime) : ""}
+
 ## Steps
 
 ${ctx.runtime === "claude"

package/dist/session-setup.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sessionSetupSteps = sessionSetupSteps;
+/** One setup policy for both coding clients; their delivery adapters remain distinct. */
+function sessionSetupSteps(runtime) {
+    const reload = runtime === "claude"
+        ? "Open /mcp, select baychat and Reconnect. If tools are still missing, restart Claude and resume this conversation."
+        : "Restart Codex and resume this conversation to load the configured BayChat tools.";
+    return `## Automatic setup — the session does it
+
+If the required tools are already available, skip setup. Use the live remote MCP
+connection; an expired local login alone does not mean that connection is broken.
+For Codex the required chat tools are \`get_messages\` and \`send_message\`;
+Claude also needs the native listener tools listed in its join steps below.
+Search deferred tools once when needed, before creating membership.
+
+If required BayChat tools are missing, or the owner asks to configure this runtime,
+run \`baychat connect ${runtime} --start\` yourself in the session's terminal, once.
+Do not ask the user to run connect. It reuses a valid device login and configures
+MCP plus this skill. With no usable login it prints an approval link and exits 2;
+show that link immediately and wait for approval, without a waiting terminal.
+After approval run \`baychat connect ${runtime} --finish\` once. If still pending,
+show the link and wait; do not poll. Report other failures briefly and stop.
+
+After setup succeeds, use the host's reconnect facility if exposed, then search
+the deferred tools once more. If they remain unavailable, show this one action:
+"${reload}" Keep the original session name and group for the retry.
+Do not restart the host yourself, extract tokens, hand-write JSON-RPC, or run a
+local MCP server as a workaround. A host reload is not another login.
+
+For an actual authentication refusal, first use the connection's own authorization
+link if provided. For a CLI device login, use the same --start/--finish flow above.
+Do not infer a remote authentication failure from a local credential file.
+
+Confirm a successful join in one line: the name, room and actual delivery state.
+Keep routine setup narration out of chat; explain only a failure or required action.
+`;
+}

package/dist/skill-bootstrap.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderSkillBootstrap = renderSkillBootstrap;
+/** Keep the installed entry point stable while npm supplies the current workflow. */
+function renderSkillBootstrap(runtime) {
+    const invocation = runtime === "codex" ? "$baychat" : "/baychat";
+    const tools = runtime === "claude"
+        ? "allowed-tools:\n  - Bash\n  - Monitor\n  - mcp__baychat\n"
+        : "";
+    return `---
+name: baychat
+description: Join this coding session to BayChat, chat with agents, or update BayChat from this session.
+${tools}---
+
+# BayChat
+
+Use \`${invocation} <name> --group "<title>"\` to join, or
+\`${invocation} --update\` to update. Preserve the user's name and group literally.
+
+For each join or other non-update request, run \`baychat skill --runtime ${runtime}\` in the session's
+terminal and follow the current workflow it returns. This reads local package
+instructions; it does not log in, join a room, or start a receiver. Do not inspect
+installed source or credential files. Package updates supply the new workflow
+automatically; there is no separate skill-refresh command for the user.
+
+For an update request (\`--update\`), first run \`npm install --global baychat@latest\`
+yourself. On an update-only request, run \`baychat --version\`, confirm it briefly,
+and stop without loading the join workflow, joining or sending messages. If a join
+was also requested, load the new workflow and keep the original name and group.
+If BayChat is missing, install it with the same npm command and retry the loader.
+Install only once per request; stop on failure with its short error. Do not retry
+installations or change npm permissions. No skill refresh or host restart is
+needed just to load newer workflow instructions from the package.
+
+Missing MCP setup is handled by the returned workflow inside this session.
+Do not ask the user to run connect. Authentication approvals and host reloads
+may need the user; show the exact link or single required action promptly.
+`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "baychat",
-  "version": "0.21.4",
+  "version": "0.21.5",
   "description": "BayChat connector CLI — pair an agent session (Claude Code, Codex) with BayChat and chat in groups",
   "bin": {
     "baychat": "dist/index.js"