@falling-ts/dsh-force-compact 0.2.0

package/src/hooks/idle.js

@@ -0,0 +1,136 @@
+/**
+ * The turn-end forced compaction.
+ *
+ * Observes `agent/status`; when an agent transitions to `idle` (no driver
+ * remains scheduled or active — i.e. all turns done, including sub-agents) and
+ * `turnEndForceCompactionEnabled` is on, compacts the session's useful history
+ * through the compaction service's **idle manual entry** (`compactNow`). This
+ * fires at the "all done, before the next human turn" boundary the user
+ * described: the agent is not busy (all turns and sub-agent work have
+ * quiesced) and the next human message has not yet arrived.
+ *
+ * `compactNow` is the idle manual-compaction entry (owner `null`): it requires an
+ * idle agent and uses the engine's own range selection. `compactRegion` is NOT
+ * usable here — its owner is `current-turn`, which requires an open turn, so at
+ * idle it throws "no open turn". A fresh `AbortController` mints a signal per
+ * idle transition (an `agent/status` listener carries no turn signal of its
+ * own).
+ *
+ * @module @falling-ts/dsh-force-compact/turn-end
+ */
+
+import { readSettings, DEFAULTS } from '../core/settings.js'
+import { resolveCompaction } from '../engine/backend.js'
+import { publishCompressing, publishDone } from '../core/ui-signal.js'
+import { guardFn, renderCrash, captureThrowSite, appendCrashLine as appendDiag } from '../core/crashnet.js'
+
+/**
+ * Handle one `agent/status` emission: when the agent transitions to `idle` and
+ * `turnEndForceCompactionEnabled` is on, compact the session's useful history
+ * through `compactNow` (the idle manual-compaction entry). Never throws out of
+ * the listener (a failing compaction is logged and swallowed).
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @param {{agent: import('@deepseek-ai/dsh-agent').Agent, status: string}} payload
+ * @param {string|undefined} mode the `compactionMode` setting (passed by the caller); undefined re-reads live.
+ * @returns {Promise<void>}
+ */
+// SAFETY ENVELOPE: this handler fires on EVERY `agent/status` transition.
+// `compactNow` is a heavyweight LLM round-trip and the idle tick recurs ~every
+// 5s, so ANY uncaught throw here would repeat on every tick — the concrete
+// "stutters every request / stuck" symptom. The ENTIRE body is therefore
+// contained: any anomaly (malformed payload, a rejecting `readSettings`, a
+// missing `agent.session`, a failing backend call) logs and returns; it NEVER
+// throws into the `agent/status` dispatch. Additionally, a UNIVERSAL-CRASH-NET
+// diagnostic (thrownAt site, deepest plugin frame, nearest non-plugin frame,
+// full stack) is appended to the durable crash log on every degradation.
+async function __handleAgentStatusEnveloped(ctx, payload, mode) {
+  try {
+    await __handleAgentStatusBody(ctx, payload, mode)
+  } catch (error) {
+    const message = error instanceof Error ? (error.stack || error.message) : String(error)
+    ctx.logger.warn(`[force-compact] handleAgentStatus degraded (swallowed) — ${message}`)
+    try {
+      const lines = renderCrash('idle.handleAgentStatus', error, captureThrowSite())
+      for (const line of lines) appendDiag(line)
+    } catch (_netFailure) { /* swallow */ }
+  }
+}
+
+export const handleAgentStatus = guardFn('idle.handleAgentStatus', __handleAgentStatusEnveloped)
+
+/** Body of {@link handleAgentStatus}; wrapped by its safe envelope. */
+async function __handleAgentStatusBody(ctx, payload, mode) {
+  if (payload === null || typeof payload !== 'object') return
+  const agent = payload.agent
+  const status = payload.status
+  if (status !== 'idle') return
+  // A usable session is required to address the compaction; without one there is
+  // nothing to do (and no id to log) — degrade quietly rather than deref crash.
+  const session = (agent && typeof agent === 'object') ? agent.session : undefined
+  const sid = (session && typeof session.id === 'string') ? session.id : '?'
+  const settings = (await readSettings(ctx)) ?? DEFAULTS
+  if (settings.turnEndForceCompactionEnabled !== true) {
+    // Visible so a tester who flipped the setting OFF can confirm the guard is
+    // what suppressed the idle compaction (not a missing listener).
+    ctx.logger.debug(`[force-compact] ${sid}: turn-end compaction disabled by settings — idle transition ignored`)
+    return
+  }
+
+  if (session === undefined || session === null || typeof session.id !== 'string') {
+    ctx.logger.debug(`[force-compact] ${sid}: idle transition observed but agent.session is unusable — skipping turn-end compaction`)
+    return
+  }
+  // Locate a usable compaction backend: the OFFICIAL `compaction` service
+  // (preferred) OR this plugin's OWN builtin engine (fallback when the service
+  // is realm-isolated away — see `engine/backend.js`). At idle the agent is
+  // still live in the registry, so its realm-scoped context still resolves the
+  // official instance when one exists; otherwise the builtin engine takes over.
+  const backend = await resolveCompaction(ctx, agent, mode)
+  if (backend === undefined || typeof backend.compactNow !== 'function') {
+    const effMode = (mode !== undefined ? mode : settings.compactionMode)
+    ctx.logger.warn(
+      `[force-compact] ${session.id}: NO compaction backend available at idle (mode=${effMode}). ` +
+      `Either the official \`compaction\` service is realm-isolated (standard preset) AND ` +
+      `\`builtinEnabled=false\`, OR the builtin engine is missing a prerequisite ` +
+      `(needs \`agent.session\` and the \`llm\` service). Enable \`builtinEnabled=true\` in the ` +
+      `\`falling-ts-force-compact\` namespace to restore the fallback.`
+    )
+    return
+  }
+
+  // compactNow is the idle manual-compaction entry (owner null). It requires an
+  // idle agent and uses the engine's own range selection. A fresh
+  // AbortController mints a signal (a status listener carries no turn signal of
+  // its own).
+  const controller = new AbortController()
+  try {
+    // LIVE UI SIGNAL — PIN RED "compressing" BEFORE requesting the model /
+    // committing anything. Both publishers are guaranteed side-effect-free
+    // (they swallow their own failures internally), so a messenger problem
+    // can never perturb the compaction transaction itself.
+    await publishCompressing(ctx)
+    // P1 — idle is an AUTO entry: pass `opts: { retainTokens }` to preserve
+    // the legacy retain-the-latest-N-tokens selection. Without this, `compactNow`
+    // defaults `retainTokens` to 0 (manual full-head behavior) which would
+    // change idle-path semantics. The 3rd arg (sourceCommandId) stays
+    // undefined — idle has no originating command id.
+    const result = await backend.compactNow(agent, controller.signal, undefined, { retainTokens: settings.retainLatestTokens })
+    if (result === undefined || result === null) {
+      ctx.logger.debug(`[force-compact] ${session.id}: idle compaction via ${backend?.kind} committed nothing`)
+      return
+    }
+    // COMMITTED — range shadowed + summary added. Pin GREEN "done" NOW; the
+    // next model request's `llm/stream` watermark redraws a fresh random
+    // working pair within seconds (typically < 3 s — the very next step's
+    // LLM boundary), which is the natural visual rhythm: no dedicated timer
+    // needed.
+    await publishDone(ctx)
+    ctx.logger.info(
+      `[force-compact] ${session.id}: idle compaction (${backend?.kind}) shadowed ${result.shadowedSeqs?.length ?? '?'} nodes `
+      + `(~${result.shadowedTokenCount ?? '?'} tokens)`,
+    )
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    ctx.logger.warn(`[force-compact] ${session.id}: idle compaction via ${backend?.kind} FAILED — ${message}`)
+  }
+}

package/src/hooks/wire-rewrite.js

@@ -0,0 +1,151 @@
+/**
+ * dsh-force-compact's wire-layer second safety net for disabling thinking —
+ * appends the OPENAI-COMPATIBLE wire field `reasoning_effort: "none"` to
+ * EVERY outgoing LLM call whenever the `disableThinking` setting is on.
+ *
+ * The dual-layer insurance rationale
+ * ---------------------------------
+ * The `disableThinking` setting is ALSO honored upstream at the request-seam:
+ * the `agent/request` waterfall sets `LlmCallConfig.reasoningEffort = 'off'`,
+ * which the DeepSeek adapter serializes to the wire field
+ * `thinking: { type: 'disabled' }`. That is the RIGHT field for the real
+ * DeepSeek API. But when the SAME wire shape lands on a llama.cpp
+ * OpenAI-compatible endpoint (:8080, `Qwen3.8-27B-NVFP4-MTP-LOW.gguf`), the
+ * top-level `thinking` key is NOT in the llama.cpp request schema — it is
+ * forwarded opaquely into `llama_params` and IGNORED
+ * (verified against `D:\AI\llama.cpp\tools\server`: `thinking` appears
+ * nowhere in `server-schema.cpp`, and the OAI parsing path never reads a
+ * top-level `thinking` key). Net effect of the request-seam path ALONE:
+ * `disableThinking:true` SILENTLY FAILS to turn off thinking on llama.cpp —
+ * the model thinks anyway, with no error surfacing.
+ *
+ * The llama.cpp-native (and OpenAI-generic) spelling for "disable reasoning"
+ * is a TOP-LEVEL wire field `reasoning_effort: "none"`
+ * (`server-common.cpp:1295-1304`), which the OAI parser special-cases into
+ * `inputs.enable_thinking = false` UNCONDITIONALLY — independent of jinja
+ * template capability. A weaker alternative,
+ * `chat_template_kwargs: { enable_thinking: false }`
+ * (`server-common.cpp:1286-1291`), depends on the template honoring the
+ * `enable_thinking` placeholder; `reasoning_effort:"none"` is more robust.
+ *
+ * Current state: NEUTERED to a pure passthrough
+ * ---------------------------------------------
+ * The original intent was "Layer 2" — append a SECOND wire field
+ * `reasoning_effort: "none"` at the `llm/stream` seam on top of the
+ * adapter's `thinking:{type:'disabled'}` (Layer 1) so that a llama.cpp /
+ * OpenAI-compatible endpoint (which ignores the top-level `thinking` key)
+ * would ALSO receive a field it honors. Live testing PROVED that this cannot
+ * be achieved at the `llm/stream` waterfall seam without modifying vendor
+ * code, because of two hard walls discovered empirically:
+ *
+ *   1. FROZEN SEED. The waterfall passes EVERY listener the SAME deep-frozen
+ *      `GenerateOptions` seed (`payload`; `ctx.waterfall` re-invokes inner
+ *      layers with the identical args — see `vendor/cordis/src/events.ts#
+ *      waterfall`). In-place assignment `options.reasoning_effort = …` throws
+ *      `Cannot add property …, object is not extensible` at the exact moment
+ *      a real LLM call fires, which PROPAGATES OUT OF the listener and TAKES
+ *      DOWN THE ENTIRE `dsh web` PROCESS.
+ *   2. GENERATOR BINDS THE SEED. The base `adapterStream` is an AsyncGenerator
+ *      that BOUND the seed object at construction; building a fresh mutable
+ *      clone and returning it (or re-dispatching `this.stream(clone)`) never
+ *      reaches the serializer, and re-dispatch additionally fails because the
+ *      listener's `this` is not reliably the LlmRuntime here (`Cannot read
+ *      properties of undefined (reading 'stream')`).
+ *
+ * Therefore injecting a NEW top-level wire field at this seam requires either
+ * a vendor change (out of scope) or a dedicated `registerAdapter` for
+ * llama.cpp (would collide with / be shadowed by the existing DeepSeek-route
+ * adapter). Rather than ship a hook that either silently no-ops or CRASHES the
+ * host, this file is deliberately reduced to a GUARANTEED pure passthrough:
+ * it forwards `next()`'s result (the real stream) untouched and performs NO
+ * mutation — incapable of breaking any business-path model call.
+ *
+ * The AUTHORITATIVE disable-thinking mechanism remains Layer 1 (unchanged):
+ * the `agent/request` waterfall sets `reasoningEffort:'off'`, which the
+ * DeepSeek adapter serializes to the native `thinking:{type:'disabled'}` —
+ * honored by the real DeepSeek API. On a llama.cpp / OpenAI-compatible
+ * endpoint that top-level field is tolerated-but-ignored, so thinking stays
+ * on there — IDENTICAL to having no plugin at all (a documented limitation,
+ * never a crash). Restoring the wire-append requires a future dedicated
+ * llama.cpp adapter or a vendor-supported options-extension seam.
+ *
+ * @module @falling-ts/dsh-force-compact/wire-rewrite
+ */
+
+/**
+ * Register the `llm/stream` Waterfall listener. As of the neutering described
+ * in the module header, the listener is a DELIBERATE pure passthrough: it
+ * forwards `next()`'s result (the async-iterable chunk stream) untouched and
+ * performs NO mutation. See the module header for why the intended
+ * `reasoning_effort:"none"` wire-append is NOT possible at this seam without a
+ * vendor change or a dedicated llama.cpp adapter.
+ *
+ * Idempotent within one plugin lifetime (a process-local latch prevents
+ * double-registration across multiple `apply` invocations in tests or HMR).
+ *
+ * Contract guarantees:
+ * Contract guarantees:
+ *   • ALWAYS calls `next()` (skipping it would stall the waterfall chain).
+ *   • NEVER mutates the (deep-frozen) seed, so it cannot raise
+ *     `object is not extensible`.
+ *   • NEVER reshapes/spreads the (stream) return value, so it cannot break the
+ *     consumer's `for await`.
+ *   • Emits at most ONE debug line (the first-of-lifetime ui-signal marker;
+ *     silent thereafter).
+ *   • FIRES THE LIVE UI STATUS SIDE-CHANNEL (`core/ui-signal.js`) on every
+ *     invocation — the "each LLM call start = fresh random working pair"
+ *     watermark. Publication is KICKED OFF FIRE-AND-FORGET (a plain
+ *     non-awaited `publishRandomWorking(ctx)` call placed BEFORE the
+ *     synchronous `return next()`) so the listener itself STAYS SYNC and can
+ *     directly hand back the real stream; `publishRandomWorking` swallows all
+ *     of its own rejections internally, so the fire-and-forget form leaks no
+ *     unhandled rejection. It never touches `payload` (the deep-frozen seed —
+ *     untouched per the two-hard-walls note above), so it can never stall or
+ *     corrupt the stream.
+ *   • The listener is DECLARED NON-ASYNC: an `async` listener would wrap
+ *     `next()`'s stream return in a Promise, and the waterfall dispatcher's
+ *     downstream `yield* <promise>` would throw
+ *     `yield* (intermediate value)… is not async iterable` on every call.
+ *
+ * @param {import('@deepseek-ai/cordis').Context} ctx
+ * @returns {boolean} whether this call actually performed the (once-only)
+ *   registration. `false` indicates it was a no-op re-entry (already
+ *   installed) or a registration failure (not installed; a later re-entry
+ *   will retry).
+ */
+
+import { publishRandomWorking } from '../core/ui-signal.js'
+let installed = false
+export function registerLlmStreamHook(ctx) {
+  if (installed) return false
+  try {
+    // CONTRACT: this listener MUST stay SYNCHRONOUS. The `llm/stream`
+    // waterfall expects each layer's RETURN VALUE to BE the (async-iterable)
+    // chunk stream itself, so that downstream layers / the dispatcher can
+    // immediately `yield*` (or `for await`) it. Making the listener `async`
+    // wraps that return in a PROMISE, and the downstream `yield* <promise>`
+    // explodes with `yield* (intermediate value)… is not async iterable` —
+    // exactly the crash observed on every built-in compaction attempt. The
+    // side-channel publication therefore runs FIRE-AND-FORGET (never blocking
+    // the return): `publishRandomWorking` swallows ALL of its own rejections
+    // internally (guaranteed side-effect-free w.r.t. the waterfall), so
+    // kicking it off without awaiting cannot leak an unhandled rejection.
+    // `payload` is the deep-frozen GenerateOptions seed — NEVER mutated (see
+    // the two-hard-walls note in the module header); the publication touches
+    // none of that (pure settings-write on the `liveUi` field, mirrored live
+    // to the browser so it can repaint the `TurnStatus` node). `void payload`
+    // documents the deliberate non-use.
+    ctx.on('llm/stream', (payload, next) => {
+      void payload
+      publishRandomWorking(ctx)   // fire-and-forget: sync kick-off, async settle
+      return next()               // synchronous return of the REAL stream
+    })
+    installed = true
+    return true
+  } catch {
+    // Registration failure (rare: e.g. a context without a usable `on`) is
+    // fatal to NOTHING — the plugin simply never installs this hook. We DO
+    // NOT mark `installed`, so a later re-entry retries.
+    return false
+  }
+}