opencode-matrixx-v2 1.3.0 → 1.3.1

package/dist/cli.js

@@ -6310,6 +6310,12 @@ var DcpManualModeSchema = object({
   enabled: boolean2().optional(),
   automaticStrategies: boolean2().optional()
 });
+var DcpWatchdogSchema = object({
+  enabled: boolean2().default(true),
+  abovePercent: number2().min(1).max(95).default(25),
+  targetPercent: number2().min(1).max(94).default(10),
+  cooldownTurns: number2().int().min(1).default(2)
+});
 var DcpProfileDefinitionSchema = object({
   pruneNotification: _enum(["off", "minimal", "detailed"]).optional(),
   pruneNotificationType: _enum(["chat", "toast"]).optional(),
@@ -6338,6 +6344,12 @@ var DcpConfigSchema = object({
     maxMessages: 6,
     keepFirst: 2,
     keepLast: 3
+  }),
+  watchdog: DcpWatchdogSchema.default({
+    enabled: true,
+    abovePercent: 25,
+    targetPercent: 10,
+    cooldownTurns: 2
   })
 });
 
@@ -6494,6 +6506,7 @@ var HookNameEnum = _enum([
   "knowledge-hub-injector",
   "knowledge-hub-search-nudge",
   "dcp-nudge-sanitizer",
+  "compress-watchdog",
   "nudge-loop-breaker",
   "task-notepad-writer",
   "session-memory",

package/dist/config/schema/dcp.d.ts

@@ -57,6 +57,13 @@ export declare const DcpManualModeSchema: z.ZodObject<{
     automaticStrategies: z.ZodOptional<z.ZodBoolean>;
 }, z.core.$strip>;
 export type DcpManualMode = z.infer<typeof DcpManualModeSchema>;
+export declare const DcpWatchdogSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    abovePercent: z.ZodDefault<z.ZodNumber>;
+    targetPercent: z.ZodDefault<z.ZodNumber>;
+    cooldownTurns: z.ZodDefault<z.ZodNumber>;
+}, z.core.$strip>;
+export type DcpWatchdog = z.infer<typeof DcpWatchdogSchema>;
 export declare const DcpProfileDefinitionSchema: z.ZodObject<{
     pruneNotification: z.ZodOptional<z.ZodEnum<{
         off: "off";
@@ -363,5 +370,11 @@ export declare const DcpConfigSchema: z.ZodObject<{
         keepFirst: z.ZodDefault<z.ZodNumber>;
         keepLast: z.ZodDefault<z.ZodNumber>;
     }, z.core.$strip>>;
+    watchdog: z.ZodDefault<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        abovePercent: z.ZodDefault<z.ZodNumber>;
+        targetPercent: z.ZodDefault<z.ZodNumber>;
+        cooldownTurns: z.ZodDefault<z.ZodNumber>;
+    }, z.core.$strip>>;
 }, z.core.$strip>;
 export type DcpConfig = z.infer<typeof DcpConfigSchema>;

package/dist/config/schema/hooks.d.ts

@@ -61,6 +61,7 @@ export declare const HookNameSchema: z.ZodUnion<readonly [z.ZodEnum<{
     "knowledge-hub-injector": "knowledge-hub-injector";
     "knowledge-hub-search-nudge": "knowledge-hub-search-nudge";
     "dcp-nudge-sanitizer": "dcp-nudge-sanitizer";
+    "compress-watchdog": "compress-watchdog";
     "nudge-loop-breaker": "nudge-loop-breaker";
     "task-notepad-writer": "task-notepad-writer";
     "session-memory": "session-memory";

package/dist/config/schema/matrixx-config.d.ts

@@ -166,6 +166,7 @@ export declare const MatrixxConfigSchema: z.ZodObject<{
         "knowledge-hub-injector": "knowledge-hub-injector";
         "knowledge-hub-search-nudge": "knowledge-hub-search-nudge";
         "dcp-nudge-sanitizer": "dcp-nudge-sanitizer";
+        "compress-watchdog": "compress-watchdog";
         "nudge-loop-breaker": "nudge-loop-breaker";
         "task-notepad-writer": "task-notepad-writer";
         "session-memory": "session-memory";
@@ -927,6 +928,12 @@ export declare const MatrixxConfigSchema: z.ZodObject<{
             keepFirst: z.ZodDefault<z.ZodNumber>;
             keepLast: z.ZodDefault<z.ZodNumber>;
         }, z.core.$strip>>;
+        watchdog: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            abovePercent: z.ZodDefault<z.ZodNumber>;
+            targetPercent: z.ZodDefault<z.ZodNumber>;
+            cooldownTurns: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     auto_update: z.ZodOptional<z.ZodBoolean>;
     skills: z.ZodOptional<z.ZodUnion<readonly [z.ZodArray<z.ZodString>, z.ZodObject<{

package/dist/index.js

@@ -25573,6 +25573,12 @@ var DcpManualModeSchema = object({
   enabled: boolean2().optional(),
   automaticStrategies: boolean2().optional()
 });
+var DcpWatchdogSchema = object({
+  enabled: boolean2().default(true),
+  abovePercent: number2().min(1).max(95).default(25),
+  targetPercent: number2().min(1).max(94).default(10),
+  cooldownTurns: number2().int().min(1).default(2)
+});
 var DcpProfileDefinitionSchema = object({
   pruneNotification: _enum(["off", "minimal", "detailed"]).optional(),
   pruneNotificationType: _enum(["chat", "toast"]).optional(),
@@ -25692,6 +25698,12 @@ var DcpConfigSchema = object({
     maxMessages: 6,
     keepFirst: 2,
     keepLast: 3
+  }),
+  watchdog: DcpWatchdogSchema.default({
+    enabled: true,
+    abovePercent: 25,
+    targetPercent: 10,
+    cooldownTurns: 2
   })
 });
 // src/config/schema/evolution.ts
@@ -25844,6 +25856,7 @@ var HookNameEnum = _enum([
   "knowledge-hub-injector",
   "knowledge-hub-search-nudge",
   "dcp-nudge-sanitizer",
+  "compress-watchdog",
   "nudge-loop-breaker",
   "task-notepad-writer",
   "session-memory",
@@ -91160,6 +91173,268 @@ function createNativePluginContext(ctx) {
   };
 }
 
+// src/shared/policy/compress-watchdog.ts
+var COMPRESS_WATCHDOG_MARKER = "<matrixx-compress-watchdog>";
+var DEFAULT_COMPRESS_WATCHDOG_CONFIG = {
+  enabled: true,
+  abovePercent: 25,
+  targetPercent: 10,
+  cooldownTurns: 2
+};
+function asRecord8(value) {
+  return typeof value === "object" && value !== null ? value : undefined;
+}
+function finiteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function nonEmptyString(value) {
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function clampPercent(value) {
+  return Math.min(95, Math.max(1, Math.round(value)));
+}
+function resolveCompressWatchdogConfig(input) {
+  const abovePercent = clampPercent(finiteNumber(input?.abovePercent) ?? DEFAULT_COMPRESS_WATCHDOG_CONFIG.abovePercent);
+  const requestedTarget = clampPercent(finiteNumber(input?.targetPercent) ?? DEFAULT_COMPRESS_WATCHDOG_CONFIG.targetPercent);
+  const targetPercent = requestedTarget < abovePercent ? requestedTarget : Math.max(1, abovePercent - 1);
+  const cooldownTurns = Math.max(1, Math.floor(finiteNumber(input?.cooldownTurns) ?? DEFAULT_COMPRESS_WATCHDOG_CONFIG.cooldownTurns));
+  return {
+    enabled: input?.enabled ?? DEFAULT_COMPRESS_WATCHDOG_CONFIG.enabled,
+    abovePercent,
+    targetPercent,
+    cooldownTurns
+  };
+}
+function extractContextUsage(messages) {
+  for (let index = messages.length - 1;index >= 0; index--) {
+    const message = asRecord8(messages[index]);
+    if (!message)
+      continue;
+    const info = asRecord8(message.info);
+    const role = message.type ?? message.role ?? info?.role;
+    if (role !== "assistant")
+      continue;
+    const owner = info ?? message;
+    const tokens = asRecord8(owner.tokens) ?? asRecord8(message.tokens);
+    if (!tokens)
+      continue;
+    const output = finiteNumber(tokens.output) ?? 0;
+    if (output <= 0)
+      continue;
+    const cache = asRecord8(tokens.cache);
+    const total = (finiteNumber(tokens.input) ?? 0) + output + (finiteNumber(tokens.reasoning) ?? 0) + (finiteNumber(cache?.read) ?? 0) + (finiteNumber(cache?.write) ?? 0);
+    if (total <= 0)
+      continue;
+    const model = asRecord8(owner.model) ?? asRecord8(message.model);
+    const providerID = nonEmptyString(owner.providerID) ?? nonEmptyString(model?.providerID);
+    const modelID = nonEmptyString(owner.modelID) ?? nonEmptyString(model?.modelID) ?? nonEmptyString(model?.id);
+    return {
+      tokens: total,
+      ...providerID !== undefined ? { providerID } : {},
+      ...modelID !== undefined ? { modelID } : {}
+    };
+  }
+  return null;
+}
+function modelListItems(raw) {
+  if (Array.isArray(raw))
+    return raw;
+  const record = asRecord8(raw);
+  if (!record)
+    return [];
+  const models = record.models;
+  if (Array.isArray(models))
+    return models;
+  const data = record.data;
+  if (Array.isArray(data))
+    return data;
+  return [];
+}
+function resolveContextLimit(models, providerID, modelID) {
+  if (providerID === undefined || modelID === undefined)
+    return null;
+  for (const item of modelListItems(models)) {
+    const record = asRecord8(item);
+    if (!record)
+      continue;
+    const itemProvider = nonEmptyString(record.providerID);
+    const itemModel = nonEmptyString(record.id) ?? nonEmptyString(record.modelID);
+    if (itemProvider !== providerID || itemModel !== modelID)
+      continue;
+    const limit = finiteNumber(asRecord8(record.limit)?.context);
+    if (limit !== undefined && limit > 0)
+      return limit;
+  }
+  return null;
+}
+function usagePercent(tokens, limit) {
+  if (!Number.isFinite(tokens) || !Number.isFinite(limit) || limit <= 0)
+    return 0;
+  return tokens / limit * 100;
+}
+function shouldInjectCompressDirective(args) {
+  const { config, currentPercent, turnsSinceLastInjection, lastUserText } = args;
+  if (!config.enabled)
+    return false;
+  if (currentPercent < config.abovePercent)
+    return false;
+  if (turnsSinceLastInjection < config.cooldownTurns)
+    return false;
+  if (lastUserText?.includes(COMPRESS_WATCHDOG_MARKER))
+    return false;
+  return true;
+}
+function buildCompressDirective(args) {
+  const { currentPercent, tokens, limit, config } = args;
+  const used = currentPercent.toFixed(1);
+  const tokenLabel = Math.round(tokens).toLocaleString("en-US");
+  const limitLabel = Math.round(limit).toLocaleString("en-US");
+  return [
+    COMPRESS_WATCHDOG_MARKER,
+    `CONTEXT WATCHDOG: this session is at ${used}% of a ${limitLabel}-token window (${tokenLabel} tokens). The configured ceiling is ${config.abovePercent}%.`,
+    `Before continuing the task, call the \`compress\` tool on the LARGEST contiguous span of CLOSED messages (never the current turn): copy the span's start and end boundary IDs exactly as injected \u2014 do not invent or omit them \u2014 and replace the span with a technical summary that preserves decisions, file paths, open tasks, and error signatures.`,
+    `Repeat until usage is at or below ${config.targetPercent}%. Do not ask the user for confirmation; compress and continue.`,
+    COMPRESS_WATCHDOG_MARKER
+  ].join(`
+`);
+}
+
+// src/plugin/message-hooks/compress-watchdog.ts
+var MODEL_LIST_TTL_MS = 60000;
+var MAX_TRACKED_SESSIONS = 500;
+function findLastUserMessage2(messages) {
+  for (let index = messages.length - 1;index >= 0; index--) {
+    const message = messages[index];
+    if (!message || roleOf(message) !== "user")
+      continue;
+    if (typeof message.text !== "string" || message.text.length === 0)
+      return null;
+    return { index, text: message.text };
+  }
+  return null;
+}
+function turnsSinceLastInjection(state) {
+  if (state.lastInjectedTurn === null)
+    return Number.POSITIVE_INFINITY;
+  return state.turns - state.lastInjectedTurn;
+}
+function isSubagentSession(sessionID) {
+  return subagentSessions.has(sessionID) || getParentSessionID(sessionID) !== undefined;
+}
+function hasCompressTool(event) {
+  const tools = event.tools;
+  return typeof tools === "object" && tools !== null && "compress" in tools;
+}
+async function readSessionUsage(ctx, event, messages) {
+  const fromEvent = extractContextUsage(messages);
+  if (fromEvent)
+    return fromEvent;
+  try {
+    const raw = await ctx.session.context({ sessionID: event.sessionID });
+    if (Array.isArray(raw))
+      return extractContextUsage(raw);
+    const nested = raw?.messages;
+    return Array.isArray(nested) ? extractContextUsage(nested) : null;
+  } catch (error) {
+    log("[compress-watchdog] session context read failed", {
+      sessionID: event.sessionID,
+      error: error instanceof Error ? error.message : String(error)
+    });
+    return null;
+  }
+}
+async function registerCompressWatchdog(ctx, options = {}) {
+  const config = resolveCompressWatchdogConfig(options.config);
+  if (!config.enabled || options.hookEnabled === false)
+    return [];
+  const now = options.now ?? (() => Date.now());
+  const sessions = new Map;
+  let limitsCache = null;
+  async function loadModelList(force) {
+    const fetchedAt = now();
+    if (!force && limitsCache && fetchedAt - limitsCache.fetchedAt < MODEL_LIST_TTL_MS) {
+      return limitsCache.raw;
+    }
+    try {
+      const raw = await ctx.model.list();
+      limitsCache = { fetchedAt, raw };
+      return raw;
+    } catch (error) {
+      log("[compress-watchdog] model list read failed", {
+        error: error instanceof Error ? error.message : String(error)
+      });
+      return limitsCache?.raw ?? null;
+    }
+  }
+  const registration = await ctx.session.hook("context", async (event) => {
+    try {
+      if (!config.enabled)
+        return;
+      if (isSubagentSession(event.sessionID))
+        return;
+      if (!hasCompressTool(event))
+        return;
+      const state = sessions.get(event.sessionID) ?? { turns: 0, lastInjectedTurn: null };
+      state.turns += 1;
+      sessions.set(event.sessionID, state);
+      if (sessions.size > MAX_TRACKED_SESSIONS) {
+        const oldest = sessions.keys().next().value;
+        if (oldest !== undefined)
+          sessions.delete(oldest);
+      }
+      const rawMessages = Array.isArray(event.messages) ? event.messages : [];
+      const usage = await readSessionUsage(ctx, event, rawMessages);
+      if (!usage)
+        return;
+      let limit = resolveContextLimit(await loadModelList(false), usage.providerID, usage.modelID);
+      if (limit === null) {
+        limit = resolveContextLimit(await loadModelList(true), usage.providerID, usage.modelID);
+      }
+      if (limit === null)
+        return;
+      const currentPercent = usagePercent(usage.tokens, limit);
+      const lastUser = findLastUserMessage2(rawMessages);
+      const shouldInject = shouldInjectCompressDirective({
+        config,
+        currentPercent,
+        turnsSinceLastInjection: turnsSinceLastInjection(state),
+        lastUserText: lastUser?.text
+      });
+      if (!shouldInject || !lastUser)
+        return;
+      const target = rawMessages[lastUser.index];
+      if (typeof target.text !== "string")
+        return;
+      const directive = buildCompressDirective({
+        currentPercent,
+        tokens: usage.tokens,
+        limit,
+        config
+      });
+      target.text = `${directive}
+
+---
+
+${target.text}`;
+      state.lastInjectedTurn = state.turns;
+      log("[compress-watchdog] directive injected", {
+        sessionID: event.sessionID,
+        currentPercent: Number(currentPercent.toFixed(1)),
+        abovePercent: config.abovePercent,
+        targetPercent: config.targetPercent,
+        tokens: usage.tokens,
+        limit
+      });
+    } catch (error) {
+      log("[compress-watchdog] hook failed", {
+        sessionID: event.sessionID,
+        error: error instanceof Error ? error.message : String(error)
+      });
+    }
+  });
+  return [registration];
+}
+
 // src/plugin/message-hooks/context-injector.ts
 async function applyContextInjectorMessagesTransform(event, deps = {}) {
   const messages = event?.messages;
@@ -91917,6 +92192,9 @@ async function registerMessageHooks(ctx, deps = {}) {
   registrations.push(...await registerThinkingBlockValidator(ctx));
   registrations.push(...await registerEvolutionHitl(ctx, deps.evolutionHitl));
   registrations.push(...await registerDcpNudgeSanitizer(ctx));
+  if (deps.compressWatchdog) {
+    registrations.push(...await registerCompressWatchdog(ctx, deps.compressWatchdog));
+  }
   registrations.push(...await registerToolPairValidator(ctx));
   return registrations;
 }
@@ -91950,7 +92228,7 @@ async function guard(label, fn) {
     return;
   }
 }
-function asRecord8(value) {
+function asRecord9(value) {
   return value !== null && typeof value === "object" ? value : {};
 }
 function hideNativeSubagentTool(editor) {
@@ -92070,7 +92348,12 @@ async function registerDomainSessionHooks(input) {
     if (registration)
       registrations.push(registration);
   }
-  const messageHookRegistrations = await guard("registerMessageHooks", () => registerMessageHooks(ctx));
+  const messageHookRegistrations = await guard("registerMessageHooks", () => registerMessageHooks(ctx, {
+    compressWatchdog: {
+      config: input.pluginConfig?.dcp?.watchdog,
+      hookEnabled: !(input.pluginConfig?.disabled_hooks ?? []).includes("compress-watchdog")
+    }
+  }));
   if (messageHookRegistrations)
     registrations.push(...messageHookRegistrations);
   if (hooks["experimental.session.compacting"]) {
@@ -92138,7 +92421,7 @@ async function registerDomainConfigTransforms(input) {
     return [];
   }
   const registrations = [];
-  const agents = asRecord8(draft.agent ?? draft.agents);
+  const agents = asRecord9(draft.agent ?? draft.agents);
   if (Object.keys(agents).length > 0) {
     const defaultAgent = typeof draft.default_agent === "string" ? draft.default_agent : undefined;
     const result = await guard("config:agent", () => registerAgentTransform(ctx.agent, { agents, defaultAgent }));
@@ -92152,7 +92435,7 @@ async function registerDomainConfigTransforms(input) {
       registrations.push(result.registration);
     }
   }
-  const mcps = asRecord8(draft.mcp);
+  const mcps = asRecord9(draft.mcp);
   if (Object.keys(mcps).length > 0) {
     const result = await guard("config:mcp", () => registerMcpTransform(ctx.mcp, mcps));
     if (result) {
@@ -92162,7 +92445,7 @@ async function registerDomainConfigTransforms(input) {
       registrations.push(result.registration);
     }
   }
-  const commands = asRecord8(draft.command);
+  const commands = asRecord9(draft.command);
   if (Object.keys(commands).length > 0) {
     const v2ctx = ctx;
     const result = await guard("config:command", () => registerCommandTransform(ctx.command, commands, {
@@ -92172,7 +92455,7 @@ async function registerDomainConfigTransforms(input) {
     if (result)
       registrations.push(result.registration);
   }
-  const skills = asRecord8(draft.skill);
+  const skills = asRecord9(draft.skill);
   if (Object.keys(skills).length > 0) {
     const result = await guard("config:skill", () => registerSkillTransform(ctx.skill, skills));
     if (result)
@@ -92304,6 +92587,7 @@ async function setupDomains(ctx) {
   return {
     directory: pctx.directory,
     worktree: pctx.worktree,
+    pluginConfig,
     hooks: assembled
   };
 }
@@ -92314,8 +92598,8 @@ async function setup(ctx) {
     directory: ctx.location?.directory,
     opencode: ctx.app?.version
   });
-  const { hooks, directory, worktree } = await setupDomains(ctx);
-  const bridge = await registerDomains({ ctx, hooks, directory, worktree });
+  const { hooks, directory, worktree, pluginConfig } = await setupDomains(ctx);
+  const bridge = await registerDomains({ ctx, hooks, directory, worktree, pluginConfig });
   log("[matrixx] ready", { registrations: bridge.registrations.length });
   return async () => {
     await bridge.dispose();

package/dist/matrixx.schema.json

@@ -252,6 +252,7 @@
               "knowledge-hub-injector",
               "knowledge-hub-search-nudge",
               "dcp-nudge-sanitizer",
+              "compress-watchdog",
               "nudge-loop-breaker",
               "task-notepad-writer",
               "session-memory",
@@ -3050,12 +3051,53 @@
             "keepLast"
           ],
           "additionalProperties": false
+        },
+        "watchdog": {
+          "default": {
+            "enabled": true,
+            "abovePercent": 25,
+            "targetPercent": 10,
+            "cooldownTurns": 2
+          },
+          "type": "object",
+          "properties": {
+            "enabled": {
+              "default": true,
+              "type": "boolean"
+            },
+            "abovePercent": {
+              "default": 25,
+              "type": "number",
+              "minimum": 1,
+              "maximum": 95
+            },
+            "targetPercent": {
+              "default": 10,
+              "type": "number",
+              "minimum": 1,
+              "maximum": 94
+            },
+            "cooldownTurns": {
+              "default": 2,
+              "type": "integer",
+              "minimum": 1,
+              "maximum": 9007199254740991
+            }
+          },
+          "required": [
+            "enabled",
+            "abovePercent",
+            "targetPercent",
+            "cooldownTurns"
+          ],
+          "additionalProperties": false
         }
       },
       "required": [
         "enabled",
         "profiles",
-        "handoffCompression"
+        "handoffCompression",
+        "watchdog"
       ],
       "additionalProperties": false
     },

package/dist/plugin/message-hooks/compress-watchdog.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Compress watchdog — native session hook.
+ *
+ * Registers one `session.hook("context")` callback and, when the configured
+ * usage ceiling is crossed, prepends an explicit compress directive to the tail
+ * of the last user message. Tail injection preserves the prompt-cache prefix;
+ * the system prompt is never touched.
+ *
+ * Fail-open everywhere: an unknown model window, a missing token figure, a
+ * subagent session, or a missing `compress` tool all skip silently instead of
+ * injecting an instruction the model cannot satisfy.
+ */
+import { COMPRESS_WATCHDOG_MARKER, type CompressWatchdogConfigInput } from "../../shared/policy/compress-watchdog";
+import type { MatrixxContext, V2Registration } from "../tool/context";
+export interface CompressWatchdogOptions {
+    config?: CompressWatchdogConfigInput | undefined;
+    hookEnabled?: boolean | undefined;
+    now?: (() => number) | undefined;
+}
+export interface LastUserMessage {
+    index: number;
+    text: string;
+}
+/** Newest user message that carries text, or `null` when there is none. */
+export declare function findLastUserMessage(messages: readonly unknown[]): LastUserMessage | null;
+export interface SessionWatchState {
+    turns: number;
+    lastInjectedTurn: number | null;
+}
+export declare function turnsSinceLastInjection(state: SessionWatchState): number;
+/**
+ * Register the watchdog. Returns an empty list when disabled or when the
+ * `compress-watchdog` hook name is in `disabled_hooks`.
+ */
+export declare function registerCompressWatchdog(ctx: MatrixxContext, options?: CompressWatchdogOptions): Promise<V2Registration[]>;
+export { COMPRESS_WATCHDOG_MARKER };

package/dist/plugin/message-hooks/index.d.ts

@@ -1,6 +1,7 @@
 import type { EvolutionHitlDeps } from "../../hooks/evolution-hitl/flat";
 import type { SessionMessage } from "../../shared/session/session-message";
 import type { MatrixxContext, V2Registration } from "../tool/context";
+import { type CompressWatchdogOptions } from "./compress-watchdog";
 import { type ContextInjectorDeps } from "./context-injector";
 import { type KnowledgeHubInjectorDeps } from "./knowledge-hub-injector";
 /** Native session hook kinds that carry messages. */
@@ -39,6 +40,7 @@ export interface MessageHookDeps {
     readonly evolutionHitl?: EvolutionHitlDeps & {
         readonly config?: unknown;
     };
+    readonly compressWatchdog?: CompressWatchdogOptions;
 }
 /**
  * Register every mapping row through its per-hook module in

package/dist/plugin/setup-domains/assemble.d.ts

@@ -1,3 +1,4 @@
+import type { MatrixxConfig } from "../../config";
 import type { MatrixxContext, V2Registration } from "../tool/context";
 import type { Hooks } from "../tool/legacy-hooks";
 export interface RegisterDomainsInput {
@@ -5,6 +6,7 @@ export interface RegisterDomainsInput {
     hooks: Hooks;
     directory: string;
     worktree: string;
+    pluginConfig?: MatrixxConfig;
 }
 export interface DomainRegistration {
     registrations: V2Registration[];

package/dist/plugin/setup-domains.d.ts

@@ -18,6 +18,7 @@
  * `BackgroundManager` talks to `session.create`/`promptAsync` directly and
  * the tmux pane mirror is gone.
  */
+import type { MatrixxConfig } from "../config";
 import type { MatrixxContext } from "./tool/context";
 import type { Hooks } from "./tool/legacy-hooks";
 /**
@@ -29,6 +30,7 @@ export declare function setupDomains(ctx: MatrixxContext): Promise<{
     directory: string;
     worktree: string;
     hooks: Hooks;
+    pluginConfig: MatrixxConfig;
 }>;
 export type { DomainRegistration, RegisterDomainsInput, } from "./setup-domains/assemble";
 export { hideNativeSubagentTool, hookOutputText, registerDomains, } from "./setup-domains/assemble";

package/dist/shared/policy/compress-watchdog.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Compress watchdog policy (pure).
+ *
+ * DCP's `compress.maxContextLimit` is a *soft* nudge threshold: above it DCP
+ * only injects a generic "compress" reminder and the model decides whether,
+ * when, and how much to compress. When the model's per-turn growth matches its
+ * per-call savings the session settles above the configured ceiling.
+ *
+ * This module is the deterministic half of the Matrixx counter-measure: given
+ * the current usage, the configured ceiling, and the cooldown state, it decides
+ * whether an explicit directive should be injected into the tail of the last
+ * user message. Every threshold comes from configuration — nothing is
+ * hardcoded here except the marker and the wording of the directive.
+ *
+ * No I/O, no timers: safe to unit test in isolation.
+ */
+/** Config consumed by the watchdog (built from `dcp.watchdog`). */
+export interface CompressWatchdogConfig {
+    enabled: boolean;
+    /** Usage percentage that arms the directive. */
+    abovePercent: number;
+    /** Usage percentage the directive asks the model to reach. */
+    targetPercent: number;
+    /** Context builds to wait between directives while still over the ceiling. */
+    cooldownTurns: number;
+}
+/** Partial form as it arrives from `matrixx.jsonc` (Zod defaults may be absent). */
+export type CompressWatchdogConfigInput = Partial<CompressWatchdogConfig>;
+/** Sentinel that makes injection idempotent across repeated context builds. */
+export declare const COMPRESS_WATCHDOG_MARKER = "<matrixx-compress-watchdog>";
+export declare const DEFAULT_COMPRESS_WATCHDOG_CONFIG: CompressWatchdogConfig;
+/** Context usage read from the newest assistant message that reports tokens. */
+export interface ContextUsage {
+    tokens: number;
+    providerID?: string;
+    modelID?: string;
+}
+/**
+ * Normalize a partial config into a usable one. `targetPercent` is kept strictly
+ * below `abovePercent` so a misconfiguration cannot ask for a target the
+ * directive will never satisfy.
+ */
+export declare function resolveCompressWatchdogConfig(input?: CompressWatchdogConfigInput | undefined): CompressWatchdogConfig;
+/**
+ * Read the newest usage figure from a message list.
+ *
+ * Tolerant by design: the V2 session event has carried both flat messages
+ * (`{ type, tokens }`) and `{ info, parts }` projections across runtimes. Both
+ * shapes are accepted; anything else is skipped. A message without reported
+ * tokens is not evidence of low usage, so it is skipped rather than treated as
+ * zero.
+ */
+export declare function extractContextUsage(messages: readonly unknown[]): ContextUsage | null;
+/** Unwrap a model-list response (`Array`, `{ models }`, or `{ data }`). */
+export declare function modelListItems(raw: unknown): unknown[];
+/**
+ * Resolve the model's context window from the provider model list. Returns
+ * `null` when the model cannot be matched — callers must fail open rather than
+ * guess a window.
+ */
+export declare function resolveContextLimit(models: unknown, providerID?: string | undefined, modelID?: string | undefined): number | null;
+/** Usage as a percentage of the window (0 when the window is unusable). */
+export declare function usagePercent(tokens: number, limit: number): number;
+export interface ShouldInjectCompressDirectiveArgs {
+    config: CompressWatchdogConfig;
+    currentPercent: number;
+    /** Context builds since the last injection (cooldown accounting). */
+    turnsSinceLastInjection: number;
+    /** Text of the message the directive would be appended to. */
+    lastUserText?: string | undefined;
+}
+export declare function shouldInjectCompressDirective(args: ShouldInjectCompressDirectiveArgs): boolean;
+export interface BuildCompressDirectiveArgs {
+    currentPercent: number;
+    tokens: number;
+    limit: number;
+    config: CompressWatchdogConfig;
+}
+/**
+ * Build the directive appended to the tail of the conversation.
+ *
+ * It is deliberately explicit about the mechanics the model got wrong in
+ * practice: compress a *contiguous closed* span, copy boundary IDs verbatim,
+ * preserve durable facts, and repeat until the target is met.
+ */
+export declare function buildCompressDirective(args: BuildCompressDirectiveArgs): string;

package/dist/tools.js

@@ -8535,6 +8535,12 @@ var DcpManualModeSchema = object({
   enabled: boolean2().optional(),
   automaticStrategies: boolean2().optional()
 });
+var DcpWatchdogSchema = object({
+  enabled: boolean2().default(true),
+  abovePercent: number2().min(1).max(95).default(25),
+  targetPercent: number2().min(1).max(94).default(10),
+  cooldownTurns: number2().int().min(1).default(2)
+});
 var DcpProfileDefinitionSchema = object({
   pruneNotification: _enum(["off", "minimal", "detailed"]).optional(),
   pruneNotificationType: _enum(["chat", "toast"]).optional(),
@@ -8563,6 +8569,12 @@ var DcpConfigSchema = object({
     maxMessages: 6,
     keepFirst: 2,
     keepLast: 3
+  }),
+  watchdog: DcpWatchdogSchema.default({
+    enabled: true,
+    abovePercent: 25,
+    targetPercent: 10,
+    cooldownTurns: 2
   })
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-matrixx-v2",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",