polygram 0.44.0 → 0.45.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://anthropic.com/claude-code/plugin.schema.json",
3
3
  "name": "polygram",
4
- "version": "0.44.0",
4
+ "version": "0.45.0",
5
5
  "description": "Telegram integration for Claude Code that preserves the OpenClaw per-chat session model. Migration target for OpenClaw users. Multi-bot, multi-chat, per-topic isolation; SQLite transcripts; inline-keyboard approvals. Bundles /polygram:status|logs|pair-code|approvals admin commands plus history (transcript queries) and polygram-send (out-of-turn IPC sends with file-upload validation) skills.",
6
6
  "keywords": [
7
7
  "telegram",
@@ -45,7 +45,7 @@
45
45
  "admin": { "routeId": "scheduled-review", "generation": "netdata-v1", "baseline": 0 }
46
46
  }
47
47
  },
48
- "_comment_mailbox": "Opt-in messages between role sessions (ask, tell, reply). Each role key is an externalJobs route id for its own isolated topic or a forum's General topic on the Claude CLI backend; no two roles may share a session. allow lists who may start an ask or tell to whom (\"*\" = every role); replies are never checked against it. mirror posts each message into the target role's topic (default true). systemSenders names processes outside any session (such as the agent-org task runner) that may send tells as system:<name> through the IPC op mailbox_submit; default none, and polygram is reserved. Limits default to maxDepth 2, perPairPerHour 10, maxBodyBytes 3500 (also the ceiling), systemPerHour 60 (per system sender). Setting enabled false withdraws queued mailbox jobs unsent. See docs/MAILBOX.md.",
48
+ "_comment_mailbox": "Opt-in messages between role sessions (ask, tell, reply). Each role key is an externalJobs route id for its own isolated topic or a forum's General topic on the Claude CLI backend; no two roles may share a session. allow lists who may start an ask or tell to whom (\"*\" = every role); replies are never checked against it. mirror posts each message into the target role's topic (true or \"target\", the default); \"both\" also posts a short sender line into the sending role's topic; false posts nothing. systemSenders names processes outside any session (such as the agent-org task runner) that may send tells as system:<name> through the IPC op mailbox_submit; default none, and polygram is reserved. Limits default to maxDepth 2, perPairPerHour 10, maxBodyBytes 3500 (also the ceiling), systemPerHour 60 (per system sender). Setting enabled false withdraws queued mailbox jobs unsent. See docs/MAILBOX.md.",
49
49
  "mailbox": {
50
50
  "enabled": false,
51
51
  "roles": {
package/docs/MAILBOX.md CHANGED
@@ -47,7 +47,7 @@ rules.
47
47
  | `enabled` | Must be `true`. Without a `mailbox` key nothing changes. |
48
48
  | `roles.<name>` | Role name = route id, `^[a-z][a-z0-9_-]*$`. `about` (≤ 300 characters) is shown to the roles allowed to message it. |
49
49
  | `allow.<name>` | Roles this role may start an `ask` or `tell` to; `"*"` means every role. A role without an entry can only reply. Replies are never checked against it. |
50
- | `mirror` | Post each message into the target role's topic. Default `true`. |
50
+ | `mirror` | Where each message is posted as plain text: `"target"` (or `true`) posts it into the target role's topic; `"both"` also posts a sender line into the sending role's topic; `false` posts nothing. Default `true`. See [Telegram mirror](#telegram-mirror). |
51
51
  | `systemSenders` | Names of processes outside any session that may send through `mailbox_submit` as `system:<name>` (see [System senders](#system-senders)). Distinct names, `^[a-z][a-z0-9_-]*$`; `polygram` is reserved. Default none. |
52
52
  | `limits.maxDepth` | Longest chain. A human message starts at depth 0, a system tell is depth 1, and each new message is one deeper. Default 2. |
53
53
  | `limits.perPairPerHour` | Asks and tells per (from, to) pair in the last hour. Default 10. |
@@ -101,6 +101,29 @@ text lands in its own topic through the normal job report.
101
101
  it is a deliberate re-ask and creates a new message.
102
102
  - Bodies are redacted before they are stored, hashed or mirrored.
103
103
 
104
+ ## Telegram mirror
105
+
106
+ Each message is posted once, right after it commits, never from the
107
+ dispatch path. The target role's topic gets the whole redacted body:
108
+
109
+ ```
110
+ 📨 role:orchestrator → role:marketing (ask m_…)
111
+ <body>
112
+ ```
113
+
114
+ With `"mirror": "both"`, the sending role's topic also gets a sender line,
115
+ so a role's chat shows what it sent. It carries the first 300 characters of
116
+ the redacted body, with `…` when the body is longer:
117
+
118
+ ```
119
+ 📤 role:orchestrator → role:marketing (ask m_…)
120
+ <first 300 characters of the body>
121
+ ```
122
+
123
+ Only a `role:` sender has a topic, so a system sender's message gets the
124
+ target line only. A failed post is logged and never blocks delivery or the
125
+ other post. Duplicates and refused messages are not posted.
126
+
104
127
  ## System senders
105
128
 
106
129
  A process outside every session, such as the agent-org task runner, can
@@ -123,7 +146,8 @@ to the IPC socket with the bot's secret, like any other IPC client.
123
146
  - `limits.systemPerHour` applies per sender, counted only after the key
124
147
  lookup, so a retry of an accepted message is never rate limited. System
125
148
  sends don't use up a role pair's budget.
126
- - The size cap, redaction and mirror apply as for agent messages.
149
+ - The size cap, redaction and target mirror apply as for agent messages.
150
+ A system sender has no topic, so it never gets a sender line.
127
151
  - `ref` (optional, 1 to 512 bytes) is an opaque reference such as a task id
128
152
  or URL. It is redacted, stored, and shown to the receiver only inside the
129
153
  untrusted payload, never in the trusted header.
@@ -77,4 +77,13 @@ function renderMirror(row) {
77
77
  return `📨 ${row.from_addr} → ${row.to_addr} (${row.kind} ${row.id})\n${row.body}`;
78
78
  }
79
79
 
80
- module.exports = { renderTask, renderPayload, renderNoticeTask, renderNoticePayload, renderMirror };
80
+ // The line for the sending role's own topic, so that topic shows what the
81
+ // role sent. The body is cut by code points so no character is split.
82
+ const SENDER_MIRROR_CHARS = 300;
83
+ function renderSenderMirror(row) {
84
+ const chars = Array.from(row.body);
85
+ const body = chars.length > SENDER_MIRROR_CHARS ? `${chars.slice(0, SENDER_MIRROR_CHARS).join('')}…` : row.body;
86
+ return `📤 ${row.from_addr} → ${row.to_addr} (${row.kind} ${row.id})\n${body}`;
87
+ }
88
+
89
+ module.exports = { renderTask, renderPayload, renderNoticeTask, renderNoticePayload, renderMirror, renderSenderMirror };
@@ -13,6 +13,9 @@ const MAILBOX_KEYS = ['enabled', 'roles', 'allow', 'mirror', 'limits', 'systemSe
13
13
  // header must fit one Telegram message.
14
14
  const DEFAULT_LIMITS = Object.freeze({ maxDepth: 2, perPairPerHour: 10, maxBodyBytes: 3500, systemPerHour: 60 });
15
15
  const MAX_BODY_BYTES = 3500;
16
+ // Where each message is posted: nowhere, the target role's topic, or the
17
+ // target's and the sending role's topics.
18
+ const MIRROR_MODES = new Map([[false, false], [true, 'target'], ['target', 'target'], ['both', 'both']]);
16
19
  const MAX_ABOUT = 300;
17
20
  const MAX_KEY_BYTES = 256;
18
21
  const MAX_REF_BYTES = 512;
@@ -80,8 +83,9 @@ function readMailboxConfig(bot, resolveTarget) {
80
83
  throw new Error('Invalid mailbox systemSenders: list distinct names of lowercase letters, digits, - and _');
81
84
  }
82
85
  if (systemSenders.includes(RESERVED_SENDER)) throw new Error(`Invalid mailbox systemSenders: ${RESERVED_SENDER} is reserved for the daemon's own notices`);
83
- const mirror = settings.mirror ?? true;
84
- if (typeof mirror !== 'boolean') throw new Error('Mailbox mirror must be true or false');
86
+ // `true` predates the sender line and keeps meaning the target topic only.
87
+ const mirror = MIRROR_MODES.get(settings.mirror ?? true);
88
+ if (mirror === undefined) throw new Error('Mailbox mirror must be true, false, "target" or "both"');
85
89
  const limits = { ...DEFAULT_LIMITS };
86
90
  for (const [key, value] of Object.entries(settings.limits || {})) {
87
91
  if (!Object.hasOwn(DEFAULT_LIMITS, key) || !Number.isSafeInteger(value) || value < 1) throw new Error(`Invalid mailbox limit ${key}`);
@@ -73,15 +73,23 @@ function createMailboxService({ config, db, botName, jobs, resolveTarget, bot =
73
73
  }
74
74
  // Posted once, after the message commits, never from the dispatch path,
75
75
  // which retries on deferral. A failed post is logged and never blocks
76
- // delivery; the target's final text reaches the same topic as the job report.
76
+ // delivery or the other post; the target's final text reaches the same
77
+ // topic as the job report. Only a role sender has a topic of its own.
77
78
  function mirror(row) {
78
- const target = cfg.roles.get(row.route_id)?.target;
79
- if (!cfg.mirror || !tg || !target) return;
79
+ if (!cfg.mirror || !tg) return;
80
+ post(cfg.roles.get(row.route_id)?.target, envelope.renderMirror(row), 'mailbox-mirror', `mirror of ${row.id}`);
81
+ if (cfg.mirror === 'both') {
82
+ const sender = rules.roleFromAddress(row.from_addr);
83
+ post(sender ? cfg.roles.get(sender)?.target : null, envelope.renderSenderMirror(row), 'mailbox-sender-mirror', `sender mirror of ${row.id}`);
84
+ }
85
+ }
86
+ function post(target, text, source, what) {
87
+ if (!target) return;
80
88
  Promise.resolve()
81
- .then(() => tg(bot, 'sendMessage', { chat_id: target.chatId, ...(target.threadId == null ? {} : { message_thread_id: target.threadId }), text: envelope.renderMirror(row) },
82
- { source: 'mailbox-mirror', botName, sessionKey: target.sessionKey, plainText: true, strictDestination: true }))
89
+ .then(() => tg(bot, 'sendMessage', { chat_id: target.chatId, ...(target.threadId == null ? {} : { message_thread_id: target.threadId }), text },
90
+ { source, botName, sessionKey: target.sessionKey, plainText: true, strictDestination: true }))
83
91
  // Telegram's description is API text, not message content.
84
- .catch((error) => logger.error?.(`[mailbox] mirror of ${row.id} failed: ${error?.error_code ?? error?.code ?? error?.name ?? 'Error'}${error?.description ? ` ${error.description}` : ''}`));
92
+ .catch((error) => logger.error?.(`[mailbox] ${what} failed: ${error?.error_code ?? error?.code ?? error?.name ?? 'Error'}${error?.description ? ` ${error.description}` : ''}`));
85
93
  }
86
94
  // Only a missing job means "not there"; any other lookup failure is
87
95
  // rethrown so the caller holds the work instead of guessing.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "polygram",
3
- "version": "0.44.0",
3
+ "version": "0.45.0",
4
4
  "description": "Telegram daemon for Claude Code that preserves the OpenClaw per-chat session model. Migration path for OpenClaw users moving to Claude Code.",
5
5
  "main": "lib/ipc/client.js",
6
6
  "bin": {