@sojaner/telex 0.1.15

package/README.md

@@ -0,0 +1,502 @@
+# telex
+
+An MCP server that lets local AI agents talk to you through Telegram — ask a question, offer
+buttons, collect a typed reply, and give up gracefully when you are away.
+
+Your agent is running a long task, hits a decision it shouldn't make alone, and you are not at
+the keyboard. Instead of guessing or stalling, it sends you a Telegram message with two buttons
+and waits. You tap one from your phone; the agent carries on with your answer. If you never
+answer, the buttons come off, the message is marked stale, and the agent decides for itself
+whether to stop or continue.
+
+telex is local-only: it runs over stdio next to your agent, talks outbound to the Telegram Bot
+API, and only ever messages the chats you configured. Nothing listens on a port.
+
+```
+┌────────┐   stdio/MCP   ┌───────┐   Bot API   ┌──────────┐
+│ agent  │ ────────────▶ │ telex │ ──────────▶ │ Telegram │ ──▶ you
+└────────┘   ◀────────── └───────┘   ◀────────  └──────────┘
+             the answer               your tap
+```
+
+---
+
+## Install
+
+```sh
+npm i -g @sojaner/telex
+```
+
+Requires Node 22.6 or newer. The binary is called `telex` whatever you install it from.
+
+Pin a version, or take it straight from the GitHub release if you prefer not to go through
+the registry:
+
+```sh
+npm i -g @sojaner/telex@0.1          # a range, or any exact published version
+npm i -g https://github.com/Sojaner/telex/releases/latest/download/telex.tgz
+npm i -g https://github.com/Sojaner/telex/releases/download/v0.1.14/telex.tgz
+```
+
+Every green push to `main` bumps the patch version, publishes it to npm and attaches the same
+tarball to a GitHub release, so both routes carry identical builds.
+
+Or run it from a checkout:
+
+```sh
+git clone https://github.com/Sojaner/telex && cd telex
+corepack enable && pnpm install
+node src/cli.ts --help          # runs the TypeScript directly, no build
+pnpm run build && pnpm link --global   # or link this checkout as the global telex
+```
+
+Upgrade with the same install command; uninstall with `npm rm -g @sojaner/telex`.
+
+---
+
+## Set up a bot
+
+Create the bot in Telegram, then let telex do the rest:
+
+```sh
+telex add
+```
+
+It walks you through three things:
+
+1. **The token.** Open [@BotFather](https://t.me/BotFather), send `/newbot`, pick a display name
+   and a username ending in `bot`. BotFather replies with a token like `8123456789:AAH…`. Paste
+   it in. telex validates it against `getMe` before going further.
+2. **The chat.** telex prints your bot's link and waits. Open the chat and send it anything —
+   telex reads the chat id and your Telegram user id straight off that message, so you never
+   have to read raw `getUpdates` JSON.
+3. **A name.** How you'll refer to this bot later (`main`, `work`, `acme-api`). The first bot
+   added becomes the default.
+
+It writes `~/.config/telex/config.json` with mode `0600` and sends a test message so you know the
+round trip works.
+
+Run `telex add` again for each additional bot. One bot per project is the point — see
+[Per-project configuration](#per-project-configuration).
+
+### Groups
+
+Point a bot at a group instead of a DM: add the bot to the group, run `telex add`, and send the
+message from inside the group. Group chat ids are negative; telex picks that up automatically.
+
+Set `allowFrom` for groups. An inline keyboard is tappable by **everyone** who can see it, and
+telex checks the tapping user against that list — without it, any group member can answer your
+agent's questions.
+
+### Doing it by hand
+
+```sh
+telex add work --token '8123456789:AAH…' --chat-id 987654321 --allow 987654321
+telex add team --token '8234567890:AAG…' --chat-id=-1001234567890 --allow 987654321,123456789
+```
+
+Negative chat ids need `--chat-id=-100…` (with the equals sign), because a bare `-100…` looks
+like another flag.
+
+---
+
+## Managing bots
+
+```
+telex add [name]              add a bot, guided; or --token … --chat-id …
+telex list                    configured bots, tokens masked
+telex set <name> [options]    change token / chat / allowlist / default
+telex remove <name>           delete a bot
+telex config [name]           install the MCP registration into this project
+telex serve                   run the MCP server over stdio (what agents launch)
+```
+
+Options for `add` and `set`:
+
+| Flag | Meaning |
+|---|---|
+| `--token <token>` | Bot token from BotFather |
+| `--chat-id <id>` | Chat the bot writes to (`--chat-id=-100…` for groups) |
+| `--allow <id,id>` | Telegram user ids allowed to answer; `any` clears the list |
+| `--default` | Make this the global default bot |
+
+```sh
+$ telex list
+* work             chat 987654321        8123456789:******bAcD  allow: 987654321
+  team             chat -1001234567890   8234567890:******xYzW  allow: 987654321, 123456789
+
+* = default. Config: /home/you/.config/telex/config.json
+```
+
+`telex list --json` prints the same thing as JSON, tokens still masked.
+
+---
+
+## The config file
+
+`~/.config/telex/config.json`, or wherever `TELEX_CONFIG` points. `XDG_CONFIG_HOME` is honoured.
+
+```json
+{
+  "defaultBot": "work",
+  "bots": {
+    "work": {
+      "token": "8123456789:AAH…",
+      "chatId": 987654321,
+      "allowFrom": [987654321]
+    },
+    "team": {
+      "token": "8234567890:AAG…",
+      "chatId": -1001234567890,
+      "allowFrom": [987654321, 123456789]
+    }
+  }
+}
+```
+
+| Field | Required | Meaning |
+|---|---|---|
+| `defaultBot` | no | Bot used when nothing else specifies one. Defaults to the first entry. |
+| `bots.<name>.token` | yes | BotFather token. Keep this file at `0600`; it is a credential. |
+| `bots.<name>.chatId` | yes | Chat the bot writes to. Negative for groups and channels. |
+| `bots.<name>.allowFrom` | no | Telegram user ids allowed to answer. Omit to trust anyone in the chat. |
+
+The file is shared by every project on the machine; projects select a bot from it rather than
+keeping their own copy of your tokens.
+
+---
+
+## Registering with an agent
+
+```sh
+cd ~/code/acme-api
+telex config
+```
+
+asks whether this directory is the project you mean, then which agent to install for, and does
+the install: it runs that agent's own CLI when it has one, and writes the config file itself when
+it does not. The server command is always `telex serve`.
+
+| Flag | Meaning |
+|---|---|
+| `--agent <id>` | skip the prompts: `claude`, `gemini`, `qwen`, `codex`, `cursor`, `roo`, `vscode`, `zed`, `amp`, `opencode`, `crush` |
+| `--scope local\|project` | for agents with both: the gitignored file or the committed one |
+| `--print` | only show the commands and file shapes; write nothing |
+| `-y` | don't ask about the current directory |
+| `--json` | print just the `mcpServers` object |
+
+Required for a non-interactive run: `--agent`, plus `--scope` for agents that have both files.
+Writing a file merges into whatever is already there rather than replacing it, and `--scope local`
+adds the file to `.gitignore`.
+
+Agents that install it themselves — `telex config --agent claude` runs:
+
+```sh
+claude mcp add --scope project telex -- telex serve      # Claude Code
+gemini mcp add --scope project telex telex serve         # Gemini CLI
+qwen mcp add --scope project telex telex serve           # Qwen Code
+```
+
+Agents telex configures by writing the file — same server, different shape per agent:
+
+| Agent | File | Shape |
+|---|---|---|
+| Claude Code | `.mcp.json` | `{"mcpServers": {"telex": {"command": "telex", "args": ["serve"]}}}` |
+| Cursor | `.cursor/mcp.json` | same as above |
+| Roo Code | `.roo/mcp.json` | same as above |
+| VS Code | `.vscode/mcp.json` | `{"servers": {"telex": {"type": "stdio", "command": "telex", "args": ["serve"]}}}` |
+| Zed | `.zed/settings.json` | `{"context_servers": {"telex": {"source": "custom", "command": "telex", "args": ["serve"]}}}` |
+| Amp | `.amp/settings.json` | `{"amp.mcpServers": {"telex": {"command": "telex", "args": ["serve"]}}}` |
+| opencode | `opencode.json` | `{"mcp": {"telex": {"type": "local", "command": ["telex", "serve"]}}}` |
+| Crush | `.crush.json` | `{"mcp": {"telex": {"type": "stdio", "command": "telex", "args": ["serve"]}}}` |
+| Codex CLI | `.codex/config.toml` or `.codex/config.local.toml` | `[mcp_servers.telex]` / `command = "telex"` / `args = ["serve"]` |
+
+Codex is the one with two files: `.codex/config.toml` is committed and shared with the team,
+`.codex/config.local.toml` is your own and gitignored — `--scope project` or `--scope local`.
+Codex only reads either for projects you have marked trusted. Anything else that
+speaks MCP takes the `mcpServers` shape — `claude_desktop_config.json`, Continue, and the rest.
+
+For one bot everywhere instead of one
+per project, install at user scope: `claude mcp add --scope user telex -- telex serve`.
+
+If `telex` is not on the agent's `PATH` — GUI apps often have a shorter `PATH` than your shell —
+use the absolute path, or point Node at the installed entry point:
+
+```json
+{
+  "mcpServers": {
+    "telex": {
+      "command": "node",
+      "args": ["/home/you/.npm-global/lib/node_modules/telex/dist/index.js"]
+    }
+  }
+}
+```
+
+`telex config --print` prints that path for your machine.
+
+### Per-project configuration
+
+Give each project its own bot, so a message tells you which project it came from before you even
+read it, and you can mute one project's bot without muting the rest.
+
+```sh
+cd ~/code/acme-api
+telex add acme-api                       # its own bot, its own chat
+telex config acme-api                    # same install, pinned to that bot
+```
+
+which threads `TELEX_BOT=acme-api` into whatever it installs:
+
+```sh
+claude mcp add --scope project telex --env TELEX_BOT=acme-api -- telex serve
+```
+
+```json
+{
+  "mcpServers": {
+    "telex": {
+      "command": "telex",
+      "args": ["serve"],
+      "env": { "TELEX_BOT": "acme-api" }
+    }
+  }
+}
+```
+
+Commit that `.mcp.json` and everyone on the project gets the right routing — they each configure
+their own bot named `acme-api` with their own token, and nothing secret goes in the repo.
+
+Which bot a message goes to, in order:
+
+1. The `bot` argument on the tool call, if the agent passes one.
+2. `TELEX_BOT` from the MCP registration — the project's bot.
+3. `defaultBot` from the config file.
+
+So a project's agent messages its own bot without being told to, and can still reach another bot
+deliberately (`bot: "oncall"` for something urgent, say).
+
+---
+
+## The tools
+
+The server exposes two tools. `send_to_user` starts the conversation:
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `project` | string, required | Task or project name, rendered as the bold heading. |
+| `message` | string, required | The copy to show you, in Telegram HTML. |
+| `options` | string[], optional | Up to 10 single-choice answers, rendered as buttons. |
+| `expect_text` | boolean, optional | Show one *Reply* button; your next message becomes the answer. |
+| `timeout_seconds` | number, default 300 | Deadline for the whole exchange, 5s to 24h. |
+| `bot` | string, optional | Which configured bot to use. |
+| `project_path` | string, required | Absolute path of the project the agent is working in. |
+| `agent` | string, required | The agent's own name, e.g. `claude-code`. |
+| `interval_seconds` | number, default 60 | How often the agent calls `heartbeat`. |
+
+`options` and `expect_text` are mutually exclusive. With neither, the message is a one-way
+notification and the call returns immediately.
+
+**Formatting.** `message` is rendered with Telegram's HTML subset: `<b> <i> <u> <s> <code> <pre>
+<a href=""> <blockquote>`. Literal `&`, `<` and `>` must be escaped as `&amp; &lt; &gt;`.
+Markdown is not rendered. A message with broken tags is re-sent as plain text rather than failing
+the call.
+
+**Results.**
+
+```json
+{"status": "sent",     "message_id": 101}
+{"status": "answered", "response": "Yes", "kind": "choice", "message_id": 101}
+{"status": "timeout",  "message_id": 101}
+```
+
+On `timeout` the buttons are stripped and the message is marked stale, so a late tap can't answer
+a question nobody is listening to any more. What happens next — retry, continue without you,
+stop — is entirely the agent's call. telex has no opinion.
+
+If you messaged the bot while the agent wasn't asking anything, the result carries those messages
+too, delivered exactly as a heartbeat would:
+
+```json
+{"status": "sent", "message_id": 101, "pending": [{"text": "hold off on the deploy", "received_at": "2026-09-15T18:22:04.000Z", "waited_seconds": 37}]}
+```
+
+### Messages you send first
+
+You can talk to the bot without being asked. An MCP server cannot wake a sleeping agent — agents
+only act when they call a tool — so telex holds what you said until the agent checks in, and
+edits a single receipt under your message as it moves:
+
+| What you see | What it means |
+|---|---|
+| 📥 *Held for the agent's next check-in.* | telex has your message and is holding it. |
+| ⛔ *Not accepted — no agent has checked in for this project yet.* | The server is running but no agent has identified itself. Nothing is holding your message. |
+| 📬 *Delivered to the agent.* | A heartbeat collected it; the agent has it now. |
+| ⌛ *Expired — the agent never picked this up.* | Three intervals passed with no check-in. Dropped. |
+| *nothing at all* | Nothing is running for that project. The message went nowhere. |
+
+Silence is the signal: telex only polls while its process is alive, so a message with no receipt
+at all means no agent is there to receive it. Held messages are capped at 50 per chat, oldest
+dropped.
+
+### `heartbeat`
+
+The agent's side of that. It calls this on a fixed interval for as long as it is working, and the
+call returns immediately — it never blocks and never waits for you.
+
+| Parameter | Type | Meaning |
+|---|---|---|
+| `interval_seconds` | number, default 60 | How often the agent intends to check in, 10s to 1h. |
+| `project_path` | string, required | Absolute path of the project. |
+| `agent` | string, required | The agent's own name. |
+| `bot` | string, optional | Which configured bot to listen on. |
+
+```json
+{"messages": [{"text": "ship it", "received_at": "2026-09-15T18:22:04.000Z", "waited_seconds": 12}], "interval_seconds": 60}
+```
+
+An empty `messages` array is the normal case — nothing was said, keep working. The interval does
+double duty as a liveness signal: miss three in a row and anything waiting is marked expired and
+dropped, so you learn the agent stopped listening instead of watching a message sit unanswered
+forever.
+
+### Who is calling
+
+Every tool call carries `project_path`, `agent` and `interval_seconds`. That does three things:
+
+- **The expiry clock starts at the first call**, not the first heartbeat. A message you send a
+  second later already has a deadline.
+- **Messages sent before any agent has checked in are refused**, not held. The server starts with
+  your agent, but until the agent actually calls a telex tool nothing owns the bot — telex says so
+  rather than quietly stockpiling messages for an agent that may never ask.
+- **Two projects on one bot get caught.** Each running agent records itself in
+  `~/.local/state/telex/sessions.json` (override with `TELEX_STATE`), so separate telex processes
+  can see each other. When a second one appears on the same bot you get:
+
+  > ⚠️ **Two agents are using this bot at once**
+  > `claude-code` — `/code/acme-api`
+  > `codex` — `/code/other`
+  > Telegram gives each message to only one of them, so answers will go missing.
+
+  That is not a cosmetic warning. Telegram hands each update to exactly one poller, so a shared
+  bot loses roughly half of everything you send. Give each project its own bot.
+
+A record is live while its process exists and it has checked in within three intervals; crashed
+and stale ones are pruned on the next call, so the warning doesn't fire for agents that are gone.
+
+### Examples
+
+A decision:
+
+```json
+{
+  "project": "acme-api",
+  "message": "Migration <code>0042_drop_legacy_users</code> is destructive and irreversible.\nRun it against <b>production</b>?",
+  "options": ["Run it", "Skip for now", "Stop and wait for me"],
+  "timeout_seconds": 1800
+}
+```
+
+Missing information:
+
+```json
+{
+  "project": "acme-api",
+  "message": "What should the new endpoint be called?",
+  "expect_text": true,
+  "timeout_seconds": 600
+}
+```
+
+A notification, no answer wanted:
+
+```json
+{
+  "project": "nightly",
+  "message": "✅ Test suite green, 412 passed in 3m12s.\nBranch <code>fix/token-refresh</code> is ready to merge.",
+  "bot": "alerts"
+}
+```
+
+---
+
+## Behaviour worth knowing
+
+- **Long messages** are split at Telegram's limit; only the last part carries the buttons.
+- **Long choices** — anything over 24 characters — are listed in the message body and the buttons
+  become `1`, `2`, `3`, because Telegram truncates long button labels.
+- **Stale updates are discarded.** Messages you sent before the question was asked are never read
+  as an answer.
+- **Slash commands are ignored** as text answers, so `/start` and friends still work.
+- **Rate limits** are honoured: a `429` is retried after the `retry_after` Telegram asks for.
+- **Tokens are redacted** from error messages; they appear in the API URL that failed.
+- **Polling runs while the process does.** Once a project's bot is watched telex long-polls for
+  the life of the server, because being reachable is what makes "delivered" mean anything. Kill
+  the agent and the bot goes quiet.
+- **Unprompted messages are held, not answered with.** A message you send while nothing is asking
+  is queued for the agent instead of being read as the answer to whatever gets asked next.
+- **`allowFrom` covers inbound too.** Someone else in the group messaging the bot is dropped, not
+  queued.
+- **One poller per token.** Two processes polling the same bot fight over updates; give telex its
+  own bot. It says so explicitly if it detects a conflict.
+
+---
+
+## Security notes
+
+- The config file holds bot tokens. telex writes it `0600`; keep it that way, and don't commit it.
+- Set `allowFrom` anywhere the chat has more than you in it. Buttons are visible and tappable by
+  every member; telex authorises the tap, not just the send.
+- A bot can only message chats it is already in, and telex only ever sends to the configured
+  `chatId`. It does not accept inbound commands or expose an HTTP endpoint.
+- The agent chooses what to send. Treat the message body as something the agent wrote — don't
+  ask it to relay secrets you wouldn't want in a Telegram chat.
+
+---
+
+## Troubleshooting
+
+| Symptom | Cause |
+|---|---|
+| `no bots configured` | Run `telex add`, or point `TELEX_CONFIG` at the right file. |
+| `Telegram rejected that token` | Paste the whole BotFather line, including the digits before the colon. |
+| Nothing arrives, no error | Wrong `chatId`, or you never messaged the bot. Check with `telex list`. |
+| `getUpdates conflict` | Another process is polling the same token. Give telex its own bot. |
+| Agent can't start the server | `telex` isn't on its `PATH`; use the absolute `node …/dist/index.js` form. |
+| Buttons do nothing | The tapping account isn't in `allowFrom`. `telex set <name> --allow <id>`. |
+| You message the bot, nothing replies | Nothing is running for that project — start the agent. That silence is deliberate. |
+| Messages stay "held" | The agent isn't calling `heartbeat`. It will still see them on its next tool call. |
+| Everything is "not accepted" | The agent hasn't called any telex tool yet, so nothing owns the bot. |
+| Warned about two agents | Two projects share one bot. `telex add <name>` and repoint one of them. |
+| Messages expire constantly | The agent's `interval_seconds` is shorter than how often it really checks in. |
+
+Run the server by hand to see startup errors that an agent would swallow:
+
+```sh
+telex serve < /dev/null
+```
+
+---
+
+## Development
+
+This repo uses **pnpm**. `npm install` in a checkout stops at a `preinstall` guard telling you
+so, CI fails on a committed `package-lock.json` or `yarn.lock`, and `pnpm install --frozen-lockfile`
+fails the build if `package.json` and `pnpm-lock.yaml` ever drift apart. The published package is
+unaffected: the guard is stripped at pack time, so installing telex runs no scripts at all.
+
+```sh
+corepack enable   # uses the pnpm version pinned in packageManager
+pnpm install
+pnpm test         # node:test, no network
+pnpm run typecheck
+pnpm run build    # tsc → dist/, normally done by CI
+node src/cli.ts   # run from source; Node strips the types
+```
+
+`dist/` is not committed. CI runs the tests on Node 22 and 24 with a frozen lockfile, then bumps
+the version, tags it, and publishes a release with the built tarball attached.
+
+## License
+
+MIT

package/config.example.json

@@ -0,0 +1,7 @@
+{
+  "defaultBot": "main",
+  "bots": {
+    "main": { "token": "123456:ABC-DEF-your-bot-token", "chatId": 987654321, "allowFrom": [987654321] },
+    "alerts": { "token": "234567:GHI-JKL-another-bot-token", "chatId": 987654321 }
+  }
+}

package/dist/agents.js

@@ -0,0 +1,94 @@
+/** Where each agent keeps its project-scoped MCP config, and how telex gets it there. */
+import { spawnSync } from "node:child_process";
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+export function agents() {
+    const std = (entry) => entry;
+    return [
+        { id: "claude", label: "Claude Code", file: ".mcp.json", path: ["mcpServers", "telex"], value: std,
+            cli: (bot) => ["claude", "mcp", "add", "--scope", "project", "telex", ...(bot ? ["--env", `TELEX_BOT=${bot}`] : []), "--", "telex", "serve"] },
+        { id: "gemini", label: "Gemini CLI", cli: (bot) => ["gemini", "mcp", "add", "--scope", "project", ...(bot ? ["-e", `TELEX_BOT=${bot}`] : []), "telex", "telex", "serve"] },
+        { id: "qwen", label: "Qwen Code", cli: (bot) => ["qwen", "mcp", "add", "--scope", "project", ...(bot ? ["-e", `TELEX_BOT=${bot}`] : []), "telex", "telex", "serve"] },
+        { id: "codex", label: "Codex CLI", file: ".codex/config.toml", localFile: ".codex/config.local.toml", toml: true },
+        { id: "cursor", label: "Cursor", file: ".cursor/mcp.json", path: ["mcpServers", "telex"], value: std },
+        { id: "roo", label: "Roo Code", file: ".roo/mcp.json", path: ["mcpServers", "telex"], value: std },
+        { id: "vscode", label: "VS Code", file: ".vscode/mcp.json", path: ["servers", "telex"], value: (e) => ({ type: "stdio", ...e }) },
+        { id: "zed", label: "Zed", file: ".zed/settings.json", path: ["context_servers", "telex"], value: (e) => ({ source: "custom", ...e }) },
+        { id: "amp", label: "Amp", file: ".amp/settings.json", path: ["amp.mcpServers", "telex"], value: std },
+        { id: "opencode", label: "opencode", file: "opencode.json", path: ["mcp", "telex"], value: (e) => ({ type: "local", command: [e.command, ...e.args], ...(e.env ? { environment: e.env } : {}) }) },
+        { id: "crush", label: "Crush", file: ".crush.json", path: ["mcp", "telex"], value: (e) => ({ type: "stdio", ...e }) },
+    ];
+}
+/** What the agent's file should contain, standalone — used for printing and for a fresh file. */
+export function snippet(agent, entry) {
+    if (agent.toml)
+        return tomlBlock(entry);
+    return JSON.stringify(nest(agent.path, agent.value(entry)), null, 2);
+}
+export function tomlBlock(entry) {
+    const lines = [`[mcp_servers.telex]`, `command = "${entry.command}"`, `args = [${entry.args.map((a) => `"${a}"`).join(", ")}]`];
+    if (entry.env) {
+        lines.push(``, `[mcp_servers.telex.env]`, ...Object.entries(entry.env).map(([k, v]) => `${k} = "${v}"`));
+    }
+    return lines.join("\n");
+}
+const nest = (path, value) => path.reduceRight((acc, key) => ({ [key]: acc }), value);
+/** Run the agent's own installer. Returns null when its binary is not on PATH. */
+export function runCli(argv, cwd) {
+    const run = spawnSync(argv[0], argv.slice(1), { cwd, encoding: "utf8" });
+    if (run.error && run.error.code === "ENOENT")
+        return null;
+    const output = `${run.stdout ?? ""}${run.stderr ?? ""}`.trim();
+    return { ok: run.status === 0, how: argv.join(" "), output };
+}
+/** Merge the entry into the agent's config file, keeping whatever else is in there. */
+export function writeFileConfig(agent, entry, dir, local) {
+    const rel = (local && agent.localFile) || agent.file;
+    const path = join(dir, rel);
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    const next = agent.toml ? mergeToml(existing, entry) : mergeJson(existing, agent, entry);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, next);
+    return { ok: true, how: `wrote ${rel}` };
+}
+function mergeJson(existing, agent, entry) {
+    const root = existing.trim() ? JSON.parse(existing) : {};
+    let node = root;
+    for (const key of agent.path.slice(0, -1)) {
+        if (typeof node[key] !== "object" || node[key] === null)
+            node[key] = {};
+        node = node[key];
+    }
+    node[agent.path[agent.path.length - 1]] = agent.value(entry);
+    return `${JSON.stringify(root, null, 2)}\n`;
+}
+/** Replace an existing [mcp_servers.telex] block (and its sub-tables) or append a new one. */
+export function mergeToml(existing, entry) {
+    const lines = existing.split("\n");
+    const start = lines.findIndex((l) => l.trim() === "[mcp_servers.telex]");
+    if (start === -1) {
+        const head = existing.trim();
+        return `${head ? `${head}\n\n` : ""}${tomlBlock(entry)}\n`;
+    }
+    let end = start + 1;
+    while (end < lines.length && !/^\s*\[/.test(lines[end]))
+        end++;
+    while (end < lines.length && lines[end].trim().startsWith("[mcp_servers.telex.")) {
+        end++;
+        while (end < lines.length && !/^\s*\[/.test(lines[end]))
+            end++;
+    }
+    const merged = [...lines.slice(0, start), ...tomlBlock(entry).split("\n"), "", ...lines.slice(end)];
+    return `${merged.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}\n`;
+}
+/** A local-only config is worthless if git picks it up anyway. */
+export function ensureGitignored(dir, rel) {
+    const path = join(dir, ".gitignore");
+    const existing = existsSync(path) ? readFileSync(path, "utf8") : "";
+    const patterns = [rel, `/${rel}`, `${rel}/`];
+    if (existing.split("\n").some((l) => patterns.includes(l.trim())))
+        return null;
+    writeFileSync(path, `${existing.replace(/\n*$/, "")}${existing.trim() ? "\n" : ""}${rel}\n`);
+    return ".gitignore";
+}
+//# sourceMappingURL=agents.js.map

package/dist/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../src/agents.ts"],"names":[],"mappings":"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"}