charness 0.0.0-stage → 3.1.0

package/.env.example

@@ -0,0 +1,88 @@
+# Charness (formerly TelegramCode) 2.0 — forum-supergroup mode.
+#
+# Copy this file to `~/.config/telegramcode/.env`, fill TELEGRAM_BOT_TOKEN,
+# then launch from the parent folder containing your projects:
+#   cd ~/projects && telegramcode
+# For docker compose use `examples/docker-compose.yml` and the per-instance
+# prefix scheme (`PET_*` / `WORK_*`).
+#
+# The `telegramcode` wrapper loads env from two locations:
+#   1. ~/.config/telegramcode/.env   (base — fill in once, used everywhere)
+#   2. $PWD/.env                     (override — per-project tweaks)
+# Start the bot from the parent folder containing your projects:
+#   cd ~/projects && telegramcode
+# That $PWD becomes the work root. Do not set WORK_ROOT for normal use.
+
+# ── Required before launch ──────────────────────────────────────────────────
+
+# Telegram bot token from @BotFather → /newbot → ...
+TELEGRAM_BOT_TOKEN=
+
+# ── Optional external configuration ─────────────────────────────────────────
+
+# Access control: there is NO user allow-list. Whoever is a creator or
+# administrator of the served forum group may drive the bot (read live from
+# Telegram, cached 1h). Promote someone in the group to grant access; demote to
+# revoke. The bot must be a group admin itself (it already needs that to create
+# topics and pin messages).
+
+# Chat id of the forum-supergroup the bot listens to (negative number, usually
+# starts with -100...). Two ways to obtain:
+#   a) After the bot is added to the group, `/whoami` in any topic prints it.
+#   b) Forward any message from the group to @JsonDumpBot — `chat.id`.
+# Leave empty to auto-pair with the first forum supergroup an admin contacts
+# the bot from. Set it only when you want to pin a specific group before launch.
+ALLOWED_GROUP_ID=
+
+# Which Telegram surface(s) one instance serves: group | dm | both.
+# Default when unset: both — serves the owner DM AND the group at once, decided
+# per chat. `group` = forum supergroup only; `dm` = owner private chat only.
+# Leave unset for the normal both-surface deploy.
+# CHAT_MODE=both
+
+# Numeric Telegram user id of the owner (a private chat's id equals the user id).
+# In `both` it is OPTIONAL: set → the DM surface is active; unset → group-only.
+# REQUIRED for `dm`. Get it via `/whoami` in the bot DM, or @JsonDumpBot.
+# OWNER_USER_ID=
+
+# Where the bot keeps state.json, mcp.json, tmp/ and logs. Default:
+# ~/.telegramCode. **Required to be distinct** when running two bots on the
+# same host under the same linux user (otherwise they corrupt each other's
+# state.json). See plan §10.7.
+# DATA_DIR=/home/user/.telegramCode/mybot
+
+# Voice transcription. Recommended: without GROQ_API_KEY, voice messages are
+# not transcribed unless you intentionally configure the OpenAI fallback below.
+# GROQ_API_KEY=
+
+# ── Advanced / only when your setup needs it ────────────────────────────────
+
+# Override the project-parent directory only when you cannot control the process
+# cwd (for example, a custom systemd service). Normal launch uses $PWD instead.
+# WORK_ROOT=/home/user/src
+
+# OpenAI Whisper fallback for voice. Usually unnecessary when GROQ_API_KEY is set.
+# OPENAI_API_KEY=
+
+# Not needed for normal agent auth. Claude/OpenCode credentials are configured
+# through those CLIs themselves; set provider env vars only if a custom MCP,
+# OpenCode plugin, or auth resolver explicitly requires them.
+# ANTHROPIC_API_KEY=
+
+# OpenCode HTTP server URL. Leave unset for the built-in loopback server on
+# http://localhost:4096. Set it for a custom port or an external server.
+# OPENCODE_URL=http://localhost:4096
+# OPENCODE_PASSWORD=
+# OPENCODE_USERNAME=opencode
+# OPENCODE_ALLOW_REMOTE=1
+
+# Custom opencode binary path (only if you've built a fork locally).
+# OPENCODE_BIN=/path/to/opencode
+
+# Custom Claude binary path (useful with nvm/asdf/systemd PATH differences).
+# CLAUDE_BIN=/path/to/claude
+
+# Debug / bot-owned MCP plumbing. By default the OS chooses a free loopback
+# port. Set SCHEDULER_MCP_PORT only when you need a stable, explicitly chosen port.
+# CLAUDE_SCRAPE_DEBUG=1
+# SCHEDULER_MCP_PORT=4107

package/DEVELOPMENT.md

@@ -0,0 +1,110 @@
+# Development
+
+Architecture and local-development notes for Charness. User-facing setup
+lives in the [README](README.md); [`CLAUDE.md`](CLAUDE.md) is the short
+project map for agents, and each module's behavior is documented next to the
+code (`src/<module>/README.md`).
+
+## Architecture
+
+The per-topic folder layout is in the README under
+[Required files structure](README.md#required-files-structure).
+
+Routing key is `(chatId, threadId)` everywhere. Per-thread state lives in
+`${DATA_DIR}/state.json` (atomic writes with `fsync`, archived on
+corruption). Bot-owned tmux sessions are named per backend —
+`claude-<chatId>-<threadId>` (Claude tmux-scrape), `cjson-…` (the Claude
+json-stream host process), `term-…` (terminal) — see
+`src/utils/tmuxSessionName.ts`; opencode sessions are keyed by the same
+`<chatId>:<threadId>` string. Two topics on the same folder stay independent.
+
+### Connector pattern (the platform seam)
+
+The core never speaks to a chat platform directly. It consumes normalized
+`InboundEvent`s and emits semantic `OutboundContent`, both addressed by a
+platform-agnostic `SessionKey`. Telegram is the first connector; adding a
+tracker or Teams surface means adding a directory under `src/connectors/`, not
+editing the core.
+
+```
+Telegram  <->  connectors/telegram/  <->  bot.ts  <->  AgentAdapter <-> { Claude CLI (tmux scrape) |
+                 inbound.ts               (core)          │              Claude CLI (stream-json) |
+                 outbound.ts + output/      │             │              OpenCode (HTTP+SSE)      |
+                 sessionKeyCodec.ts         │             │              Terminal ($SHELL in tmux) }
+                 renderAgentHtml.ts         │             │
+                 messageSplit.ts            │             └── state.ts  (bindings, claudeSessionId,
+                 fileIntake.ts              │                            opencodeSessionId, messages,
+                 fileSendGateway.ts         │                            MCP per-thread overrides)
+                 updateDispatcher.ts        │
+                 language/timezonePicker.ts │
+                                            │
+      platform/inbound.ts  ─────────────────┤
+      platform/outbound.ts ─────────────────┤
+      platform/commandRouter.ts ────────────┘
+      (the contracts — no platform library may be imported here)
+```
+
+A test (`src/__tests__/platformBoundary.test.ts`) fails if any module outside
+`src/connectors/telegram/` imports the Telegram library; `src/bot.ts` is the one
+explicit, documented exemption still awaiting decomposition.
+
+- `platform/` holds the CONTRACTS: `InboundEvent`, `ConnectorInbound`,
+  `OutboundContent`, `OutboundHints`, `ConnectorCapabilities`,
+  `ConnectorOutbound`, and the neutral command router.
+- `connectors/telegram/` holds the IMPLEMENTATION: telegraf types, the HTML
+  dialect, message limits, inline keyboards, pins, the typing action, and the
+  frozen `"<chatId>:<threadId>"` key spelling.
+- A connector DECLARES its capabilities (`ConnectorCapabilities`) and content
+  degrades through one shared rule (`platform/capabilityFallback.ts`) that every
+  connector applies — a tracker has no pinning and no tappable buttons, so the
+  options stay as the enumerated text the body already carries and the user
+  answers by index. `src/connectors/test/` is a capability-configurable test
+  double that makes those degraded paths reachable; it is TESTS ONLY.
+- `OutputTransport` (`src/connectors/telegram/output/`) is a Telegram CHAT-MODE seam, one level
+  below: picked once at boot by `CHAT_MODE`, group edit-in-place stream vs the
+  owner-DM native draft "cursor". It is composed by the Telegram connector, not
+  by the core.
+
+### Adapter pattern
+
+Each adapter implements `AgentAdapter` from `src/types.ts`:
+- `startSession(key, workDir, args?, sessionId?)` / `stopSession(key)` / `resumeSession(key, workDir, sessionId, options?)`
+- `sendInput(key, text)` / `sendSignal(key, signal)`
+- events: `output`, `status`, `question`, `questionGone`, `thinking`,
+  `toolResult`, `subagentStatus`, `apiError`, `started`, `stopped`, `closed`,
+  `error` (all emit `SessionKey` first)
+
+## Local development
+
+```bash
+yarn install
+yarn dev          # tsx watch (fast dev — TS errors crash the process)
+yarn typecheck    # strict tsc over all of src/, test code included
+                  # (tsconfig.typecheck.json extends tsconfig.json)
+yarn build        # tsc → dist/ (tsconfig.json; src/__tests__ is not emitted)
+yarn test         # test:unit, then test:flows (node test runner + tsx); build
+                  # first — some tests exercise the built dist/cli.js
+yarn test:unit    # every file but the flows; each file must finish in 2 min
+yarn test:flows   # the `*E2e.test.ts` flows; each file must finish in 20 min
+yarn hot          # hot-reload mode: tsc -w + nodemon on dist/ (also
+                   # `telegramcode hot` from anywhere) — a broken edit can't
+                   # take the bot down; OpenCode generations stay outside the
+                   # worker tree, so agent turns survive worker reloads
+                   # (Linux/macOS; Windows hot mode is intentionally refused)
+```
+
+Node applies `--test-timeout` to a whole test FILE (a `describe`'s own `timeout` cannot extend it), so a file that
+hangs or leaves a process alive fails by name when its limit passes, instead of hanging the run. A long-running
+flow file must be named `*E2e.test.ts` to get the flows' limit; `live/*Live.test.ts` is run directly (CLAUDE.md).
+A flow's own time budget is that same limit less a teardown reserve (`getFlowDeadlineMs`, read from the process's
+`--test-timeout`), so a flow that runs long fails first, at the wait that is late and with charness's output tail,
+not with the runner's bare timeout. Run one flow directly with `--test-timeout=<ms>`.
+
+The Docker dev loop (never `docker compose restart` — it ignores
+`depends_on`):
+
+```bash
+docker compose down telegramcode && docker compose up -d telegramcode   # examples/docker-compose.yml
+docker compose logs -f telegramcode         # tail logs
+docker exec telegramcode-main telegramcode-restart-bot   # restart only the bot; agents keep running
+```

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sergei Solo
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATION_1_TO_2.md

@@ -0,0 +1,24 @@
+# Migrating from 1.x to 2.0
+
+The 1.x "one bot = one private chat = one folder" mode is **removed**.
+There is no in-place upgrade; the steps are:
+
+1. Stop the old bot.
+2. Create a forum supergroup, add the bot, follow [Quick Start §3](README.md#3-set-up-a-group-optional-or-dm).
+3. Remove the old `WORK_DIR` env and launch from the projects parent:
+   `cd /home/user/src && telegramcode`.
+4. Leave `ALLOWED_GROUP_ID` empty to auto-pair on first contact (or set
+   the numeric id by hand).
+5. Set `DATA_DIR` if you run two instances on the same host.
+6. The old `~/.telegram-bot-messages.json` is moved to `.bak` on first
+   start — no migration of message ids, fresh `state.json`.
+
+## Release notes
+
+- Routing key is `(chatId, threadId)`, persisted in `state.json`.
+- tmux sessions renamed `claude-${chatId}-${threadId}` (the tmux-scrape
+  backend; the json-stream host uses the `cjson-` prefix, terminal `term-`).
+- `claude --session-id <uuid>` is hardcoded — no more interactive picker.
+- `--dangerously-skip-permissions` is hardcoded (symmetry with
+  opencode's auto-approve).
+- Privacy mode must be disabled and the bot re-added.