@kadaliao/dsh-bots 0.7.1 → 0.8.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/lib/usage.mjs CHANGED
@@ -5,11 +5,18 @@
5
5
  * request (a message from the user or a chat app, a scheduled run, a DM from
6
6
  * another bot) until it is idle again.
7
7
  *
8
+ * In 0.8 a run (the plan's "回合"; still `task` in these files) may belong to a
9
+ * ticket: work one bot handed another, done in a conversation of its own.
10
+ *
8
11
  * Files under the bots cache:
9
- * - `usage.jsonl`: `{t, b, s, k?, r, p, m, i, o, cr, cw}` — time, bot, session,
10
- * task, kind ('chat' | 'compaction' | 'memory' | 'dream'), provider, model,
11
- * uncached input, output, cache-read and cache-write tokens.
12
- * - `tasks.jsonl`: `{id, b, s, trigger, via?, from?, sched?, title, start, end, status, topic?}`.
12
+ * - `usage.jsonl`: `{t, b, s, k?, tk?, r, p, m, i, o, cr, cw}` — time, bot, session,
13
+ * task (run), ticket, kind ('chat' | 'compaction' | 'memory' | 'dream'), provider,
14
+ * model, uncached input, output, cache-read and cache-write tokens. The ticket is
15
+ * `tk`, not `t` as PLAN-0.8 §5 says: `t` has always been the time here.
16
+ * - `tasks.jsonl`: `{id, b, s, t?, trigger, via?, from?, sched?, title, start, end, status, topic?}`;
17
+ * `t` is the ticket the run belongs to.
18
+ *
19
+ * Rows written before 0.8 have neither and read as before.
13
20
  *
14
21
  * Rows older than {@link KEEP_DAYS} are dropped when the file is compacted.
15
22
  *
@@ -29,12 +36,13 @@ const COMPACT_SLACK = 5000;
29
36
  const int = (v) => (Number.isFinite(Number(v)) && Number(v) > 0 ? Math.round(Number(v)) : 0);
30
37
 
31
38
  /** A ledger row from a Harness TokenUsage. */
32
- export function usageRow({ at, botId, sessionId, taskId, kind = 'chat', provider, model, usage }) {
39
+ export function usageRow({ at, botId, sessionId, taskId, ticketId, kind = 'chat', provider, model, usage }) {
33
40
  return {
34
41
  t: Number(at) || Date.now(),
35
42
  b: botId,
36
43
  s: sessionId ?? '',
37
44
  ...(taskId ? { k: taskId } : {}),
45
+ ...(ticketId ? { tk: ticketId } : {}),
38
46
  r: kind,
39
47
  p: String(provider ?? ''),
40
48
  m: String(model ?? ''),
@@ -161,9 +169,12 @@ function add(acc, r, cost) {
161
169
  const round = (cost) => Object.fromEntries(Object.entries(cost).map(([k, v]) => [k, Number(v.toFixed(6))]));
162
170
 
163
171
  /**
164
- * A usage report for the page.
172
+ * A usage report for the page. `tickets` groups the window's calls by the
173
+ * ticket they were made for (with how many of its runs ended in the window);
174
+ * `opts.tickets` names them.
165
175
  * @param {{calls: object[], tasks: object[], running?: object[]}} data
166
- * @param {{range?: string, bot?: string, tz?: number, now?: number, price: (model: string) => object|null, schedules?: Map<string,string>}} opts
176
+ * @param {{range?: string, bot?: string, tz?: number, now?: number, price: (model: string) => object|null, schedules?: Map<string,string>,
177
+ * tickets?: Map<string, {title?: string, botId?: string}>}} opts
167
178
  */
168
179
  export function report(data, opts) {
169
180
  const now = opts.now ?? Date.now();
@@ -188,6 +199,7 @@ export function report(data, opts) {
188
199
  const byModel = new Map();
189
200
  const byKind = new Map();
190
201
  const byTask = new Map();
202
+ const byTicket = new Map();
191
203
  const series = new Map();
192
204
  for (const r of calls) {
193
205
  if (r.t >= from - span && r.t < from) add(prev, r, costOf(price(r.m), r));
@@ -199,6 +211,7 @@ export function report(data, opts) {
199
211
  add(byModel.get(mk) ?? byModel.set(mk, { ...blank(), provider: r.p, model: r.m }).get(mk), r, cost);
200
212
  add(byKind.get(r.r) ?? byKind.set(r.r, blank()).get(r.r), r, cost);
201
213
  if (r.k) add(byTask.get(r.k) ?? byTask.set(r.k, blank()).get(r.k), r, cost);
214
+ if (r.tk) add(byTicket.get(r.tk) ?? byTicket.set(r.tk, { ...blank(), bot: r.b }).get(r.tk), r, cost);
202
215
  const b = keyOf(r.t);
203
216
  const s = series.get(b) ?? series.set(b, { t: b, tokens: 0, byBot: {}, cost: {} }).get(b);
204
217
  s.tokens += rowTokens(r);
@@ -222,6 +235,7 @@ export function report(data, opts) {
222
235
  ...(t.via ? { via: t.via } : {}),
223
236
  ...(t.from ? { from: t.from } : {}),
224
237
  ...(t.sched ? { sched: t.sched } : {}),
238
+ ...(t.t ? { ticket: t.t } : {}),
225
239
  title: t.title,
226
240
  start: t.start,
227
241
  end: t.end ?? null,
@@ -242,6 +256,8 @@ export function report(data, opts) {
242
256
  s.tokens += t.tokens;
243
257
  for (const [c, v] of Object.entries(t.cost)) s.cost[c] = (s.cost[c] ?? 0) + v;
244
258
  }
259
+ const runsOf = new Map();
260
+ for (const t of [...tasks, ...running]) if (t.t) runsOf.set(t.t, (runsOf.get(t.t) ?? 0) + 1);
245
261
  const fin = (o) => ({ ...o, cost: round(o.cost) });
246
262
  const sortTokens = (a, b) => b.tokens - a.tokens;
247
263
  return {
@@ -255,9 +271,39 @@ export function report(data, opts) {
255
271
  schedules: [...sched.values()].map((s) => ({ ...s, cost: round(s.cost) })).sort(sortTokens),
256
272
  tasks: [...live, ...finished.slice().sort((a, b) => (b.end ?? b.start) - (a.end ?? a.start))].slice(0, 60),
257
273
  topTasks: finished.slice().sort(sortTokens).slice(0, 10),
274
+ tickets: [...byTicket]
275
+ .map(([id, { bot: rowBot, ...v }]) => ({ id, bot: opts.tickets?.get(id)?.botId ?? rowBot, title: opts.tickets?.get(id)?.title ?? '', runs: runsOf.get(id) ?? 0, ...fin(v) }))
276
+ .sort(sortTokens)
277
+ .slice(0, 60),
258
278
  };
259
279
  }
260
280
 
281
+ /**
282
+ * Everything one ticket cost, whenever it ran: its runs (finished and running,
283
+ * oldest first) with their tokens and cost, and the totals, which also count
284
+ * calls made for the ticket outside a run (its memory summary).
285
+ * @param {{calls: object[], tasks: object[], running?: object[]}} data
286
+ * @param {string} ticketId
287
+ * @param {(model: string) => object|null} price
288
+ */
289
+ export function ticketUsage(data, ticketId, price) {
290
+ const calls = data.calls.filter((r) => r.tk === ticketId);
291
+ const total = blank();
292
+ const byRun = new Map();
293
+ for (const r of calls) {
294
+ const cost = costOf(price(r.m), r);
295
+ add(total, r, cost);
296
+ if (r.k) add(byRun.get(r.k) ?? byRun.set(r.k, blank()).get(r.k), r, cost);
297
+ }
298
+ const runs = [...data.tasks.filter((t) => t.t === ticketId), ...(data.running ?? []).filter((t) => t.t === ticketId)]
299
+ .sort((a, b) => a.start - b.start)
300
+ .map((t) => {
301
+ const u = byRun.get(t.id) ?? blank();
302
+ return { id: t.id, trigger: t.trigger, title: t.title, start: t.start, end: t.end ?? null, status: t.status ?? (t.end ? 'done' : 'running'), tokens: u.tokens, calls: u.calls, cost: round(u.cost) };
303
+ });
304
+ return { runs, tokens: total.tokens, calls: total.calls, cost: round(total.cost), unpriced: total.unpriced };
305
+ }
306
+
261
307
  /** Today's tokens per bot, for the roster. */
262
308
  export function todayByBot(calls, tz = 0, now = Date.now()) {
263
309
  const { from, to } = rangeOf('today', tz, now);
@@ -0,0 +1,216 @@
1
+ /**
2
+ * The ticket watchdog's rules, deterministic only: which errors are worth a
3
+ * retry and when, which quiet workers get a status check or are marked
4
+ * stalled, and which requesters get one reminder. The host gathers the facts
5
+ * (stage, session status, background jobs) and carries out the actions; no
6
+ * model judges anything here.
7
+ *
8
+ * @module @kadaliao/dsh-bots/lib/watchdog
9
+ */
10
+
11
+ /** Delays before the 1st, 2nd and 3rd "continue" after a temporary error; then the ticket fails. */
12
+ export const RETRY_DELAYS_MS = Object.freeze([15_000, 30_000, 60_000]);
13
+
14
+ /** Default minutes without events (or without a report after a status check) before the watchdog acts. */
15
+ export const STALL_MINUTES = 20;
16
+
17
+ /** Stages in which a requester has nothing left to wait for. */
18
+ export const SETTLED_STAGES = Object.freeze(['done', 'failed', 'stopped', 'stalled']);
19
+
20
+ /**
21
+ * The delay before the next retry, given how many were already made;
22
+ * undefined once they are used up (the ticket then fails).
23
+ * @param {number} retries
24
+ * @returns {number|undefined}
25
+ */
26
+ export function retryDelay(retries) {
27
+ const n = Math.max(0, Math.floor(Number(retries) || 0));
28
+ return RETRY_DELAYS_MS[n];
29
+ }
30
+
31
+ const TRANSIENT_CODES = new Set([
32
+ 'ECONNREFUSED',
33
+ 'ECONNRESET',
34
+ 'ECONNABORTED',
35
+ 'ETIMEDOUT',
36
+ 'ESOCKETTIMEDOUT',
37
+ 'EPIPE',
38
+ 'EAI_AGAIN',
39
+ 'ENETDOWN',
40
+ 'ENETUNREACH',
41
+ 'EHOSTDOWN',
42
+ 'EHOSTUNREACH',
43
+ 'ERR_STREAM_PREMATURE_CLOSE',
44
+ 'UND_ERR_CONNECT_TIMEOUT',
45
+ 'UND_ERR_HEADERS_TIMEOUT',
46
+ 'UND_ERR_BODY_TIMEOUT',
47
+ 'UND_ERR_SOCKET',
48
+ ]);
49
+
50
+ const transientStatus = (s) => s === 408 || s === 429 || (s >= 500 && s <= 599);
51
+
52
+ /** "status code 503", "HTTP 429", "Error: 502", or a message that starts with the status ("529 Overloaded", "APIError: 500 …"). */
53
+ const STATUS_IN_TEXT = [/\b(?:status(?:\s+code)?|http(?:\/\d(?:\.\d)?)?|error|code)\s*[:=]?\s*(\d{3})\b/i, /^\s*(?:[A-Za-z]*Error:\s*)?(\d{3})\b/];
54
+ const TRANSIENT_TEXT =
55
+ /\b(?:ECONNREFUSED|ECONNRESET|ECONNABORTED|ETIMEDOUT|ESOCKETTIMEDOUT|EPIPE|EAI_AGAIN|ENETDOWN|ENETUNREACH|EHOSTUNREACH|UND_ERR_[A-Z_]+)\b|connection (?:was )?(?:refused|reset|closed|aborted|timed out)|socket hang up|\btimed out\b|\btimeout\b|rate.?limit|too many requests|overloaded|service unavailable|bad gateway|gateway time-?out|internal server error|temporarily unavailable|fetch failed|network error|premature close/i;
56
+
57
+ /** Out of money or quota: some providers send these as 429, but waiting does not help. */
58
+ const NOT_TRANSIENT_TEXT = /insufficient[_ ](?:quota|balance|funds)|billing/i;
59
+
60
+ /** true / false when the text says, undefined when it does not. */
61
+ function textVerdict(text) {
62
+ if (NOT_TRANSIENT_TEXT.test(text)) return false;
63
+ for (const re of STATUS_IN_TEXT) {
64
+ const m = re.exec(text);
65
+ if (m) {
66
+ const n = Number(m[1]);
67
+ if (n >= 100 && n <= 599) return transientStatus(n);
68
+ }
69
+ }
70
+ return TRANSIENT_TEXT.test(text) ? true : undefined;
71
+ }
72
+
73
+ /**
74
+ * Is an error worth retrying: HTTP 408, 429 or 5xx, or a refused, reset or
75
+ * timed-out connection? Accepts Error objects (their `cause` too), `{status}`
76
+ * / `{statusCode}` / `{response: {status}}`, `{code}`, `{error: …}` wrappers,
77
+ * a bare status number, and message strings. A known status decides on its
78
+ * own, except that running out of quota or balance is never transient (some
79
+ * providers send it as 429), nor is an AbortError (someone stopped the run).
80
+ * @param {unknown} error
81
+ * @returns {boolean}
82
+ */
83
+ export function isTransient(error) {
84
+ return verdict(error, 0) === true;
85
+ }
86
+
87
+ function verdict(error, depth) {
88
+ if (error === null || error === undefined || depth > 4) return undefined;
89
+ if (typeof error === 'string') return textVerdict(error);
90
+ if (typeof error === 'number') return transientStatus(error);
91
+ if (typeof error !== 'object') return undefined;
92
+ if (error.name === 'AbortError') return false;
93
+ if ([error.code, error.type, error.message].some((s) => typeof s === 'string' && NOT_TRANSIENT_TEXT.test(s))) return false;
94
+ const status = Number(error.status ?? error.statusCode ?? error.response?.status);
95
+ if (Number.isInteger(status) && status >= 100 && status <= 599) return transientStatus(status);
96
+ if (typeof error.code === 'number' && error.code >= 100 && error.code <= 599) return transientStatus(error.code);
97
+ if (typeof error.code === 'string' && TRANSIENT_CODES.has(error.code.toUpperCase())) return true;
98
+ if (error.name === 'TimeoutError') return true;
99
+ const said = typeof error.message === 'string' ? textVerdict(error.message) : undefined;
100
+ if (said === false) return false;
101
+ for (const inner of [error.cause, error.error]) {
102
+ const v = verdict(inner, depth + 1);
103
+ if (v !== undefined) return v;
104
+ }
105
+ if (said !== undefined) return said;
106
+ if (typeof error.code === 'string') return textVerdict(error.code);
107
+ return undefined;
108
+ }
109
+
110
+ const toMs = (v) => (typeof v === 'number' ? v : v ? Date.parse(v) : NaN);
111
+ /** The latest of some timestamps (numbers or ISO strings), NaN when none is set. */
112
+ function latest(...values) {
113
+ const ms = values.map(toMs).filter(Number.isFinite);
114
+ return ms.length ? Math.max(...ms) : NaN;
115
+ }
116
+ const lastReportAt = (t) => latest(...(Array.isArray(t.reports) ? t.reports.map((r) => r?.at) : []));
117
+
118
+ /**
119
+ * The watchdog pass over working tickets (PLAN-0.8 §4.5). Only a ticket in
120
+ * stage `working` whose session is idle with no background jobs is looked
121
+ * at; queued, question and ended tickets are never touched.
122
+ *
123
+ * - Quiet for `stallMinutes` (no session event, report, or message from a
124
+ * person or the requester; counted from the start when there was none) and
125
+ * not yet checked → one `nudge` (the host sends the status check and sets
126
+ * `nudgedAt`).
127
+ * - Checked, and `stallMinutes` since the check went by without a report or
128
+ * such a message → `stall` (the host sets `stalledAt` and tells the
129
+ * requester). A report or a message (`lastHumanAt`, `lastRequesterAt`)
130
+ * after the check answers it; the next quiet spell may get its own check.
131
+ *
132
+ * @param {Array<{ticket: object, stage: string, agentStatus: 'running'|'idle'|'offline', backgroundJobs?: number}>} items
133
+ * @param {{stallMinutes?: number}} [rules]
134
+ * @param {number} [now]
135
+ * @returns {Array<{kind: 'nudge'|'stall', ticketId: string, quietMinutes: number}>}
136
+ */
137
+ export function checkTickets(items, rules = {}, now = Date.now()) {
138
+ const stallMs = Math.max(1, Number(rules.stallMinutes) || STALL_MINUTES) * 60_000;
139
+ const actions = [];
140
+ for (const item of items ?? []) {
141
+ const t = item?.ticket;
142
+ if (!t?.id || item.stage !== 'working' || t.ended || t.archivedAt) continue;
143
+ if (item.agentStatus !== 'idle' || Number(item.backgroundJobs ?? 0) > 0) continue;
144
+ const reportAt = lastReportAt(t);
145
+ const humanAt = latest(t.lastHumanAt, t.lastRequesterAt);
146
+ const nudgedAt = toMs(t.nudgedAt);
147
+ const answered = Number.isFinite(nudgedAt) && (reportAt > nudgedAt || humanAt > nudgedAt);
148
+ if (Number.isFinite(nudgedAt) && !answered) {
149
+ if (now - nudgedAt >= stallMs) actions.push({ kind: 'stall', ticketId: t.id, quietMinutes: Math.floor((now - nudgedAt) / 60_000) });
150
+ continue;
151
+ }
152
+ const last = latest(t.lastEventAt, reportAt, humanAt, t.startedAt, t.createdAt);
153
+ if (Number.isFinite(last) && now - last >= stallMs) actions.push({ kind: 'nudge', ticketId: t.id, quietMinutes: Math.floor((now - last) / 60_000) });
154
+ }
155
+ return actions;
156
+ }
157
+
158
+ /** When a settled ticket settled: its end, the stall, or its last report. */
159
+ function settledAt(t) {
160
+ const at = latest(t.ended?.at, t.stalledAt, lastReportAt(t));
161
+ return Number.isFinite(at) ? at : latest(t.updatedAt, t.createdAt);
162
+ }
163
+
164
+ /**
165
+ * Requesters to remind once: every unarchived ticket a requester session
166
+ * asked for is settled (done, failed, stopped, stalled), the session is idle,
167
+ * and it has said nothing (no report to its own asker, no reply to the
168
+ * person) since the last of them settled. `ticketIds` lists the tickets that
169
+ * settled after its last word or reminder. The host records `remindedAt`
170
+ * after reminding, which keeps it to once per batch.
171
+ *
172
+ * Tickets requested by the user (requester.kind 'user') have no session to
173
+ * remind and are skipped, and so is a requester that is itself a ticket that
174
+ * has ended (`ended` in its facts, or its ticket among `items` is ended): its
175
+ * work is over and nobody reads what it would say. A grace period (default 1
176
+ * minute) leaves time for the relay of the last report to wake the requester
177
+ * first.
178
+ *
179
+ * @param {Array<{ticket: object, stage: string}>} items - tickets with their stages; archived ones are ignored.
180
+ * @param {Map<string, object>|Record<string, object>|((sessionId: string) => object|undefined)} requesters -
181
+ * per requester session: `{status: 'running'|'idle'|'offline', reportedAt?, remindedAt?, ended?}`.
182
+ * @param {number} [now]
183
+ * @param {{graceMs?: number}} [rules]
184
+ * @returns {Array<{sessionId: string, botId?: string, ticketIds: string[]}>}
185
+ */
186
+ export function requesterReminders(items, requesters, now = Date.now(), rules = {}) {
187
+ const graceMs = Math.max(0, Number(rules.graceMs ?? 60_000));
188
+ const factsOf = (id) =>
189
+ typeof requesters === 'function' ? requesters(id) : requesters instanceof Map ? requesters.get(id) : requesters?.[id];
190
+ const groups = new Map();
191
+ const byId = new Map();
192
+ for (const item of items ?? []) {
193
+ const t = item?.ticket;
194
+ if (t?.id) byId.set(t.id, t);
195
+ const r = t?.requester;
196
+ if (!t?.id || t.archivedAt || r?.kind !== 'session' || !r.sessionId) continue;
197
+ if (!groups.has(r.sessionId)) groups.set(r.sessionId, []);
198
+ groups.get(r.sessionId).push(item);
199
+ }
200
+ const out = [];
201
+ for (const [sessionId, list] of groups) {
202
+ if (!list.every((it) => SETTLED_STAGES.includes(it.stage))) continue;
203
+ const facts = factsOf(sessionId);
204
+ if (facts?.status !== 'idle' || facts.ended) continue;
205
+ const parentId = list[0].ticket.requester.ticketId;
206
+ if (parentId && byId.get(parentId)?.ended) continue;
207
+ const told = latest(facts.reportedAt, facts.remindedAt);
208
+ const fresh = list.filter((it) => !(settledAt(it.ticket) <= told));
209
+ if (fresh.length === 0) continue;
210
+ const last = latest(...fresh.map((it) => settledAt(it.ticket)));
211
+ if (Number.isFinite(last) && now - last < graceMs) continue;
212
+ const botId = list[0].ticket.requester.botId;
213
+ out.push({ sessionId, ...(botId ? { botId } : {}), ticketIds: fresh.map((it) => it.ticket.id) });
214
+ }
215
+ return out;
216
+ }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@kadaliao/dsh-bots",
3
- "version": "0.7.1",
3
+ "version": "0.8.0",
4
4
  "type": "module",
5
5
  "description": "Grok-style bots for DeepSeek Harness: create bots with their own avatar, persona, model, skills, apps, scheduled tasks and memory; they message each other, a dispatcher bot hands out the work, and a usage view counts tokens by bot, task and day.",
6
6
  "exports": {