polygram 0.41.3 → 0.42.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.
@@ -0,0 +1,288 @@
1
+ 'use strict';
2
+
3
+ const path = require('node:path');
4
+ const { randomBytes, randomUUID } = require('node:crypto');
5
+ const rules = require('./rules');
6
+ const envelope = require('./envelope');
7
+ const { createMailboxStore } = require('./store');
8
+
9
+ const SCRIPT = path.resolve(__dirname, '../../skills/mailbox/scripts/msg.js');
10
+ const MAILBOX_REQUEST = 'mailbox:';
11
+ const NOTICE_REQUEST = 'mailbox-notice:';
12
+ const POLL_MS = 5000;
13
+ const RETRY_MS = 60000;
14
+ const RETRY_MAX_MS = 30 * 60000;
15
+ const SETTLED = new Set(['succeeded', 'failed', 'interrupted', 'unknown']);
16
+
17
+ const isMailboxRequest = (requestId) => typeof requestId === 'string'
18
+ && (requestId.startsWith(MAILBOX_REQUEST) || requestId.startsWith(NOTICE_REQUEST));
19
+
20
+ function checkFields(input, allowed) {
21
+ if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('Mailbox input object required');
22
+ for (const key of Object.keys(input)) if (!allowed.includes(key)) throw new Error(`Unknown mailbox field: ${key}`);
23
+ }
24
+
25
+ // Messages between role sessions. Each role session holds one in-memory token
26
+ // that resolves to its role and to the depth of the last prompt polygram sent
27
+ // it, so the daemon, never the agent, decides who is speaking and how deep
28
+ // the conversation already is.
29
+ // `ipcDir` is the daemon's IPC runtime directory. The agent's command carries
30
+ // it because a CLI session inherits its environment from whoever started the
31
+ // tmux server, which is often not the daemon; msg.js then finds the socket
32
+ // and the 0600 secret file there.
33
+ function createMailboxService({ config, db, botName, jobs, resolveTarget, bot = null, tg = null, ipcDir = null, now = Date.now, logger = console }) {
34
+ const cfg = rules.readMailboxConfig(config.bot, resolveTarget);
35
+ const raw = db?.raw;
36
+ const store = cfg ? createMailboxStore(raw, { botName, now }) : null;
37
+ const tokens = new Map();
38
+ const tokenBySession = new Map();
39
+ const depths = new Map();
40
+ const transaction = (fn) => raw.transaction(fn).immediate();
41
+ const requireEnabled = () => { if (!cfg) throw rules.refusal(rules.REFUSAL.disabled, 'Mailbox is disabled'); };
42
+ const roleOf = (sessionKey) => cfg?.roleForSession(sessionKey) ?? null;
43
+ let started = false;
44
+ let timer = null;
45
+ let polling = null;
46
+ const retries = new Map();
47
+ const waiting = (key) => (retries.get(key)?.at ?? 0) > now();
48
+ function backOff(key) {
49
+ const attempts = (retries.get(key)?.attempts ?? 0) + 1;
50
+ retries.set(key, { attempts, at: now() + Math.min(RETRY_MS * 2 ** (attempts - 1), RETRY_MAX_MS) });
51
+ }
52
+
53
+ function caller(token) {
54
+ const sessionKey = typeof token === 'string' ? tokens.get(token) : undefined;
55
+ const role = sessionKey ? roleOf(sessionKey) : null;
56
+ if (!role) throw new Error('Mailbox token is not valid; use the command from your current turn');
57
+ // A session that has not been prompted since boot can only reply.
58
+ return { role, depth: depths.get(sessionKey) ?? cfg.limits.maxDepth };
59
+ }
60
+ // The message's real delivery state, so a retried send whose first
61
+ // delivery already failed, was withdrawn or became uncertain says so.
62
+ function receipt(row, extra = {}) {
63
+ const { job } = jobs.get({ routeId: row.route_id, requestId: MAILBOX_REQUEST + row.id });
64
+ return { id: row.id, state: job.state === 'queued' && job.paused ? 'paused' : job.state, ...extra };
65
+ }
66
+ function record(message) {
67
+ return store.insert({ ...message, id: `m_${randomBytes(8).toString('hex')}` });
68
+ }
69
+ // Runs inside the caller's transaction, so a refused submit also rolls the
70
+ // message row back and the refusal reaches the sender synchronously.
71
+ function deliver(row, ask = null) {
72
+ jobs.submit({ routeId: row.route_id, requestId: MAILBOX_REQUEST + row.id, task: envelope.renderTask(row), payload: envelope.renderPayload(row, ask) });
73
+ }
74
+ // Posted once, after the message commits, never from the dispatch path,
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.
77
+ function mirror(row) {
78
+ const target = cfg.roles.get(row.route_id)?.target;
79
+ if (!cfg.mirror || !tg || !target) return;
80
+ 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 }))
83
+ // 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}` : ''}`));
85
+ }
86
+ // Only a missing job means "not there"; any other lookup failure is
87
+ // rethrown so the caller holds the work instead of guessing.
88
+ function lookup(routeId, requestId) {
89
+ try { return jobs.get({ routeId, requestId }).job; }
90
+ catch (error) { if (error?.code === 'EXTERNAL_JOB_NOT_FOUND') return null; throw error; }
91
+ }
92
+ const held = (what, error) => logger.error?.(`[mailbox] ${what} held: ${error?.code || error?.name || 'Error'}`);
93
+ // A notice about an ask is keyed on the ask; one about a reply that never
94
+ // arrived is keyed on the reply, so a late reply that fails after a "no
95
+ // reply" notice is still reported. Either marks the ask as notified.
96
+ function notify(ask, requestId, task, payload) {
97
+ const routeId = rules.roleFromAddress(ask.from_addr);
98
+ transaction(() => {
99
+ if (!lookup(routeId, requestId)) jobs.submit({ routeId, requestId, task, payload });
100
+ store.markNoticeSent(ask.id);
101
+ });
102
+ }
103
+ // One notice per open ask once its delivery job has settled, and a
104
+ // recovery probe for every mailbox-owned job left unknown, so an uncertain
105
+ // turn does not block its session's queue. Neither ever replays a message.
106
+ // Every failure is logged with its ids and code and backs off, from one
107
+ // minute up to thirty, so a stuck item never retries on every poll.
108
+ async function poll() {
109
+ const live = new Set();
110
+ for (const ask of store.noticeCandidates()) {
111
+ if (!started) return;
112
+ const key = `notice:${ask.id}`;
113
+ live.add(key);
114
+ if (waiting(key)) continue;
115
+ try {
116
+ const delivery = lookup(ask.route_id, MAILBOX_REQUEST + ask.id);
117
+ if (!delivery) throw Object.assign(new Error('Ask delivery job is missing'), { code: 'MAILBOX_DELIVERY_MISSING' });
118
+ if (!SETTLED.has(delivery.state)) continue;
119
+ notify(ask, NOTICE_REQUEST + ask.id, envelope.renderNoticeTask(ask, delivery.state), envelope.renderNoticePayload(ask, delivery));
120
+ retries.delete(key);
121
+ } catch (error) { backOff(key); held(`notice for ask ${ask.id}`, error); }
122
+ }
123
+ for (const row of store.undeliveredReplies()) {
124
+ if (!started) return;
125
+ const key = `reply-notice:${row.id}`;
126
+ live.add(key);
127
+ if (waiting(key)) continue;
128
+ try {
129
+ const ask = store.get(row.in_reply_to);
130
+ const delivery = lookup(row.route_id, MAILBOX_REQUEST + row.id);
131
+ if (!ask || !delivery) throw Object.assign(new Error('Reply or its delivery job is missing'), { code: 'MAILBOX_REPLY_MISSING' });
132
+ const reply = { ...delivery, id: row.id };
133
+ const reason = reply.state === 'unknown' ? 'reply-uncertain' : 'reply-undelivered';
134
+ notify(ask, NOTICE_REQUEST + row.id, envelope.renderNoticeTask(ask, reason), envelope.renderNoticePayload(ask, null, reply));
135
+ retries.delete(key);
136
+ } catch (error) { backOff(key); held(`notice for reply ${row.id}`, error); }
137
+ }
138
+ for (const job of store.unrecoveredJobs()) {
139
+ if (!started) return;
140
+ const key = `recover:${job.route_id}:${job.request_id}`;
141
+ live.add(key);
142
+ if (waiting(key)) continue;
143
+ // Recovery refuses while the session is paused or busy; retry later.
144
+ try { await jobs.prepareRecovery({ routeId: job.route_id, requestId: job.request_id }); retries.delete(key); }
145
+ catch (error) { backOff(key); held(`recovery for ${job.request_id}`, error); }
146
+ }
147
+ // Asks that were answered or notified and jobs that became inactive by
148
+ // other means keep no retry state.
149
+ for (const key of retries.keys()) if (!live.has(key)) retries.delete(key);
150
+ }
151
+
152
+ const api = {
153
+ enabled: cfg !== null,
154
+ scope(sessionKey) {
155
+ if (!roleOf(sessionKey)) return null;
156
+ let token = tokenBySession.get(sessionKey);
157
+ if (!token) { token = randomUUID(); tokens.set(token, sessionKey); tokenBySession.set(sessionKey, token); }
158
+ return token;
159
+ },
160
+ // An inbound human message: the human is in the loop, so the turn may
161
+ // start a fresh chain.
162
+ noteHumanPrompt(sessionKey) {
163
+ if (roleOf(sessionKey)) depths.set(sessionKey, 0);
164
+ },
165
+ // Called at the moment an external job's prompt is actually sent. A
166
+ // mailbox delivery carries its message depth; every other job, notices
167
+ // included, gets maxDepth so its turn can reply but not start a chain.
168
+ noteJobSend(job) {
169
+ const sessionKey = job?.target?.sessionKey;
170
+ if (!roleOf(sessionKey)) return;
171
+ const id = typeof job.requestId === 'string' && job.requestId.startsWith(MAILBOX_REQUEST) ? job.requestId.slice(MAILBOX_REQUEST.length) : null;
172
+ const row = id ? store.get(id) : null;
173
+ depths.set(sessionKey, row && row.route_id === job.routeId ? row.depth : cfg.limits.maxDepth);
174
+ },
175
+ instructions(sessionKey) {
176
+ const role = roleOf(sessionKey);
177
+ if (!role) return '';
178
+ const command = [...(ipcDir ? [`POLYGRAM_IPC_DIR=${JSON.stringify(ipcDir)}`] : []),
179
+ ...[process.execPath, SCRIPT, botName, api.scope(sessionKey)].map((part) => JSON.stringify(part))].join(' ');
180
+ const targets = [...cfg.roles.values()].filter((other) => cfg.allowed(role, other.name))
181
+ .map((other) => (other.about ? `${other.name} (${other.about})` : other.name));
182
+ return `\nInter-session mailbox: you are role:${role} in an organization of agent sessions. Roles you may message: ${targets.length ? targets.join('; ') : 'none (you can still reply to asks you receive)'}.`
183
+ + ` Ask or tell another role: run ${command} send '{"to":"<role>","kind":"ask","body":"..."}' (kind "tell" expects no reply).`
184
+ + ` Reply to an ask you received: run ${command} reply '{"id":"<message id>","body":"..."}'.`
185
+ + ' An ask states the answer you need; do not hand work off through the mailbox yet. Send summaries and file paths, never transcripts.'
186
+ + ' Reply exactly once to each ask you receive. Replies arrive as a new turn after your turn ends, so never wait or poll for them.\n';
187
+ },
188
+ send(token, input) {
189
+ requireEnabled();
190
+ const from = caller(token);
191
+ checkFields(input, ['to', 'kind', 'body']);
192
+ rules.checkStart(cfg, { from: from.role, to: input.to, kind: input.kind });
193
+ const body = rules.cleanBody(input.body, cfg.limits.maxBodyBytes);
194
+ const hash = rules.bodyHash(body);
195
+ const fromAddr = rules.roleAddress(from.role);
196
+ const toAddr = rules.roleAddress(input.to);
197
+ const { result, row } = transaction(() => {
198
+ const duplicate = store.findDuplicate(fromAddr, toAddr, input.kind, hash, now() - rules.DUPLICATE_WINDOW_MS);
199
+ if (duplicate) return { result: receipt(duplicate, { duplicate: true }) };
200
+ const depth = rules.nextDepth(from.depth, cfg.limits.maxDepth);
201
+ rules.checkRate(store.countPair(fromAddr, toAddr, now() - rules.RATE_WINDOW_MS), cfg.limits.perPairPerHour);
202
+ const created = record({ kind: input.kind, from: fromAddr, to: toAddr, routeId: input.to, body, inReplyTo: null, depth, bodyHash: hash });
203
+ deliver(created);
204
+ return { result: receipt(created), row: created };
205
+ });
206
+ if (row) mirror(row);
207
+ return result;
208
+ },
209
+ reply(token, input) {
210
+ requireEnabled();
211
+ const from = caller(token);
212
+ checkFields(input, ['inReplyTo', 'body']);
213
+ const body = rules.cleanBody(input.body, cfg.limits.maxBodyBytes);
214
+ const hash = rules.bodyHash(body);
215
+ const fromAddr = rules.roleAddress(from.role);
216
+ const { result, row } = transaction(() => {
217
+ const ask = typeof input.inReplyTo === 'string' ? store.get(input.inReplyTo) : null;
218
+ const existing = ask ? store.replyTo(ask.id) : null;
219
+ // A retried reply with the same text returns the stored one.
220
+ if (existing && existing.from_addr === fromAddr && existing.body_hash === hash) return { result: receipt(existing, { duplicate: true }) };
221
+ rules.checkReply({ ask, caller: from.role, replied: existing !== null });
222
+ const asker = rules.roleFromAddress(ask.from_addr);
223
+ if (!cfg.roles.has(asker)) throw new Error('The asking role is no longer configured');
224
+ const created = record({ kind: 'reply', from: fromAddr, to: ask.from_addr, routeId: asker, body, inReplyTo: ask.id, depth: ask.depth, bodyHash: hash });
225
+ deliver(created, ask);
226
+ return { result: receipt(created), row: created };
227
+ });
228
+ if (row) mirror(row);
229
+ return result;
230
+ },
231
+ // The role behind a live role-session token, so a tool an agent runs
232
+ // (such as the task CLI) learns who is calling from the daemon instead
233
+ // of trusting the agent's word.
234
+ identify(input) {
235
+ requireEnabled();
236
+ checkFields(input, ['token']);
237
+ return { role: caller(input.token).role };
238
+ },
239
+ // A tell from a configured process outside any session, such as the
240
+ // organization's task runner, which has no token. The caller's key, not
241
+ // a time window, decides what is new: it is looked up before any other
242
+ // check, so a retry of an accepted message always gets that message's
243
+ // receipt, even when a limit would now refuse a new one.
244
+ submit(input) {
245
+ requireEnabled();
246
+ checkFields(input, ['sender', 'to', 'body', 'key', 'ref']);
247
+ const fromAddr = rules.systemAddress(rules.checkSystemSender(cfg, input.sender));
248
+ const key = rules.checkKey(input.key);
249
+ const ref = rules.cleanRef(input.ref);
250
+ if (typeof input.to !== 'string') throw rules.refusal(rules.REFUSAL.unknownRole, 'Unknown role');
251
+ const toAddr = rules.roleAddress(input.to);
252
+ const hash = rules.redactedBodyHash(input.body);
253
+ const { result, row } = transaction(() => {
254
+ const existing = store.findByKey(fromAddr, key);
255
+ if (existing) {
256
+ if (existing.to_addr !== toAddr || existing.body_hash !== hash) {
257
+ throw rules.refusal(rules.REFUSAL.keyConflict, 'Idempotency key already used for a different target or body');
258
+ }
259
+ return { result: receipt(existing, { duplicate: true }) };
260
+ }
261
+ if (!cfg.roles.has(input.to)) throw rules.refusal(rules.REFUSAL.unknownRole, 'Unknown role');
262
+ const body = rules.cleanBody(input.body, cfg.limits.maxBodyBytes);
263
+ 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 });
266
+ deliver(created);
267
+ return { result: receipt(created), row: created };
268
+ });
269
+ if (row) mirror(row);
270
+ return result;
271
+ },
272
+ tick() {
273
+ if (!started) return Promise.resolve();
274
+ if (!polling) polling = poll().catch((error) => logger.error?.(`[mailbox] polling failed: ${error?.code || error?.name || 'Error'}`)).finally(() => { polling = null; });
275
+ return polling;
276
+ },
277
+ start() {
278
+ if (started || !cfg) return;
279
+ started = true;
280
+ timer = setInterval(() => void api.tick(), POLL_MS); timer.unref?.();
281
+ void api.tick();
282
+ },
283
+ stop() { started = false; clearInterval(timer); timer = null; },
284
+ };
285
+ return api;
286
+ }
287
+
288
+ module.exports = { createMailboxService, isMailboxRequest, MAILBOX_REQUEST, NOTICE_REQUEST };
@@ -0,0 +1,60 @@
1
+ 'use strict';
2
+
3
+ // SQL access for mailbox_messages. Every query is scoped to one bot.
4
+ function createMailboxStore(db, { botName, now = Date.now }) {
5
+ const byId = db.prepare('SELECT * FROM mailbox_messages WHERE id=? AND bot_name=?');
6
+ return {
7
+ insert(m) {
8
+ db.prepare(`INSERT INTO mailbox_messages(id,bot_name,kind,from_addr,to_addr,route_id,body,in_reply_to,depth,body_hash,created_at,idem_key,ref)
9
+ VALUES (?,?,?,?,?,?,?,?,?,?,?,?,?)`).run(m.id, botName, m.kind, m.from, m.to, m.routeId, m.body, m.inReplyTo ?? null, m.depth, m.bodyHash, now(),
10
+ m.idemKey ?? null, m.ref ?? null);
11
+ return byId.get(m.id, botName);
12
+ },
13
+ get(id) { return byId.get(id, botName) ?? null; },
14
+ // The message a sender already created under an idempotency key.
15
+ findByKey(from, key) {
16
+ return db.prepare('SELECT * FROM mailbox_messages WHERE bot_name=? AND from_addr=? AND idem_key=?').get(botName, from, key) ?? null;
17
+ },
18
+ replyTo(askId) {
19
+ return db.prepare("SELECT * FROM mailbox_messages WHERE bot_name=? AND in_reply_to=? AND kind='reply'").get(botName, askId) ?? null;
20
+ },
21
+ countFrom(from, since) {
22
+ return db.prepare('SELECT count(*) n FROM mailbox_messages WHERE bot_name=? AND from_addr=? AND created_at>=?').get(botName, from, since).n;
23
+ },
24
+ countPair(from, to, since) {
25
+ return db.prepare(`SELECT count(*) n FROM mailbox_messages WHERE bot_name=? AND from_addr=? AND to_addr=?
26
+ AND created_at>=? AND kind IN ('ask','tell')`).get(botName, from, to, since).n;
27
+ },
28
+ // Once the sender has had a notice about a message, an identical send is
29
+ // a deliberate re-ask rather than a retry, so it no longer matches.
30
+ findDuplicate(from, to, kind, bodyHash, since) {
31
+ return db.prepare(`SELECT * FROM mailbox_messages WHERE bot_name=? AND from_addr=? AND to_addr=? AND created_at>=?
32
+ AND body_hash=? AND kind=? AND notice_sent=0 ORDER BY created_at DESC, rowid DESC LIMIT 1`).get(botName, from, to, since, bodyHash, kind) ?? null;
33
+ },
34
+ // Asks with no reply whose asker has not been told how the delivery
35
+ // ended. A reply that never arrives is reported by undeliveredReplies.
36
+ noticeCandidates() {
37
+ return db.prepare(`SELECT * FROM mailbox_messages m WHERE m.bot_name=? AND m.kind='ask' AND m.notice_sent=0
38
+ AND NOT EXISTS (SELECT 1 FROM mailbox_messages r WHERE r.in_reply_to=m.id AND r.kind='reply') ORDER BY m.created_at, m.rowid`).all(botName);
39
+ },
40
+ // Replies whose delivery failed, was interrupted or became uncertain and
41
+ // that have no notice of their own yet, whether or not the ask already
42
+ // had a notice: a late reply can fail after a "no reply" notice.
43
+ undeliveredReplies() {
44
+ return db.prepare(`SELECT r.* FROM mailbox_messages r
45
+ JOIN external_jobs j ON j.bot_name=r.bot_name AND j.route_id=r.route_id AND j.request_id='mailbox:' || r.id
46
+ WHERE r.bot_name=? AND r.kind='reply' AND j.state IN ('failed','interrupted','unknown')
47
+ AND NOT EXISTS (SELECT 1 FROM external_jobs n WHERE n.bot_name=r.bot_name AND n.request_id='mailbox-notice:' || r.id)
48
+ ORDER BY r.created_at, r.rowid`).all(botName);
49
+ },
50
+ markNoticeSent(id) { db.prepare('UPDATE mailbox_messages SET notice_sent=1 WHERE id=? AND bot_name=?').run(id, botName); },
51
+ // Mailbox-owned external jobs whose outcome is unknown and whose session
52
+ // is not yet proven idle, so its queue stays blocked.
53
+ unrecoveredJobs() {
54
+ return db.prepare(`SELECT route_id, request_id FROM external_jobs WHERE bot_name=? AND state='unknown' AND inactive=0
55
+ AND (request_id GLOB 'mailbox:*' OR request_id GLOB 'mailbox-notice:*') ORDER BY id`).all(botName);
56
+ },
57
+ };
58
+ }
59
+
60
+ module.exports = { createMailboxStore };
@@ -1,5 +1,7 @@
1
1
  'use strict';
2
2
 
3
+ const { classify } = require('../error/classify');
4
+
3
5
  const CLAUDE_NAMESPACE = 'claude:channels';
4
6
  const CODEX_NAMESPACE = 'codex:app-server';
5
7
  const CLEAN_RESUME_POLICY_VERSION = 2;
@@ -162,9 +164,9 @@ async function executeCleanResumeClaim(claim, {
162
164
  ? loadSource(claim.source_message_id)
163
165
  : null;
164
166
 
165
- async function fallback(reason, { ambiguous = false } = {}) {
167
+ async function fallback(reason, { ambiguous = false, text: noticeText = null } = {}) {
166
168
  markReady();
167
- const text = recoveryNoticeText({ ambiguous });
169
+ const text = noticeText || recoveryNoticeText({ ambiguous });
168
170
  await sendNotice({
169
171
  claim,
170
172
  source,
@@ -192,13 +194,14 @@ async function executeCleanResumeClaim(claim, {
192
194
  return fallback(reason);
193
195
  }
194
196
 
195
- function failed(reason, { ambiguous = false } = {}) {
197
+ function failed(reason, { ambiguous = false, text = null, apiErrorCode = undefined } = {}) {
196
198
  logEvent('clean-resume-failed', {
197
199
  ...eventDetail,
198
200
  reason,
199
201
  ambiguous: ambiguous || undefined,
202
+ api_error_code: apiErrorCode,
200
203
  });
201
- return fallback(reason, { ambiguous });
204
+ return fallback(reason, { ambiguous, text });
202
205
  }
203
206
 
204
207
  if (!enabled) return fallback('rollout-disabled');
@@ -312,6 +315,15 @@ async function executeCleanResumeClaim(claim, {
312
315
  } catch (error) {
313
316
  markReady();
314
317
  const ambiguous = error?.deliveryAmbiguous === true;
318
+ // The resume worked and the continuation reached claude, which then gave
319
+ // up on a failing API: say that (the same copy a live turn gets), not
320
+ // that resuming was unsafe.
321
+ if (!ambiguous && error?.code === 'CLAUDE_API_ERROR') {
322
+ return failed('continuation-api-error', {
323
+ text: classify(error).userMessage,
324
+ apiErrorCode: error.apiError,
325
+ });
326
+ }
315
327
  return failed(
316
328
  ambiguous ? 'continuation-delivery-ambiguous' : 'continuation-failed',
317
329
  { ambiguous },
@@ -149,6 +149,10 @@ function createBuildSdkOptions({
149
149
  permissionMode: useCanUseTool ? 'default' : 'bypassPermissions',
150
150
  allowDangerouslySkipPermissions: !useCanUseTool,
151
151
  ...(useCanUseTool && { canUseTool: makeCanUseTool(sessionKey) }),
152
+ // Claude Code delivers SendMessage traffic from other same-user
153
+ // sessions unless told otherwise; a bot session takes input only
154
+ // from polygram. Same flag-settings tier as the CLI's --settings.
155
+ settings: { crossSessionInbound: 'refuse' },
152
156
  hooks: {},
153
157
  executable: 'node',
154
158
  ...(existingSessionId && { resume: existingSessionId }),
@@ -21,6 +21,7 @@
21
21
  'use strict';
22
22
 
23
23
  const { getTopicConfig } = require('../session-key');
24
+ const { classify: classifyError } = require('../error/classify');
24
25
  const { pickBackend } = require('@shumkov/orchestra');
25
26
  const {
26
27
  isCodexProcess,
@@ -66,6 +67,10 @@ function createSdkCallbacks({
66
67
  // self-checks, injected messages picked up as their own cycle). Optional.
67
68
  sessionFeedback = null,
68
69
  deliveryBarrier = null,
70
+ // Gates for the API-error notice of a cycle with no pending turn: never
71
+ // speak while the daemon shuts down or right after the user's /stop.
72
+ getIsShuttingDown = () => false,
73
+ isSessionRecentlyAborted = () => false,
69
74
  logger = console,
70
75
  } = {}) {
71
76
  // 0.13 P4: the rc.9 extraTurnTracker (tmux NEW-TURN typing/✍ bridge) was
@@ -407,6 +412,71 @@ function createSdkCallbacks({
407
412
  catch (err) { logger.error?.(`[${botName}] onIdle failed: ${err.message}`); }
408
413
  },
409
414
 
415
+ // A failed claude query ran cycles that no pending turn runs in — most
416
+ // often follow-ups that were autosteered into a turn that then failed,
417
+ // running afterwards as their own cycle (claude runs several queued ones
418
+ // as one query). Nobody else will answer those messages, so reply to each
419
+ // with the same copy a failed turn gets. A cycle that picked up no user
420
+ // message (a wakeup) only ends its visuals.
421
+ // (Failed pending turns reject instead and go through the dispatcher.)
422
+ onApiError: (sessionKey, payload /* , entry */) => {
423
+ // Visuals first and on their own: a failure here must not cost the user
424
+ // the notice, and a skipped notice must still stop typing.
425
+ try { sessionFeedback?.endCycle(sessionKey); }
426
+ catch (err) { logger.error?.(`[${botName}] onApiError endCycle failed: ${err.message}`); }
427
+ try {
428
+ const chatId = getChatIdFromKey(sessionKey);
429
+ const threadIdRaw = getThreadIdFromKey(sessionKey);
430
+ const threadId = threadIdRaw ? parseInt(threadIdRaw, 10) : null;
431
+ const anchors = Array.isArray(payload?.anchorMsgIds) ? payload.anchorMsgIds : [];
432
+ const { userMessage } = classifyError({ code: 'CLAUDE_API_ERROR', apiError: payload?.apiError });
433
+ // Why nothing may be sent, whichever message it would answer.
434
+ let gate = null;
435
+ if (!userMessage) {
436
+ // AUTH_DISABLED keeps the chat silent; the operator is notified when a
437
+ // pending turn fails with that code (dispatcher), not from here.
438
+ gate = payload?.apiError === 'oauth_org_not_allowed' ? 'auth-disabled' : 'suppressed';
439
+ }
440
+ else if (!bot) gate = 'no-bot';
441
+ else if (getIsShuttingDown()) gate = 'shutting-down';
442
+ else if (isSessionRecentlyAborted(sessionKey)) gate = 'aborted';
443
+ const logOutcome = (outcome, anchor) => logEvent('cli-cycle-api-error', {
444
+ chat_id: chatId,
445
+ session_key: sessionKey,
446
+ thread_id: threadIdRaw,
447
+ api_error_code: payload?.apiError,
448
+ anchor_msg_id: Number.isSafeInteger(anchor) ? anchor : undefined,
449
+ outcome,
450
+ });
451
+ if (anchors.length === 0) {
452
+ logOutcome('no-anchor');
453
+ return;
454
+ }
455
+ for (const raw of anchors) {
456
+ const anchor = raw == null || raw === '' ? NaN : Number(raw);
457
+ const outcome = !(Number.isSafeInteger(anchor) && anchor > 0) ? 'bad-anchor' : (gate || 'replied');
458
+ logOutcome(outcome, anchor);
459
+ if (outcome !== 'replied') continue;
460
+ tg(bot, 'sendMessage', {
461
+ chat_id: chatId,
462
+ text: userMessage,
463
+ ...(Number.isInteger(threadId) && { message_thread_id: threadId }),
464
+ // The follow-up may be minutes old (or deleted) by now.
465
+ reply_parameters: { message_id: anchor, allow_sending_without_reply: true },
466
+ }, {
467
+ source: 'error-reply',
468
+ botName,
469
+ sessionKey,
470
+ sourceMsgId: anchor,
471
+ }).catch((err) => {
472
+ logger.error?.(`[${botName}] api-error notice send failed: ${err.message}`);
473
+ });
474
+ }
475
+ } catch (err) {
476
+ logger.error?.(`[${botName}] onApiError failed: ${err.message}`);
477
+ }
478
+ },
479
+
410
480
  onQuestionResumed: (sessionKey, entry) => {
411
481
  try {
412
482
  const ctx = entry?.pendingQueue?.[0]?.context;
@@ -0,0 +1,68 @@
1
+ 'use strict';
2
+
3
+ /**
4
+ * How a streamed turn's preview is settled when the turn ends in an error
5
+ * (polygram.js handleMessage's catch).
6
+ *
7
+ * A turn that already delivered replies and THEN failed must not restate
8
+ * them: finalize(null) publishes whatever the draft holds, which on a CLI turn
9
+ * is usually the answer a reply already sent. So when the turn delivered
10
+ * anything, the exit settles through the turn settler instead and, unless told
11
+ * otherwise, sends the suffix as its own short message. With nothing
12
+ * delivered, the partial bubble is finalized in place and carries the suffix.
13
+ */
14
+
15
+ const { classifyTurnEndError } = require('../error/classify');
16
+
17
+ /**
18
+ * @param {object} deps
19
+ * @param {() => boolean} deps.hasDeliveredReplies
20
+ * @param {() => Promise<unknown>} deps.finishStreamer - the turn settler
21
+ * @param {{ finalize: Function }} deps.streamer
22
+ * @param {(text: string) => Promise<unknown>} deps.sendSuffixMessage
23
+ * @param {(msgId: number, text: string) => void} deps.persistBubbleText
24
+ * @returns {(errorSuffix: string|null, opts?: { suffixMessage?: boolean }) => Promise<void>}
25
+ */
26
+ function createTurnErrorExit({
27
+ hasDeliveredReplies,
28
+ finishStreamer,
29
+ streamer,
30
+ sendSuffixMessage,
31
+ persistBubbleText,
32
+ }) {
33
+ return async (errorSuffix, { suffixMessage = true } = {}) => {
34
+ if (hasDeliveredReplies()) {
35
+ await finishStreamer().catch(() => {});
36
+ // suffixMessage:false — the error reply the dispatcher sends next is
37
+ // already this turn's one error message.
38
+ if (errorSuffix && suffixMessage) {
39
+ await sendSuffixMessage(`⚠️ ${errorSuffix}`).catch(() => {});
40
+ }
41
+ return;
42
+ }
43
+ // null, not '': finalize falls back to the drafted body. Passing ''
44
+ // REPLACED whatever had streamed with an empty bubble — the user watched
45
+ // a partial answer appear and then get wiped by the very failure that
46
+ // was supposed to leave it standing.
47
+ const fin = await streamer.finalize(null, errorSuffix ? { errorSuffix } : {})
48
+ .catch(() => null);
49
+ // The bubble now shows the drafted body; bring its transcript row along,
50
+ // or the row keeps the ~30-character stub the initial send wrote.
51
+ if (fin?.finalEditOk) persistBubbleText(fin.msgId, fin.finalText);
52
+ };
53
+ }
54
+
55
+ /**
56
+ * The non-quiet error exit: decide the suffix from the error code
57
+ * (classifyTurnEndError), settle the preview, and return the reactor state
58
+ * the caller sets.
59
+ */
60
+ async function settleTurnEndError(err, settleErrorExit) {
61
+ const { errorSuffix, reactorState, suffixMessage } = classifyTurnEndError(err);
62
+ // null keeps the drafted body so the suffix APPENDS to what the user was
63
+ // reading instead of replacing it with a bare "⚠️ …".
64
+ await settleErrorExit(errorSuffix, { suffixMessage });
65
+ return reactorState;
66
+ }
67
+
68
+ module.exports = { createTurnErrorExit, settleTurnEndError };
@@ -0,0 +1,19 @@
1
+ -- Messages between role sessions. Delivery state lives in external_jobs,
2
+ -- keyed by (route_id, 'mailbox:' || id); this table holds only what the
3
+ -- daemon decided and stamped at send time.
4
+ CREATE TABLE mailbox_messages (
5
+ id TEXT PRIMARY KEY,
6
+ bot_name TEXT NOT NULL,
7
+ kind TEXT NOT NULL CHECK (kind IN ('ask','tell','reply')),
8
+ from_addr TEXT NOT NULL,
9
+ to_addr TEXT NOT NULL,
10
+ route_id TEXT NOT NULL,
11
+ body TEXT NOT NULL,
12
+ in_reply_to TEXT REFERENCES mailbox_messages(id),
13
+ depth INTEGER NOT NULL,
14
+ body_hash TEXT NOT NULL,
15
+ notice_sent INTEGER NOT NULL DEFAULT 0,
16
+ created_at INTEGER NOT NULL
17
+ );
18
+ CREATE UNIQUE INDEX mailbox_one_reply ON mailbox_messages(in_reply_to) WHERE kind = 'reply';
19
+ CREATE INDEX mailbox_by_pair ON mailbox_messages(bot_name, from_addr, to_addr, created_at);
@@ -0,0 +1,6 @@
1
+ -- A system sender's idempotency key and its opaque reference. Messages
2
+ -- between role sessions leave both NULL. A key names one message per sender
3
+ -- within a bot, so a retried submit finds the message it already created.
4
+ ALTER TABLE mailbox_messages ADD COLUMN idem_key TEXT;
5
+ ALTER TABLE mailbox_messages ADD COLUMN ref TEXT;
6
+ CREATE UNIQUE INDEX mailbox_idem_key ON mailbox_messages(bot_name, from_addr, idem_key) WHERE idem_key IS NOT NULL;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "polygram",
3
- "version": "0.41.3",
3
+ "version": "0.42.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": {
@@ -26,6 +26,7 @@
26
26
  "ops/polygram.plist.example",
27
27
  "docs/EXTERNAL_JOBS_API.md",
28
28
  "docs/RECORDED_NOTIFICATIONS_API.md",
29
+ "docs/MAILBOX.md",
29
30
  "ops/README.md",
30
31
  "docs/2026-08-16-003-codex-protected-hook-artifact-runbook.md",
31
32
  "config.example.json"
@@ -70,7 +71,7 @@
70
71
  "dependencies": {
71
72
  "@anthropic-ai/claude-agent-sdk": "0.3.283",
72
73
  "@modelcontextprotocol/sdk": "^1.29.0",
73
- "@shumkov/orchestra": "0.11.1",
74
+ "@shumkov/orchestra": "0.11.3",
74
75
  "acorn": "8.18.0",
75
76
  "better-sqlite3": "^12.9.0",
76
77
  "grammy": "^1.42.0",