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.
- package/.claude-plugin/plugin.json +1 -1
- package/config.example.json +22 -1
- package/docs/EXTERNAL_JOBS_API.md +10 -2
- package/docs/MAILBOX.md +207 -0
- package/lib/db/event-detail-schema.js +11 -0
- package/lib/db.js +1 -1
- package/lib/error/classify.js +67 -2
- package/lib/external-jobs/dispatch.js +27 -0
- package/lib/external-jobs/runtime.js +9 -2
- package/lib/external-jobs/service.js +81 -30
- package/lib/external-jobs/store.js +14 -7
- package/lib/handlers/dispatcher.js +26 -13
- package/lib/ipc/handlers.js +10 -0
- package/lib/ipc/server.js +3 -1
- package/lib/mailbox/envelope.js +80 -0
- package/lib/mailbox/rules.js +172 -0
- package/lib/mailbox/service.js +288 -0
- package/lib/mailbox/store.js +60 -0
- package/lib/ops/clean-resume.js +16 -4
- package/lib/sdk/build-options.js +4 -0
- package/lib/sdk/callbacks.js +70 -0
- package/lib/telegram/turn-error-exit.js +68 -0
- package/migrations/024-mailbox.sql +19 -0
- package/migrations/025-mailbox-system-senders.sql +6 -0
- package/package.json +3 -2
- package/polygram.js +41 -40
- package/skills/mailbox/SKILL.md +30 -0
- package/skills/mailbox/scripts/msg.js +19 -0
|
@@ -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 };
|
package/lib/ops/clean-resume.js
CHANGED
|
@@ -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 },
|
package/lib/sdk/build-options.js
CHANGED
|
@@ -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 }),
|
package/lib/sdk/callbacks.js
CHANGED
|
@@ -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.
|
|
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.
|
|
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",
|