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.
|
|
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",
|
package/config.example.json
CHANGED
|
@@ -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
|
|
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,
|
|
16
|
-
(`isolateTopics: true`)
|
|
17
|
-
`isolateTopics: false` don't qualify; give the
|
|
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…", "
|
|
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
|
|
93
|
-
`maxDepth`, so it can reply but not start a
|
|
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
|
|
131
|
-
|
|
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
|
|
136
|
-
and fails otherwise, including for a token from before a restart. A
|
|
137
|
-
agent runs (the agent-org `tasks` CLI) passes the session's mailbox
|
|
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
|
-
|
|
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
|
}
|
package/lib/mailbox/service.js
CHANGED
|
@@ -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
|
-
|
|
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
|
|
265
|
-
|
|
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.
|
|
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": {
|