@soffits/dsh-fallback-models 0.2.1 → 0.3.0

package/README.md

@@ -44,8 +44,7 @@ The settings page lists models from DSH's catalog (the same set the model picker
     # codes: [...]         # optional, see below
     # refusalPatterns: [...]   # optional, see "Refused answers"
     notify:                # optional, see "Notifications"
-      via: telegramTopics
-      to: "196554"
+      via: telegramTopics  # to the conversation's own topic; add `to: "<thread id>"` for one fixed topic
 ```
 
 | Field | Default | Meaning |
@@ -56,7 +55,7 @@ The settings page lists models from DSH's catalog (the same set the model picker
 | `codes` | see below | Failure codes that cause a switch to another model. |
 | `refusalPatterns` | built-in list | Regular expressions that mark a reply as refused. An empty list turns refusal detection off. |
 | `refusalMaxLength` | `500` | Longest reply, in characters, that can count as a refusal. |
-| `notify` | none | `{ via, to }`: a DSH service with a `send({ to, text, files, from })` method, and the address to pass it. |
+| `notify` | none | `{ via, to }`: a DSH service with a `send({ to, chat, text, files, from })` method. Without `to`, each message goes to the conversation the switch happened in; with `to`, always to that address. See "Notifications". |
 
 All fields apply at the next failure; DSH does not need a restart.
 
@@ -113,7 +112,12 @@ The new turn sees the whole conversation (your latest message, any tool results,
 The plugin depends on no other plugin. Each switch is also:
 
 - emitted as the Host event `fallback-models/switch`, with `{ agent, sessionId, turn, from, to, failure, refusal }`, for any plugin that wants to listen;
-- sent through `notify`, when set: the plugin looks up the service named by `via` at the time of the switch and calls its `send({ to, text, files: [], from: { label: 'dsh-fallback-models', sessionId } })` with one short message (worded apart for a refusal). Any plugin that provides such a service can receive these messages, for example a Telegram plugin's topic service with a topic's thread id as `to`. A missing service or a failed send is logged and changes nothing else.
+- sent through `notify`, when `via` names a service: the plugin looks the service up at the time of the switch and calls its `send({ to, chat, text, files: [], from: { label: 'dsh-fallback-models', sessionId } })` with one short message (worded apart for a refusal). A missing service or a failed send is logged and changes nothing else.
+
+Where the message goes depends on `to`:
+
+- Empty (the default): to the conversation the switch happened in. The service has to say where conversations live through a `topics()` method that returns `[{ sessionId, threadId, chatId }]`, as the topic service of [dsh-telegram-bot](https://github.com/soffits/dsh-telegram-bot) (`telegramTopics`) does; the message goes to the entry bound to the session, with `to` set to its `threadId` and `chat` to its `chatId`. When a subagent's model is switched, the plugin follows the subagent's parents up to the nearest conversation that has an entry and sends there, saying it happened in a subagent. A conversation with no entry anywhere up its chain, such as one opened only in the Web UI, gets no message. Ordinary forks count as conversations of their own.
+- Set: every message goes to that one address, such as a topic's thread id, whatever conversation it came from.
 
 ### What reaches the model
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soffits/dsh-fallback-models",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "Fallback model chain for DeepSeek Harness: when a model request keeps failing after DSH's own retries, the work continues on the next model in a configured list.",
   "type": "module",
   "main": "./index.js",

package/src/config.js

@@ -26,8 +26,8 @@ export const Config = z.object({
   refusalMaxLength: z.natural().default(DEFAULT_REFUSAL_MAX_LENGTH).volatile()
     .description('Longest reply, in characters, that can count as a refusal.'),
   notify: z.object({
-    via: z.string().description('Name of a running DSH service with a send({ to, text, files, from }) method, such as a Telegram plugin\'s topic service. Empty: no message.'),
-    to: z.string().description('Address that service understands, such as a topic\'s thread id.'),
+    via: z.string().description('Name of a running DSH service with a send({ to, chat, text, files, from }) method, such as a Telegram plugin\'s topic service. Empty: no message.'),
+    to: z.string().description('Empty (the default): send to the conversation the switch happened in, as the service\'s topics() list places it; a subagent\'s switch goes to its nearest parent conversation that has a place, and nothing is sent when none has. Set: send every message to this one address, such as a topic\'s thread id.'),
   }).default({}).volatile()
     .description('Optional: also send one short message per switch through another plugin\'s service. Nothing is required; the switch is always shown in the conversation and emitted as the fallback-models/switch event.'),
 })

package/src/fallback.js

@@ -19,13 +19,14 @@
 // Each switch is announced three ways, none of which needs another plugin:
 // a banner in the Web UI conversation (client.js renders the interrupted
 // turn's end), a `fallback-models/switch` event other plugins may listen to,
-// and, when `notify` names a service, one `send({ to, text, from })` call to
-// it (for example a Telegram plugin's topic service).
+// and, when `notify` names a service, one message through it, to a fixed
+// address or to the conversation's own place (src/notify.js).
 import { randomUUID } from 'node:crypto'
 import {
   REFUSAL_CODE, boundSummary, candidates, chainFor, failureText, isRefusal, read,
   routeKey, routeLabel, sameRoute, switches, toSelection,
 } from './policy.js'
+import { sendNotice } from './notify.js'
 import {
   DEFAULT_REFUSAL_MAX_LENGTH, DEFAULT_REFUSAL_PATTERNS, compilePatterns,
   toolSucceededThisTurn, watchRefusal,
@@ -49,21 +50,6 @@ export function switchReason(from, to, failure) {
   return `${REASON_PREFIX}: ${routeLabel(from)} ${what} (${failure.code}); continuing on ${routeLabel(to)}`
 }
 
-/**
- * The message sent through `notify` for one switch. A refusal is worded
- * apart: the reply was hidden, not lost to an error.
- */
-export function switchText(info) {
-  const from = routeLabel(info.from)
-  const to = routeLabel(info.to)
-  if (info.refusal) {
-    return `Model fallback: ${from} refused to answer or its filter blocked the reply, in session ${info.sessionId}. `
-      + `The refused reply was hidden, and ${to} is answering instead.`
-  }
-  return `Model fallback: ${from} failed (${failureText(info.failure)}) in session ${info.sessionId}. `
-    + `The work continues on ${to}.`
-}
-
 function freeze(value) {
   if (value && typeof value === 'object') {
     for (const key of Object.keys(value)) freeze(value[key])
@@ -250,27 +236,7 @@ export function installFallback(ctx, config) {
     } catch (error) {
       logger.warn('a %s listener failed: %s', SWITCH_EVENT, error instanceof Error ? error.message : String(error))
     }
-    const via = typeof notify?.via === 'string' ? notify.via.trim() : ''
-    if (via === '') return
-    let service
-    try {
-      service = ctx.get(via)
-    } catch {
-      service = undefined
-    }
-    if (typeof service?.send !== 'function') {
-      logger.warn('notify: no running service %s with a send method', via)
-      return
-    }
-    const request = {
-      to: typeof notify.to === 'string' ? notify.to.trim() : notify.to,
-      text: switchText(info),
-      files: [],
-      from: { label: 'dsh-fallback-models', sessionId: info.sessionId },
-    }
-    Promise.resolve()
-      .then(() => service.send(request))
-      .catch(error => logger.warn('notify through %s failed: %s', via, error instanceof Error ? error.message : String(error)))
+    void sendNotice(ctx, logger, info, notify)
   }
 
   /**

package/src/notify.js

@@ -0,0 +1,139 @@
+// The optional message sent through another plugin's service for each switch.
+//
+// `notify.via` names a running DSH service with `send({ to, chat, text, files,
+// from })`. With `notify.to` set, every message goes to that one address. With
+// `notify.to` empty, the message goes to the place of the conversation the
+// switch happened in: the service's `topics()` lists the places it knows, each
+// bound to a session, and a subagent's switch goes to the nearest ancestor
+// session that has one. No place in the chain means no message.
+import { failureText, routeLabel } from './policy.js'
+
+/** Stop walking up a parent chain after this many links. */
+export const MAX_PARENT_HOPS = 32
+
+/**
+ * Where the message is going, relative to the switching session.
+ * - `address`: a fixed `notify.to`, maybe unrelated to the session.
+ * - `own`: the place bound to the switching session itself.
+ * - `parent`: the place of an ancestor; the switch happened in a subagent.
+ */
+function whereText(info, relation) {
+  if (relation === 'own') return 'in this conversation'
+  if (relation === 'parent') return `in a subagent of this conversation (session ${info.sessionId})`
+  return `in session ${info.sessionId}`
+}
+
+/**
+ * The message for one switch. A refusal is worded apart: the reply was
+ * hidden, not lost to an error.
+ * @param info - the switch, as emitted on `fallback-models/switch`.
+ * @param relation - `address` (default), `own` or `parent`; see whereText.
+ */
+export function switchText(info, relation = 'address') {
+  const from = routeLabel(info.from)
+  const to = routeLabel(info.to)
+  const where = whereText(info, relation)
+  if (info.refusal) {
+    return `Model fallback: ${from} refused to answer or its filter blocked the reply, ${where}. `
+      + `The refused reply was hidden, and ${to} is answering instead.`
+  }
+  return `Model fallback: ${from} failed (${failureText(info.failure)}) ${where}. `
+    + `The work continues on ${to}.`
+}
+
+/** Header of a session by id: a live agent's first, else the stored one. */
+async function headerOf(ctx, id) {
+  try {
+    const live = ctx.get('agents')?.get(id)?.session?.header
+    if (live) return live
+  } catch {
+    // no agent registry: fall through to storage
+  }
+  try {
+    return (await ctx.get('sessionPersistence')?.stat(id))?.header
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * The place of a session or of its nearest subagent ancestor.
+ * Only `origin: 'subagent'` links are followed: an ordinary fork is a
+ * conversation of its own, even when its header names a source session.
+ * @param ctx - plugin context, for reading parent headers.
+ * @param topics - the service's places: `[{ sessionId, threadId, chatId? }]`.
+ * @param header - the switching session's header.
+ * @returns `{ topic, relation }`, or undefined when no session in the chain has a place.
+ */
+export async function conversationPlace(ctx, topics, header) {
+  const places = new Map()
+  for (const topic of Array.isArray(topics) ? topics : []) {
+    if (topic?.sessionId == null || topic.threadId == null) continue
+    const key = String(topic.sessionId)
+    if (!places.has(key)) places.set(key, topic)
+  }
+  const seen = new Set()
+  let current = header
+  for (let hops = 0; current && hops <= MAX_PARENT_HOPS; hops++) {
+    const id = String(current.id)
+    if (seen.has(id)) return undefined
+    seen.add(id)
+    const topic = places.get(id)
+    if (topic) return { topic, relation: hops === 0 ? 'own' : 'parent' }
+    if (current.origin !== 'subagent' || current.parentSession === undefined) return undefined
+    current = await headerOf(ctx, current.parentSession)
+  }
+  return undefined
+}
+
+/**
+ * Send one switch message through `notify`, when it names a service.
+ * Never throws: a missing service, an unknown place or a failed send is
+ * logged and changes nothing else.
+ * @param ctx - plugin context.
+ * @param logger - the plugin's logger.
+ * @param info - the switch; `info.agent.session.header` locates the conversation.
+ * @param notify - the `notify` setting: `{ via, to }`.
+ */
+export async function sendNotice(ctx, logger, info, notify) {
+  const via = typeof notify?.via === 'string' ? notify.via.trim() : ''
+  if (via === '') return
+  let service
+  try {
+    service = ctx.get(via)
+  } catch {
+    service = undefined
+  }
+  if (typeof service?.send !== 'function') {
+    logger.warn('notify: no running service %s with a send method', via)
+    return
+  }
+  const to = typeof notify.to === 'string' ? notify.to.trim() : notify.to == null ? '' : String(notify.to)
+  const from = { label: 'dsh-fallback-models', sessionId: info.sessionId }
+  try {
+    let request
+    if (to !== '') {
+      request = { to, text: switchText(info, 'address'), files: [], from }
+    } else {
+      if (typeof service.topics !== 'function') {
+        logger.warn('notify: service %s cannot say where a conversation lives (no topics method); set notify.to', via)
+        return
+      }
+      const place = await conversationPlace(ctx, await service.topics(), info.agent?.session?.header)
+      if (place === undefined) {
+        logger.info('notify: session %s has no place in %s; no message sent', info.sessionId, via)
+        return
+      }
+      request = {
+        to: String(place.topic.threadId),
+        ...place.topic.chatId == null ? {} : { chat: place.topic.chatId },
+        text: switchText(info, place.relation),
+        files: [],
+        from,
+      }
+    }
+    await service.send(request)
+  } catch (error) {
+    logger.warn('notify through %s failed: %s', via, error instanceof Error ? error.message : String(error))
+  }
+}