polygram 0.42.0 → 0.43.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.42.0",
4
+ "version": "0.43.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",
@@ -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,
@@ -132,10 +135,20 @@ to the IPC socket with the bot's secret, like any other IPC client.
132
135
 
133
136
  The reply is `{id, state}` like `send`, with `duplicate: true` on a key hit.
134
137
 
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.
138
+ `mailbox_identify {token}` returns `{role, depth}` for a live role-session
139
+ token and fails otherwise, including for a token from before a restart. A
140
+ tool an agent runs (the agent-org `tasks` CLI) passes the session's mailbox
141
+ token and lets the daemon say which role is calling. `depth` is the
142
+ session's current depth, the one `send` would use:
143
+
144
+ - 0 when the last prompt polygram sent the session was a human message or a
145
+ system tell;
146
+ - the message's depth after a mailbox delivery;
147
+ - `limits.maxDepth` after any other automation turn, or before the
148
+ session's first prompt since boot.
149
+
150
+ So `depth: 0` means a human asked in this turn (or a system sender started
151
+ it).
139
152
 
140
153
  ## Error codes
141
154
 
@@ -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,15 @@ 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 or a system tell, so the tool can tell whether a human asked
236
+ // in this turn.
234
237
  identify(input) {
235
238
  requireEnabled();
236
239
  checkFields(input, ['token']);
237
- return { role: caller(input.token).role };
240
+ const { role, depth } = caller(input.token);
241
+ return { role, depth };
238
242
  },
239
243
  // A tell from a configured process outside any session, such as the
240
244
  // organization's task runner, which has no token. The caller's key, not
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "polygram",
3
- "version": "0.42.0",
3
+ "version": "0.43.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": {