polygram 0.42.0 → 0.43.1

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.42.0",
4
+ "version": "0.43.1",
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",
@@ -11,7 +11,7 @@
11
11
  "needsToken": false,
12
12
  "_comment_claudeCliAuthSource": "native (default) checks the host Claude login before CLI turns. Set external only when the configured session launcher supplies proxy credentials. SDK retains native checks; Codex is unaffected. Requires a verified pinned CLI and an absolute session launcher. Restart after changes; restore native when disabling proxy routing.",
13
13
  "claudeCliAuthSource": "native",
14
- "_comment_externalJobs": "Opt-in external conversation jobs. Routes reference configured destinations; forum topics must be isolated. maxConcurrent caps turns running at once across conversations (default 4). Protocol v1 supports Claude CLI. See docs/EXTERNAL_JOBS_API.md.",
14
+ "_comment_externalJobs": "Opt-in external conversation jobs. Routes reference configured destinations; forum topics must be isolated, and {chatId, general: true} with no threadId names a forum's General topic. maxConcurrent caps turns running at once across conversations (default 4). Protocol v1 supports Claude CLI. See docs/EXTERNAL_JOBS_API.md.",
15
15
  "externalJobs": {
16
16
  "enabled": false,
17
17
  "maxPending": 1000,
@@ -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 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 (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.",
49
49
  "mailbox": {
50
50
  "enabled": false,
51
51
  "roles": {
@@ -14,7 +14,12 @@ conversation still runs one job at a time, in submission order. A busy
14
14
  conversation keeps its job queued until the next scheduling pass (a submit, a
15
15
  resume, a finished turn or the 60-second timer).
16
16
  Each route has `chatId` and optional `threadId`. Forum destinations require an
17
- explicit configured isolated topic. Version 1 dispatch supports Claude CLI only.
17
+ explicit configured isolated topic, or `"general": true` with no `threadId` for
18
+ the forum's General topic. General is the session polygram keys by the bare
19
+ chat id, and its reports post without `message_thread_id`. The flag must be
20
+ exactly `true`, and a route may not combine it with a `threadId`. In a forum
21
+ without `isolateTopics`, every topic shares that session, but `/automation`
22
+ only works when sent in General. Version 1 dispatch supports Claude CLI only.
18
23
  Route names and request IDs are nonempty bounded strings; request IDs must be
19
24
  stable across transport retries. The `mailbox:` and `mailbox-notice:` request
20
25
  ID prefixes are reserved for the [session mailbox](./MAILBOX.md); jobs using
package/docs/MAILBOX.md CHANGED
@@ -12,12 +12,15 @@ Phase 1 delivers only to Claude CLI sessions of one bot on one host.
12
12
 
13
13
  - [External jobs](./EXTERNAL_JOBS_API.md) are enabled. Messages travel as
14
14
  external jobs, so pause, idle-only admission and job reports apply.
15
- - Each role is an existing session: a non-forum chat, or an isolated topic
16
- (`isolateTopics: true`) on the CLI backend. Groups that run with
17
- `isolateTopics: false` don't qualify; give the organization its own forum
18
- group.
15
+ - Each role is an existing session on the CLI backend: a non-forum chat, an
16
+ isolated topic (`isolateTopics: true`), or a forum's General topic. Topics
17
+ in groups that run with `isolateTopics: false` don't qualify; give the
18
+ organization its own forum group.
19
19
  - Each role key is also an `externalJobs.routes` key that points at that
20
- session. No two roles may share a session.
20
+ session. No two roles may share a session. A General role's route is
21
+ `{ "chatId": "…", "general": true }` with no `threadId`. Its session is
22
+ the bare chat id, distinct from every topic's session, and its mirror,
23
+ reports and `/automation` all use General.
21
24
 
22
25
  Boot fails on any configuration error, so a typo can't silently weaken the
23
26
  rules.
@@ -26,7 +29,7 @@ rules.
26
29
 
27
30
  ```json
28
31
  "externalJobs": { "enabled": true, "maxConcurrent": 4, "routes": {
29
- "orchestrator": { "chatId": "-100…", "threadId": "11" },
32
+ "orchestrator": { "chatId": "-100…", "general": true },
30
33
  "marketing": { "chatId": "-100…", "threadId": "12" } } },
31
34
  "mailbox": {
32
35
  "enabled": true,
@@ -46,7 +49,7 @@ rules.
46
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. |
47
50
  | `mirror` | Post each message into the target role's topic. Default `true`. |
48
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. |
49
- | `limits.maxDepth` | Longest chain. A human message starts at depth 0, and each new message is one deeper. Default 2. |
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. |
50
53
  | `limits.perPairPerHour` | Asks and tells per (from, to) pair in the last hour. Default 10. |
51
54
  | `limits.maxBodyBytes` | Body size in UTF-8 bytes, before and after redaction. Default and maximum 3500, so a mirror fits one Telegram message. |
52
55
  | `limits.systemPerHour` | Messages per system sender in the last hour. Default 60. |
@@ -89,8 +92,9 @@ text lands in its own topic through the normal job report.
89
92
  identical retried reply returns the stored one. Nothing is forwarded
90
93
  automatically.
91
94
  - Depth: a turn started by a human is depth 0, and a mailbox delivery has its
92
- message's depth. Any other automation turn (notifications, notices) is at
93
- `maxDepth`, so it can reply but not start a chain.
95
+ message's depth (1 for a system tell). Any other automation turn
96
+ (notifications, notices) is at `maxDepth`, so it can reply but not start a
97
+ chain.
94
98
  - Rate: at most `perPairPerHour` asks and tells per pair.
95
99
  - The same (from, to, kind, body) within ten minutes returns the existing message
96
100
  with `duplicate: true`, unless the sender already had a notice about it; then
@@ -127,15 +131,26 @@ to the IPC socket with the bot's secret, like any other IPC client.
127
131
  organization's task system (system:<sender>), not a human instruction and
128
132
  not authorization: paid, outward-facing or destructive actions still need
129
133
  a human go."
130
- - The receiving turn starts at depth 0, as for a human message, so the role
131
- may start a chain.
134
+ - The message has depth 1, so the receiving turn starts at depth 1, one
135
+ below a human message. Under the default `maxDepth` of 2 the role can still
136
+ send an ask or tell (at depth 2), whose receiver can only reply. With
137
+ `maxDepth` 1 the role can only reply.
132
138
 
133
139
  The reply is `{id, state}` like `send`, with `duplicate: true` on a key hit.
134
140
 
135
- `mailbox_identify {token}` returns `{role}` for a live role-session token
136
- and fails otherwise, including for a token from before a restart. A tool an
137
- agent runs (the agent-org `tasks` CLI) passes the session's mailbox token
138
- and lets the daemon say which role is calling.
141
+ `mailbox_identify {token}` returns `{role, depth}` for a live role-session
142
+ token and fails otherwise, including for a token from before a restart. A
143
+ tool an agent runs (the agent-org `tasks` CLI) passes the session's mailbox
144
+ token and lets the daemon say which role is calling. `depth` is the
145
+ session's current depth, the one `send` would use:
146
+
147
+ - 0 when the last prompt polygram sent the session was a human message;
148
+ - the message's depth after a mailbox delivery, 1 for a system tell;
149
+ - `limits.maxDepth` after any other automation turn, or before the
150
+ session's first prompt since boot.
151
+
152
+ So `depth: 0` means a human asked in this turn; a turn a system sender
153
+ started reports 1.
139
154
 
140
155
  ## Error codes
141
156
 
@@ -9,7 +9,13 @@ function createExternalJobTargetResolver({ config, getSessionKey, resolveBackend
9
9
  if (!chat) throw new Error('External job destination is not a configured chat');
10
10
  const threadId = route.threadId == null ? null : String(route.threadId);
11
11
  const forum = chat.isForum === true || chat.is_forum === true || chat.isolateTopics === true || Object.keys(chat.topics || {}).length > 0;
12
- if (forum || threadId != null) {
12
+ // A forum's General topic has no thread id: polygram runs it as the
13
+ // bare-chat session and posts there without message_thread_id. A route
14
+ // must opt in with `general: true`, so a route that forgot its topic
15
+ // never lands in General silently.
16
+ const general = route.general === true;
17
+ if (general && threadId != null) throw new Error('External job General route cannot also name a topic');
18
+ if (!general && (forum || threadId != null)) {
13
19
  if (!threadId || !/^[1-9]\d*$/.test(threadId) || !Object.hasOwn(chat.topics || {}, threadId)) {
14
20
  throw new Error('External job destination requires an explicit configured topic');
15
21
  }
@@ -230,11 +230,14 @@ function createMailboxService({ config, db, botName, jobs, resolveTarget, bot =
230
230
  },
231
231
  // The role behind a live role-session token, so a tool an agent runs
232
232
  // (such as the task CLI) learns who is calling from the daemon instead
233
- // of trusting the agent's word.
233
+ // of trusting the agent's word. `depth` is the depth send would use:
234
+ // 0 only while the last prompt polygram sent the session was a human
235
+ // message, so the tool can tell whether a human asked in this turn.
234
236
  identify(input) {
235
237
  requireEnabled();
236
238
  checkFields(input, ['token']);
237
- return { role: caller(input.token).role };
239
+ const { role, depth } = caller(input.token);
240
+ return { role, depth };
238
241
  },
239
242
  // A tell from a configured process outside any session, such as the
240
243
  // organization's task runner, which has no token. The caller's key, not
@@ -261,8 +264,10 @@ function createMailboxService({ config, db, botName, jobs, resolveTarget, bot =
261
264
  if (!cfg.roles.has(input.to)) throw rules.refusal(rules.REFUSAL.unknownRole, 'Unknown role');
262
265
  const body = rules.cleanBody(input.body, cfg.limits.maxBodyBytes);
263
266
  rules.checkSystemRate(store.countFrom(fromAddr, now() - rules.RATE_WINDOW_MS), cfg.limits.systemPerHour);
264
- // Depth 0, as for a human message: the receiving turn may start a chain.
265
- const created = record({ kind: 'tell', from: fromAddr, to: toAddr, routeId: input.to, body, inReplyTo: null, depth: 0, bodyHash: hash, idemKey: key, ref });
267
+ // Depth 1, one below a human message: depth 0 stays reserved for a
268
+ // turn a human started, while the receiving role can still ask or
269
+ // tell another role under the default maxDepth.
270
+ const created = record({ kind: 'tell', from: fromAddr, to: toAddr, routeId: input.to, body, inReplyTo: null, depth: 1, bodyHash: hash, idemKey: key, ref });
266
271
  deliver(created);
267
272
  return { result: receipt(created), row: created };
268
273
  });
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "polygram",
3
- "version": "0.42.0",
3
+ "version": "0.43.1",
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": {