@falling-ts/dsh-force-compact 0.2.0

package/src/core/ui-signal.js

@@ -0,0 +1,271 @@
+/**
+ * Live UI status messenger — the plugin-private bridge between the HOST half
+ * ("which phase am I in right now?") and the CLIENT half ("paint THAT pair on
+ * the `TurnStatus` DOM node").
+ *
+ * Why settings at all
+ * ------------------
+ * The client half (`web/client.js`) already mirrors the `falling-ts-force-compact`
+ * namespace through `settingsScope.bind` → `createSnapshotStore`, so ANY field
+ * written by the host here is reflected in the browser live (the `SettingsScope`
+ * revision-fencing contract). That is the ONLY sanctioned host→browser live-data
+ * channel this independent plugin bundle can use — there is no reverse RPC seam
+ * for a client-loaded plugin to expose arbitrary callable methods (the unary
+ * route map is closed and host-defined). The `liveUi` field documented below is
+ * therefore a PLUGIN-PRIVATE transient messenger: the host is its only writer;
+ * the client never writes it; it deliberately persists to `settings.yaml` like
+ * every other field of the namespace (harmless cosmetic residue — the worst
+ * outcome after a restart is the badge briefly showing a stale phase before the
+ * next LLM call overwrites it).
+ *
+ * Phases
+ * ------
+ * Every model request begins with a WORKING phase (a random text+color pair
+ * drawn from the 20×20 tables below — the "工作中的状态" set). Around a
+ * force-compaction the display is OVERRIDDEN deterministically, not randomly:
+ *
+ *   • COMPRESSING — pinned red `[强制压缩中>>>]`, fired BEFORE the `compactNow` /
+ *     `compactRegion` call;
+ *   • DONE        — pinned green `[压缩完成!]`, fired right AFTER the call
+ *     commits; then after `DONE_FALLBACK_MS` (3 s) a forced
+ *     `isImportant=true` push redraws a fresh random Deep working pair
+ *     (single-purpose timer — the only one in this module).
+ *
+ * All writers are GUARANTEED never to throw (they wrap the settings-service
+ * write in try/catch): a messenger failure must NEVER disrupt the model
+ * request or the compaction transaction itself.
+ *
+ * @module @falling-ts/dsh-force-compact/ui-signal
+ */
+
+/** The settings field name carrying the live UI status (host-written, client-read). */
+export const LIVE_UI_FIELD = 'liveUi'
+
+/** Phase discriminants. Closed union — consumers switch on exactly these. */
+export const PHASE_WORKING = 'working'
+export const PHASE_COMPRESSING = 'compressing'
+export const PHASE_DONE = 'done'
+
+/** Pinned (never randomized) payloads for the deterministic phases. */
+export const PINNED_TEXTS = Object.freeze({
+  [PHASE_COMPRESSING]: '[强制压缩中>>>]',
+  [PHASE_DONE]: '[压缩完成!]',
+})
+
+/** Pinned colors matching {@link PINNED_TEXTS} — red while compacting, green on completion. */
+export const PINNED_COLORS = Object.freeze({
+  [PHASE_COMPRESSING]: '#ff4d4f',
+  [PHASE_DONE]: '#52c41a',
+})
+
+/**
+ * The 20 WORKING-phase texts. Deliberately irreverent, meme-flavored one-liners
+ * aimed at the agent ITSELF ("我正在憋大招..." / "我在偷渡..." / ...) — the
+ * badge talks about what the agent is supposedly up to in a playful voice
+ * instead of dry status verbs. Lengths intentionally exceed the old four-char
+ * constraint; the client paints the raw string with no width assumption.
+ * Colors are unchanged and remain randomly paired with these labels.
+ * @readonly
+ */
+export const WORKING_TEXTS = Object.freeze([
+  '正在酝酿骚操作...',
+  '正在憋大招...',
+  '灵感正在路上...',
+  '脑细胞开会中...',
+  '灵魂拷问进行中...',
+  '偷偷翻你底牌...',
+  '量子纠缠计算中...',
+  '假装很忙...',
+  '摸鱼式工作中...',
+  '疯狂敲键盘(精神上)...',
+  '正在缝合上下文...',
+  '正在驯服混沌...',
+  '正在召唤赛博大脑...',
+  '正在翻阅《天机》...',
+  'CPU 正在冒烟...',
+  '正在跟熵值搏斗...',
+  '正在画饼给你吃...',
+  '正在偷渡灵感...',
+  '正在暗中观察...',
+  '马上就好(大概)...',
+])
+
+/**
+ * The 20 WORKING-phase colors — a fixed palette covering the hue wheel (soft
+ * blues/greens for calm phases, warm amber/violet toward the end); each pairs
+ * with any text independently (random pairing, not a locked text-color index,
+ * so repeated draws visibly vary BOTH dimensions).
+ * @readonly
+ */
+export const WORKING_COLORS = Object.freeze([
+  '#4f9cf9',
+  '#5b8def',
+  '#6a5bff',
+  '#8b5cf6',
+  '#a855f7',
+  '#c45bf9',
+  '#db6bd4',
+  '#e86bb0',
+  '#f06b8b',
+  '#f76b5b',
+  '#fb8c5b',
+  '#fca95b',
+  '#fdc35b',
+  '#d8e05b',
+  '#aede5b',
+  '#7ee083',
+  '#5be0a0',
+  '#5becd8',
+  '#5bcdf9',
+  '#7ba8f9',
+])
+
+/**
+ * Draw a random working-phase status: a random text paired with a random
+ * color (independently chosen, so the pair space is 20×20 = 400 distinct
+ * combinations). Pure — no I/O, trivially testable.
+ * @returns {{phase: string, text: string, color: string}}
+ */
+export function randomWorkingPair() {
+  return {
+    phase: PHASE_WORKING,
+    text: WORKING_TEXTS[Math.floor(Math.random() * WORKING_TEXTS.length)],
+    color: WORKING_COLORS[Math.floor(Math.random() * WORKING_COLORS.length)],
+  }
+}
+
+/**
+ * Build the pinned payload for a deterministic phase.
+ * @param {'compressing'|'done'} phase
+ * @returns {{phase: string, text: string, color: string}}
+ */
+export function pinnedPayload(phase) {
+  return { phase, text: PINNED_TEXTS[phase], color: PINNED_COLORS[phase] }
+}
+
+/**
+ * Publish one UI status onto the `liveUi` field of the `falling-ts-force-compact`
+ * namespace. This is THE host→browser delivery point: the client half's
+ * `settingsScope.bind` mirror flips its snapshot on the next accepted
+ * revision, and the browser component repaints the `TurnStatus` DOM node.
+ *
+ * Guarantees:
+ *   • NEVER throws — a settings-service absence or a rejected write is caught
+ *     and logged at most once per lifetime (observability only; the model
+ *     request and any surrounding compaction transaction proceed untouched).
+ *   • Fire-and-forget from the caller's perspective: the returned promise
+ *     always settles (resolve on success, resolve-with-warning on failure).
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{phase: string, text: string, color: string}} status
+ * @param {boolean} [isImportant=false] — `true` bypasses the guard entirely
+ *   and writes unconditionally. `false` (the default) refuses to overwrite a
+ *   currently displayed text that starts with `[` (i.e. a pinned bracket-form
+ *   message such as `[强制压缩中>>>]`), returning early without touching
+ *   settings.
+ * @returns {Promise<void>}
+ */
+let warnedOnce = false
+export async function publishUiStatus(ctx, status, isImportant = false) {
+  try {
+    const settings = ctx.get('settings')
+    if (settings === undefined || typeof settings.update !== 'function') return
+    const NS = 'falling-ts-force-compact'
+    // Non-important pushes refuse to overwrite a pinned bracket-form text.
+    if (!isImportant) {
+      let currentText
+      try {
+        // SYNC read — the settings service's `get` returns the cached value
+        // immediately (same call style as settings.js:226); the gate is purely
+        // advisory (worst case: the write proceeds, nothing breaks), so there
+        // is no reason to await an async variant even if one ever appeared.
+        const nsValue = (typeof settings.get === 'function') ? settings.get(NS) : undefined
+        currentText = (nsValue != null && typeof nsValue === 'object')
+          ? nsValue[LIVE_UI_FIELD]?.text
+          : (typeof nsValue === 'string' ? nsValue : undefined)
+      } catch { /* read failure must not block the important path — fall through */ }
+      if (typeof currentText === 'string' && currentText.startsWith('[')) return
+    }
+    await settings.update(NS, { [LIVE_UI_FIELD]: status })
+    if (!warnedOnce) {
+      warnedOnce = true
+      try {
+        ctx.logger.debug(`[force-compact] ui-signal: publishing ${status?.phase} "${status?.text}" (${status?.color}) via ${NS}.${LIVE_UI_FIELD}`)
+      } catch { /* logging must never propagate */ }
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    try {
+      ctx.logger.warn(`[force-compact] ui-signal publish failed (ignored, cosmetic only) — ${message}`)
+    } catch { /* never */ }
+  }
+}
+
+/**
+ * The host-side driver for one MODEL REQUEST's start moment. Call from the
+ * `llm/stream` waterfall (once per outgoing call): draw a fresh random working
+ * pair and publish it NON-importantly (so a pinned bracket-form text such as
+ * `[压缩完成!]` survives the push until its own fallback timer clears it — see
+ * {@link publishDone}). A fresh pair is also emitted on the 3-second fallback
+ * after DONE ({@link DONE_FALLBACK_MS}), firing with `isImportant=true` so it
+ * overwrites the DONE banner even though a `[`-prefixed text is on screen.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {Promise<void>}
+ */
+export async function publishRandomWorking(ctx) {
+  await publishUiStatus(ctx, randomWorkingPair())
+}
+
+/**
+ * Publish the pinned RED "[强制压缩中>>>]" status. Call BEFORE a `compactNow` /
+ * `compactRegion` invocation. Passes `isImportant=true` so the pinned
+ * bracket-form message can overwrite whatever is currently displayed (including
+ * another pinned text).
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {Promise<void>}
+ */
+export async function publishCompressing(ctx) {
+  await publishUiStatus(ctx, pinnedPayload(PHASE_COMPRESSING), true)
+}
+
+/**
+ * How long after the pinned "[压缩完成!]" DONE banner is published before the
+ * forced fallback kicks in and paints a fresh random Deep working pair back on
+ * the badge (with `isImportant=true`). 3000 ms.
+ *
+ * Note: this is the plugin's SINGLE-USE TIMER — a deliberate, documented
+ * exception to the collection rule "plugins are pure host listeners that do
+ * not introduce timers". See the `dsh-force-compact` AGENTS.md deviation note.
+ */
+const DONE_FALLBACK_MS = 3000
+
+/**
+ * Publish the pinned GREEN "[压缩完成!]" status. Call AFTER a `compactNow` /
+ * `compactRegion` invocation commits. After {@link DONE_FALLBACK_MS} (3 s) a
+ * forced fallback (`isImportant=true`) overwrites the DONE banner with a fresh
+ * random Deep working pair, restoring the usual working appearance regardless
+ * of whether a subsequent `llm/stream` fires in the interim. We paint a
+ * FRESH random working pair (not the literal pre-compression text, which is no
+ * longer recoverable from the settings store — it was already overwritten by
+ * the COMPRESSING/DONE banners): the intent is "back to a normal working
+ * look", which a freshly-drawn working pair satisfies.
+ *
+ * Passes `isImportant=true` for the initial DONE push: reaching `publishDone`
+ * PRECEDED BY `publishCompressing`, which has already written the pinned red
+ * `[强制压缩中>>>]` bracket-form text. Without `isImportant=true` the gate inside
+ * {@link publishUiStatus} (which refuses non-important pushes over a currently
+ * displayed `[`-bracket text) would see our OWN still-displayed `compressing`
+ * banner and bail out, so the green `[压缩完成!]` would silently never be written
+ * and the 3 s fallback would jump straight from COMPRESSING to a fresh working
+ * pair — the DONE banner never appearing at all. Since a DONE push can only
+ * follow a `compressing` push from THIS plugin, there is no manually-set custom
+ * banner to protect, and overriding our own prior banner is exactly intended.
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {Promise<void>}
+ */
+export async function publishDone(ctx) {
+  await publishUiStatus(ctx, pinnedPayload(PHASE_DONE), true)
+  setTimeout(() => {
+    void publishUiStatus(ctx, randomWorkingPair(), true)
+  }, DONE_FALLBACK_MS)
+}

package/src/engine/backend.js

@@ -0,0 +1,143 @@
+/**
+ * Locate the `compaction` service for a given agent.
+ *
+ * In modern harness compositions the compaction BACKEND (`compaction-basic`)
+ * is mounted per **agent preset realm** (the `standard` preset isolates the
+ * `compaction` service into each session's realm), so the HOST-GLOBAL
+ * `ctx.get('compaction')` observes `undefined` while each live agent's own
+ * context (`agent.ctx`) resolves the instance. A host-level function plugin
+ * (this one) holds a global context, so reading `ctx.get('compaction')` alone
+ * finds nothing — but it DOES have the live agent handle on every event
+ * payload, and `agent.ctx` is the canonical way to reach that agent's
+ * realm-scoped world.
+ *
+ * The location MODE comes from the `compactionMode` setting (`'realm'`
+ * default, `'global'` opt-out), read directly from the raw settings namespace
+ * so the hot model-request path never pays a full-settings-parse cost.
+ *
+ * Resolution tries, in priority order:
+ *   1. `agent.ctx` (the agent's realm-scoped context, guaranteed by the
+ *      `Agent` type definition) — the modern preset-plane location;
+ *   2. the host-global `ctx.get('compaction')` — the base-bundle location
+ *      plus a safety net when the agent context did not hold the service;
+ *   3. `ctx.compaction` (injected-property convention, topology-sensitive).
+ *
+ * `'realm'` (default) tries all three so every layout works; `'global'`
+ * restricts to steps 2–3 (a deployment known to mount the backend globally).
+ *
+ * @module @falling-ts/dsh-force-compact/service-resolver
+ */
+
+import { readRawSetting, COMPACT_MODE_GLOBAL } from '../core/settings.js'
+
+import { compactNowBuiltin, compactRegionBuiltin } from './builtin.js'
+import { guardFn } from '../core/crashnet.js'
+
+/**
+ * Find a usable compaction backend for one agent.
+ *
+ * Resolution order (priority 1 first):
+ *   1. the OFFICIAL `compaction` service (`compactNow`/`compactRegion`) — the
+ *      authoritative summarizer; preferred whenever it is reachable from this
+ *      agent's context (see the historical note above about realm placement);
+ *   2. this plugin's BUILTIN engine (its own transaction, event names, and
+ *      summarizer) — the fallback used whenever the official service is
+ *      unreachable from this context (the common `standard` preset layout) and
+ *      the `builtinEnabled` setting allows it (default `true`).
+ *
+ * Both backends expose the SAME shape — `compactNow` and `compactRegion` — so
+ * callers are agnostic to which produced the result.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx a context to fall back to (the plugin-global context) when the agent-side candidates do not resolve.
+ * @param {import('@deepseek-ai/dsh-agent').Agent|undefined} agent the agent owning the target session.
+ * @param {string|undefined} mode the `compactionMode` setting value (`'realm'`|`'global'`).
+ * @returns {Promise<{ compactNow: Function, compactRegion: Function, kind: 'official'|'builtin' }|undefined>} a normalized backend, or `undefined` when neither the official service nor the builtin engine is usable.
+ */
+// Internal body of `resolveCompaction` — routed through the crash-net wrapper
+// so an unusual throw (a throwing `ctx.get` proxy, a rejecting `readRawSetting`)
+// becomes a visible diagnostic rather than a silent propagation.
+async function __resolveCompactionBody(ctx, agent, mode) {
+  const official = await findOfficialService(ctx, agent, mode)
+  if (official !== undefined) {
+    return { compactNow: official.compactNow, compactRegion: official.compactRegion, kind: 'official' }
+  }
+  return await builtinBackend(ctx, agent)
+}
+
+/** Public entry — wrapped by the universal crash net. */
+export const resolveCompaction = guardFn('backend.resolveCompaction', __resolveCompactionBody)
+
+/**
+ * Locate the OFFICIAL `compaction` service for this agent via the historical
+ * two-tier resolver. Reads the `compactionMode` setting (`'realm'` default,
+ * `'global'` opt-out) to choose candidates:
+ *   - `'realm'` (default): the agent's OWN realm-scoped context (`agent.ctx`,
+ *     the canonical modern location), then the host-global `ctx.get('compaction')`;
+ *   - `'global'`: only the host-global `ctx.get('compaction')`.
+ *
+ * NEVER declares `inject:['compaction']` and NEVER reads `ctx.compaction` as a
+ * property (that would trip the strict-injection fatal). Only `ctx.get` /
+ * `agent.ctx.get` — both safe and tolerant.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {import('@deepseek-ai/dsh-agent').Agent|undefined} agent
+ * @param {string|undefined} mode
+ * @returns {Promise<object|undefined>} the official compaction service, or `undefined`.
+ */
+async function findOfficialService(ctx, agent, mode) {
+  const effectiveMode = (typeof mode === 'string' && mode === COMPACT_MODE_GLOBAL)
+    ? COMPACT_MODE_GLOBAL
+    : ((mode === undefined) ? (await readRawSetting(ctx, 'compactionMode')) : 'realm')
+
+  if (effectiveMode !== COMPACT_MODE_GLOBAL
+      && agent && agent.ctx !== undefined && agent.ctx !== null) {
+    const byRealm = tryGet(agent.ctx)
+    if (byRealm !== undefined) return byRealm
+  }
+  return tryGet(ctx)
+}
+
+/**
+ * Build the BUILTIN backend for this agent: the plugin's own engine, gated by
+ * the `builtinEnabled` setting (default `true`). Returns `undefined` when the
+ * engine is disabled or lacks what it needs (an `agent` handle with a session
+ * and an `llm` service for the summarizer).
+ */
+async function builtinBackend(ctx, agent) {
+  const enabled = (await readRawSetting(ctx, 'builtinEnabled')) ?? true
+  if (!enabled) return undefined
+  if (agent === undefined || agent === null || agent.session === undefined) return undefined
+  const llm = ctx.get('llm')
+  if (llm === undefined || typeof llm.stream !== 'function') return undefined
+  return {
+    kind: 'builtin',
+    // P1 — widen positionals so command-driven callers can thread
+    // `sourceCommandId` (3rd arg) and auto/idle callers can supply
+    // `opts` (4th arg) to the builtin engine. The official passthrough
+    // (priority-1 path) ignores extra positionals harmlessly.
+    compactNow: (...args) => compactNowBuiltin(ctx, ...args),
+    compactRegion: (...args) => compactRegionBuiltin(ctx, ...args),
+  }
+}
+
+/**
+ * Safely attempt `receiver.get('compaction')`, returning the service ONLY when
+ * it exposes the methods this plugin calls (`compactNow` / `compactRegion`).
+ * Never throws — an unusable receiver or a missing service yields `undefined`.
+ *
+ * @param {any} receiver any receiver (typically a Cordis context, possibly a
+ *   Proxy; some partial receivers may lack `.get` altogether).
+ * @returns {object|undefined}
+ */
+function tryGet(receiver) {
+  if (receiver === undefined || receiver === null) return undefined
+  if (typeof receiver.get !== 'function') return undefined
+  try {
+    const svc = receiver.get('compaction')
+    if (svc === undefined || svc === null) return undefined
+    if (typeof svc.compactNow === 'function' || typeof svc.compactRegion === 'function') return svc
+  } catch {
+    // Any receiver shape (including non-proxy partials) is tolerated.
+  }
+  return undefined
+}