clisbot 0.1.43 → 0.1.45

package/README.md

@@ -40,17 +40,53 @@ The challenge is not whether AI is useful. It is how to make it work at enterpri
 - Slack and Telegram are not treated as plain-text sinks: routed conversations can carry thread or topic identity, pairing, and file-aware workflows.
 - Advanced multi-agent setup is available later, but it is not required for day one.
 
-## CLI Compatibility Snapshot
+## Surface Access Model
+
+The important current config mental model is:
+
+- `app`
+- `bots`
+- `agents`
+
+Inside each bot:
+
+- `directMessages` is the one-person surface map
+- `groups` is the multi-user surface map
+- stored keys use raw provider-local ids plus `*`
+
+Examples:
 
-`clisbot` currently works best with `codex`.
+- Slack shared surface: `groups["C1234567890"]`
+- Telegram group: `groups["-1001234567890"]`
+- Telegram topic: `groups["-1001234567890"].topics["42"]`
+- DM wildcard default: `directMessages["*"]`
+
+Operator CLI ids stay prefixed:
+
+- `dm:<id>`
+- `dm:*`
+- `group:<id>`
+- `group:*`
+- `topic:<chatId>:<topicId>`
+
+Current invariants:
+
+- Slack `channel:<id>` is compatibility input only, not canonical operator naming
+- stored config under one bot uses only raw ids plus `*` inside `directMessages` and `groups`
+- `group:*` is the default multi-user sender policy node for one bot and should be updated or disabled, not removed
+- `disabled` means silent for everyone on that surface, including owner/admin and pairing guidance
+- owner/admin do not bypass `groupPolicy`/`channelPolicy` admission; after a group is admitted and enabled, they bypass sender allowlists, while `blockUsers` still wins
+- the deny message intentionally uses one common human-facing term, `group`, for every multi-user surface
+
+## CLI Compatibility Snapshot
 
-`claude` and `gemini` are both usable, but they need a bit more operator awareness today.
+`clisbot` currently works well with Codex, Claude, and Gemini.
 
 | CLI      | Current Stability   | Short Take                                                                                                  |
 | ----------| ---------------------| -------------------------------------------------------------------------------------------------------------|
 | `codex`  | Best today          | Strongest default for routed coding work.                                                                   |
 | `claude` | Usable with caveats | Claude can surface its own plan-approval and auto-mode behavior even when launched with bypass-permissions. |
-| `gemini` | Usable with caveats | Runner support is solid, but auth/setup gating and routed reply behavior still need more care.              |
+| `gemini` | Fully compatible   | Gemini is supported as a first-class runner for routed Slack and Telegram workflows.                         |
 
 CLI-specific operator notes:
 
@@ -81,7 +117,13 @@ If you want to try first without persisting the token yet, just remove `--persis
 
 Next steps:
 
-- For security, just as openclaw, direct message with the bot currently requires pairing and groups need explicit specified in allowlist by default.
+- For security, DMs default to pairing.
+- Existing `0.1.43` configs upgrade directly to `0.1.45` automatically on first run. clisbot writes a backup first under `~/.clisbot/backups/`, then rewrites the config to the current shape.
+- Shared Slack channels, Slack groups, Telegram groups, and Telegram topics are a separate gate: normal users need an explicit route such as `group:<id>` or `topic:<chatId>:<topicId>` before the bot will talk there. Legacy Slack `channel:<id>` input still works for compatibility.
+- After a shared surface is admitted, per-surface sender control comes from the bot's default shared rule `groups["*"]` plus any route-local `allowUsers` or `blockUsers`.
+- If the effective shared policy is `disabled`, the bot stays silent there for everyone, including owner/admin.
+- If the effective shared policy is `allowlist` and a sender is not allowed, the bot denies before the runner:
+  - `You are not allowed to use this bot in this group. Ask a bot owner or admin to add you to \`allowUsers\` for this surface.`
 - However, `clisbot` has smart autopairing feature to help you get started frictionless. Just send direct message to your bot (through telegram or slack) within 30 minutes so you can claim owner role automatically, and use the bot right away without pairing. After this 30 minutes window you need to approve pairing following instructions by the bot in direct message.
 - To chat with the bot in a group:
   - telegram: Add bot to group, then use slash command in that group /start, you will be guided with command to add a group. Run that command directly or copy that command and chat directly with the bot in DM to ask it do for you (since you are the owner, you are authorized to run that command). After completed, come back to the group and start talk with the bot. 
@@ -224,7 +266,7 @@ The docs in this repo are kept current, including the [User Guide](docs/user-gui
 If you prefer to configure everything yourself:
 
 1. Read the official config template in [config/clisbot.json.template](config/clisbot.json.template).
-2. If you need the archived legacy snapshot, compare it with [config/clisbot.json.v0.1.0.template](config/clisbot.json.v0.1.0.template).
+2. If you need the archived released snapshot for migration review, compare it with [config/clisbot.v0.1.43.json.template](config/clisbot.v0.1.43.json.template).
 3. Copy the official template to `~/.clisbot/clisbot.json` and adjust bots, routes, agents, workspaces, and policies for your environment.
 4. Add agents through the CLI so tool defaults, startup options, and bootstrap templates stay consistent.
 5. Optionally move stable channel secrets into env vars or canonical credential files after your first successful run.
@@ -279,8 +321,11 @@ trust_level = "trusted"
 - If that trust screen is still blocking, attach directly and continue from tmux with `tmux -S ~/.clisbot/state/clisbot.sock attach -t agent-default-main`.
 - If Gemini startup says it is waiting for manual authorization, authenticate Gemini directly first or provide a headless auth path such as `GEMINI_API_KEY` or Vertex AI credentials; `clisbot` now treats that screen as a startup blocker instead of a healthy ready session.
 - If Codex warns that `bubblewrap` is missing on Linux, install `bubblewrap` in the runtime environment.
-- If the bot does not answer, check that your shell environment really contains the expected tokens and restart `clisbot` after changing them.
+- If the bot does not answer, check `clisbot status` first. Healthy channels should show `connection=active`; if a channel stays `starting`, inspect `clisbot logs`.
+- If a routed message was accepted but no reply arrives, send one test message and immediately run `clisbot runner watch --latest --lines 100` in a terminal. This shows the live tmux runner pane and usually reveals missing CLI auth, trust prompts, stuck startup, or model/provider errors.
+- If Codex works in your normal terminal but the routed runner shows `Missing environment variable: CODEX_CLIPROXYAPI_KEY`, remember that `clisbot` runs Codex from a detached background process and tmux session. Start or restart `clisbot` from a shell where `echo $CODEX_CLIPROXYAPI_KEY` prints a value, or export the key in the environment used by your service manager. Existing tmux runner sessions keep their old environment, so recycle them after fixing env.
 - If runtime startup still fails, run `clisbot logs` and inspect the recent log tail that `clisbot` now prints automatically on startup failure.
+- If a normal restart is not enough, use `clisbot stop --hard` to stop the runtime and kill all tmux runner sessions on the configured clisbot socket, then start again from a shell with the correct environment.
 - If you need the full command list, run `clisbot --help`.
 - If you need step-by-step operator docs, start with [docs/user-guide/README.md](docs/user-guide/README.md).
 - If Slack thread behavior feels too eager, use `/followup pause` or `/followup mention-only`.
@@ -293,11 +338,12 @@ Most users only need a small set of commands at first:
 - `clisbot start`: start the bot runtime and create the default first-run setup when needed.
 - `clisbot restart`: restart the runtime cleanly; use this first when the bot stops responding.
 - `clisbot stop`: stop the runtime cleanly before upgrades, config changes, or maintenance.
+- `clisbot stop --hard`: stop the runtime and kill all tmux runner sessions on the configured clisbot socket; use this when stale runner panes, old environment variables, or stuck sessions survive a normal restart.
 - `clisbot status`: check whether the runtime, channels, and active sessions look healthy.
 - `clisbot logs`: inspect recent runtime logs when startup, routing, or replies look wrong.
 - `clisbot runner list`: list the live tmux-backed runner sessions and see what is active.
 - `clisbot runner watch <session-name>`: live-watch one specific session when debugging a real run.
-- `clisbot runner watch --latest`: jump straight into the most recently active session.
+- `clisbot runner watch --latest --lines 100`: jump straight into the most recently active session with enough context to debug a just-submitted message.
 
 Full operator command reference: