hffmnnj.autocompact 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,94 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://unpkg.com/hffmnnj.autocompact/assets/banner.png" alt="Autocompact: pack idle context down." width="100%">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# hffmnnj.autocompact
+
+An [OpenCode](https://opencode.ai) V2 plugin that compacts a primary session after it has been idle for a short window, before the configured prompt-cache window expires. It is the OpenCode equivalent of Claude Code's idle auto-compact.
+
+## Install
+
+Reference the published package in the V2 config, keeping any existing plugin entries:
+
+```json
+{
+  "plugins": [
+    { "package": "hffmnnj.autocompact" }
+  ]
+}
+```
+
+Options are optional and can be passed alongside the package:
+
+```json
+{
+  "plugins": [
+    {
+      "package": "hffmnnj.autocompact",
+      "options": { "idleSeconds": 290, "cacheTtlSeconds": 300 }
+    }
+  ]
+}
+```
+
+## Behavior
+
+- A run that settles (`session.execution.succeeded`, `failed`, or `interrupted`) starts an idle countdown. The default is **290 seconds**, just under the configured five-minute cache window.
+- **Warming comes first.** The native `opencode.warming` plugin sends keep-alive requests while a session is idle. Each keep-alive restarts the countdown, so compaction fires **290 seconds after the final keep-alive**, once warming has stopped. Keep-alives are recognised by their prompt, which must match `warmingPrompt` (default: the native prompt). With warming disabled, the countdown runs from the settled run.
+- A new user prompt, model call, or execution cancels the pending countdown.
+- Compaction is requested with `session.compact({ delivery: "queue" })`. An idle session runs it immediately, and a racing user message is queued rather than injected into a running turn.
+- **At most one automatic compaction per idle stretch.** The compaction run's own settlement does not start another countdown. A new user prompt starts a fresh stretch.
+- **Only sessions this plugin instance has seen active.** Session events reach every plugin instance, but hooks reach only the instance whose location owns the session. A session becomes eligible only through a `prompt` or `context` hook in its own instance, so sessions that were already idle when the plugin loaded are left untouched.
+- **Primary sessions only** by default. Child sessions (subagents) are skipped unless `includeSubagents` is set.
+- **OpenAI-provider sessions are exempt.** At fire time the plugin re-reads the session and skips it when the current model's `providerID` is `openai`.
+- **Cache-expiry guard.** Compaction fires only while the elapsed idle time is below `cacheTtlSeconds` (default **300 seconds**). If the process was suspended and the timer wakes after this configured window, the plugin skips the attempt rather than risk a cold compaction. This does not guarantee a provider's actual cache retention or a cache hit.
+- **A compaction by anyone ends the stretch.** A manual `/compact` during the countdown cancels it, and no automatic one follows until the next user prompt.
+- **Location check at fire time.** Before compacting, the instance re-reads the session and refuses unless the session's directory is its own.
+- **Every decision is logged** when the decision log is enabled. The host records these compactions as `reason: "manual"`, so with the log enabled the plugin's decision log is the only way to tell them from a user's.
+- **Fail-open runtime observers.** Every hook and the event loop are wrapped. A bug in those observers is reported once per error class and swallowed; it cannot fail the session it watches.
+
+## Warming
+
+The native warming plugin sends a keep-alive as a generate request whose final message is exactly its prompt. Keep-alives emit no session events, so the request shape is the only signal that warming is still running.
+
+For default settings, keep the warming `interval` below `idleSeconds` (native default: 4 minutes against 290 seconds). A longer interval would let the countdown expire between keep-alives, so compaction could fire while warming is still running. If you customise the native `warming.prompt`, set `warmingPrompt` to the same text so keep-alives are still recognised.
+
+## Options
+
+| Option | Default | Meaning |
+| --- | --- | --- |
+| `idleSeconds` | `290` | Idle time after a settled run before compacting. Must be a positive integer less than `cacheTtlSeconds`. |
+| `cacheTtlSeconds` | `300` | Prompt-cache lifetime used by the expiry guard. Use `3600` for accounts on the 1-hour tier and set `idleSeconds` accordingly (for example `3300`). |
+| `includeSubagents` | `false` | Also compact child sessions. |
+| `warmingPrompt` | native keep-alive prompt | Must match a customised `warming.prompt` in the host config. The default is `This is a keep-alive request. Do not perform any work or use tools. Reply with exactly: OK`. |
+| `logFile` | `$XDG_STATE_HOME/opencode-autocompact/decisions.jsonl` | Absolute path for the decision log, or `false` to disable it. Falls back to `~/.local/state` when `XDG_STATE_HOME` is unset or empty. |
+
+Unknown options and invalid values are rejected when the plugin loads, so a typo cannot silently fall back to a default.
+
+## Decision log
+
+One JSON object per line, appended to `$XDG_STATE_HOME/opencode-autocompact/decisions.jsonl` (default `~/.local/state/opencode-autocompact/decisions.jsonl`). Set `logFile` to an absolute path to move it, or `false` to turn it off. Past 5 MB the active log rotates to `decisions.jsonl.1`, replacing any previous `.1`. Lines hold session IDs, timings, event names, option values and error class names, never conversation text or native error messages.
+
+Every line has `at`, `instance` (the location whose plugin instance decided) and `pid`, plus:
+
+| `event` | Meaning |
+| --- | --- |
+| `loaded` / `disposed` | Instance start and stop, with the effective options. |
+| `owned` | A prompt or model call reached this instance's hooks (`via`). Only then is a session a candidate. |
+| `armed` / `disarmed` | A countdown started (`via`: `settled` run or `keepalive`), or a pending countdown was cancelled (`why`). |
+| `keepalive-ignored`, `settle-ignored` | A signal changed nothing, and `why`. |
+| `skipped` | The countdown ended without compacting: `cache-expired`, `ineligible`, or `activity-during-lookup`. |
+| `compacting` / `compact-result` | The request was sent, and whether it was accepted (`ok`, `errorName`). |
+| `compaction-seen` | The host reported a compaction: `by: "plugin"` or `"other"` (a user's). |
+
+The plugin does not use `ctx.storage`; eligibility is held in memory, and the optional decision log is a local file.
+
+## Limitations
+
+- Compaction is **lossy** and is a model call. It runs whether or not you intended to come back, and there is no context-size floor, so small sessions can be compacted too.
+- Eligibility is in memory and resets on every host restart. A session becomes eligible again only after it runs or receives a prompt under the new host.
+- A run that began before the plugin loaded and settles afterwards is never compacted, because no hook of this instance saw it start.
+- A session run only by something that fires neither the `prompt` nor the `context` hook is never owned, so it is never compacted. That fails safe.
+- A failed compaction request is logged and not retried until the next user prompt.
+- The native host records these compactions as `reason: "manual"`, because they go through the API.
+- The timer uses wall-clock time. A suspended machine that wakes inside the configured TTL window can still compact; a wake at or after the TTL is skipped.

package/index.ts

@@ -0,0 +1 @@
+export { default } from "./src/index.ts";

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "hffmnnj.autocompact",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "assets/banner.png"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hffmnnj/opencode-autocompact.git"
+  },
+  "homepage": "https://github.com/hffmnnj/opencode-autocompact#readme",
+  "bugs": {
+    "url": "https://github.com/hffmnnj/opencode-autocompact/issues"
+  },
+  "dependencies": {
+    "@opencode/plugin": "2.0.25"
+  },
+  "devDependencies": {
+    "@opencode/sdk": "2.0.25",
+    "@types/bun": "1.3.5",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "bun test tests/unit",
+    "check": "bun run typecheck && bun run test",
+    "test:host": "bun tests/host/run.ts"
+  }
+}

package/src/compactor.ts

@@ -0,0 +1,196 @@
+import type { Trace } from "./trace";
+
+export interface CompactorOptions {
+  readonly idleMs: number;
+  readonly cacheTtlMs: number;
+  readonly includeSubagents: boolean;
+}
+
+export interface CompactorDeps {
+  readonly now: () => number;
+  /** Returns a cancel function. */
+  readonly schedule: (run: () => void, delayMs: number) => () => void;
+  readonly isEligible: (sessionID: string) => Promise<boolean>;
+  readonly compact: (sessionID: string) => Promise<void>;
+  /** Failures only; never include conversation content. */
+  readonly report: (message: string) => void;
+  /** Every decision is traced, so an unexpected compaction can be explained from the log. */
+  readonly trace: (trace: Trace) => void;
+}
+
+/**
+ * Session events are delivered to every plugin instance, but hooks only reach the instance whose location owns the
+ * session. A keep-alive is therefore visible only to the owner. State is created solely from owner-scoped signals
+ * (`userPrompted`, `modelCalled`); every event-driven method ignores sessions it has no state for. Without that rule,
+ * each other instance counts down on its own, never hears a keep-alive, and compacts a still-warming session.
+ */
+export interface IdleCompactor {
+  /** A model call seen through a hook, so this instance owns the session and it is running now. */
+  modelCalled(sessionID: string): void;
+  /** A compaction request by anyone (manual or automatic): this stretch has had its compaction. */
+  compactionRequested(sessionID: string): void;
+  executionStarted(sessionID: string): void;
+  executionSettled(sessionID: string): void;
+  /** A keep-alive ping: the countdown restarts from here, so compaction waits until warming stops. */
+  warmingPinged(sessionID: string): void;
+  userPrompted(sessionID: string): void;
+  forget(sessionID: string): void;
+  dispose(): void;
+}
+
+/** One idle stretch: from a settled run until the next user prompt or execution. */
+interface Stretch {
+  busy: boolean;
+  /** At most one automatic compaction per stretch, so our own compaction cannot re-arm the next one. */
+  compacted: boolean;
+  /**
+   * Set when this plugin asked for a compaction, cleared when the host's `compaction` hook reports it. That hook runs
+   * after `compact()` has already returned (the request is queued), so the flag cannot be tied to the call's lifetime.
+   */
+  requesting: boolean;
+  /** Bumped on every transition; a callback scheduled or started under an older value is stale. */
+  generation: number;
+  cancel?: () => void;
+}
+
+export function createIdleCompactor(options: CompactorOptions, deps: CompactorDeps): IdleCompactor {
+  const stretches = new Map<string, Stretch>();
+  let disposed = false;
+
+  /** Creates state, which marks this instance as the owner. Only owner-scoped hooks may call this. */
+  const own = (sessionID: string, via: "prompt" | "context"): Stretch => {
+    const existing = stretches.get(sessionID);
+    if (existing) return existing;
+    const created: Stretch = { busy: false, compacted: false, requesting: false, generation: 0 };
+    stretches.set(sessionID, created);
+    deps.trace({ event: "owned", sessionID, via });
+    return created;
+  };
+
+  const disarm = (sessionID: string, stretch: Stretch, why: Extract<Trace, { event: "disarmed" }>["why"]): void => {
+    // Only a countdown that was actually pending is worth a log line.
+    if (stretch.cancel) deps.trace({ event: "disarmed", sessionID, why });
+    stretch.generation++;
+    stretch.cancel?.();
+    stretch.cancel = undefined;
+  };
+
+  const arm = (sessionID: string, stretch: Stretch, via: "settled" | "keepalive"): void => {
+    stretch.generation++;
+    stretch.cancel?.();
+    const generation = stretch.generation;
+    const armedAt = deps.now();
+    deps.trace({ event: "armed", sessionID, via, fireInMs: options.idleMs });
+
+    const tick = (): void => {
+      stretch.cancel = undefined;
+      if (disposed || stretch.generation !== generation) return;
+
+      const elapsed = deps.now() - armedAt;
+      if (elapsed < options.idleMs) {
+        stretch.cancel = deps.schedule(tick, options.idleMs - elapsed);
+        return;
+      }
+      // A late wake (for example after laptop sleep) means the cache has already expired. Compacting cold
+      // re-reads the full history and then pays for the summary as well, which costs more than it saves.
+      if (elapsed >= options.cacheTtlMs) {
+        deps.trace({ event: "skipped", sessionID, why: "cache-expired", idleMs: elapsed });
+        return;
+      }
+
+      stretch.compacted = true;
+      void compactIdle(sessionID, generation, stretch, elapsed);
+    };
+
+    stretch.cancel = deps.schedule(tick, options.idleMs);
+  };
+
+  const compactIdle = async (sessionID: string, generation: number, stretch: Stretch, idleMs: number): Promise<void> => {
+    try {
+      if (!(await deps.isEligible(sessionID))) {
+        deps.trace({ event: "skipped", sessionID, why: "ineligible", idleMs });
+        return;
+      }
+      // Re-check after the awaited lookup: a prompt or new execution may have arrived in the meantime.
+      if (disposed || stretch.generation !== generation || stretch.busy) {
+        deps.trace({ event: "skipped", sessionID, why: "activity-during-lookup", idleMs });
+        return;
+      }
+      deps.trace({ event: "compacting", sessionID, idleMs });
+      stretch.requesting = true;
+      await deps.compact(sessionID);
+      deps.trace({ event: "compact-result", sessionID, ok: true });
+    } catch (error) {
+      // Never forward the native error text: it can contain conversation content. The class name is safe.
+      stretch.requesting = false;
+      deps.trace({ event: "compact-result", sessionID, ok: false, errorName: error instanceof Error ? error.name : "unknown" });
+      deps.report("idle compaction request failed; the session was left unchanged");
+    }
+  };
+
+  /** Event-driven methods only touch sessions that an owner-scoped signal already registered. */
+  const known = (sessionID: string): Stretch | undefined => stretches.get(sessionID);
+
+  return {
+    modelCalled(sessionID) {
+      const stretch = own(sessionID, "context");
+      stretch.busy = true;
+      disarm(sessionID, stretch, "model-call");
+    },
+    compactionRequested(sessionID) {
+      const stretch = known(sessionID);
+      if (!stretch) return;
+      deps.trace({ event: "compaction-seen", sessionID, by: stretch.requesting ? "plugin" : "other" });
+      stretch.requesting = false;
+      stretch.compacted = true;
+      disarm(sessionID, stretch, "compaction-seen");
+    },
+    executionStarted(sessionID) {
+      const stretch = known(sessionID);
+      if (!stretch) return;
+      stretch.busy = true;
+      disarm(sessionID, stretch, "execution-started");
+    },
+    executionSettled(sessionID) {
+      const stretch = known(sessionID);
+      if (!stretch) return;
+      stretch.busy = false;
+      if (disposed) return;
+      if (stretch.compacted) {
+        deps.trace({ event: "settle-ignored", sessionID, why: "already-compacted" });
+        return;
+      }
+      arm(sessionID, stretch, "settled");
+    },
+    warmingPinged(sessionID) {
+      const stretch = known(sessionID);
+      if (!stretch || disposed) return;
+      if (stretch.busy || stretch.compacted) {
+        deps.trace({ event: "keepalive-ignored", sessionID, why: stretch.busy ? "running" : "already-compacted" });
+        return;
+      }
+      arm(sessionID, stretch, "keepalive");
+    },
+    userPrompted(sessionID) {
+      const stretch = own(sessionID, "prompt");
+      stretch.compacted = false;
+      stretch.requesting = false;
+      disarm(sessionID, stretch, "prompt");
+    },
+    forget(sessionID) {
+      const stretch = stretches.get(sessionID);
+      if (!stretch) return;
+      disarm(sessionID, stretch, "forgotten");
+      stretches.delete(sessionID);
+    },
+    dispose() {
+      disposed = true;
+      for (const stretch of stretches.values()) {
+        stretch.generation++;
+        stretch.cancel?.();
+        stretch.cancel = undefined;
+      }
+      stretches.clear();
+    },
+  };
+}

package/src/config.ts

@@ -0,0 +1,63 @@
+import { isAbsolute } from "node:path";
+
+/** Default idle window: just under the 5-minute prompt-cache lifetime, so compaction is dispatched while the cache is still warm. */
+export const DEFAULT_IDLE_SECONDS = 290;
+/** Anthropic's default prompt-cache lifetime. Set to 3600 for accounts on the 1-hour tier. */
+export const DEFAULT_CACHE_TTL_SECONDS = 300;
+
+/** Must match the native `opencode.warming` default, or a customised warming prompt must be set here too. */
+export const DEFAULT_WARMING_PROMPT =
+  "This is a keep-alive request. Do not perform any work or use tools. Reply with exactly: OK";
+
+export interface AutoCompactConfig {
+  readonly idleSeconds: number;
+  readonly cacheTtlSeconds: number;
+  readonly includeSubagents: boolean;
+  readonly warmingPrompt: string;
+  /** Decision log path; `false` disables the file. `undefined` means the default state-directory path. */
+  readonly logFile: string | false | undefined;
+}
+
+const KNOWN_KEYS = new Set(["idleSeconds", "cacheTtlSeconds", "includeSubagents", "warmingPrompt", "logFile"]);
+
+function positiveInteger(value: unknown, name: string, fallback: number): number {
+  if (value === undefined) return fallback;
+  if (typeof value !== "number" || !Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`opencode-autocompact: ${name} must be a positive integer`);
+  }
+  return value;
+}
+
+/** Strict on purpose: an unknown key is almost always a typo that would otherwise silently keep the default. */
+export function parseConfig(raw: unknown): AutoCompactConfig {
+  if (raw === undefined) return parseConfig({});
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new Error("opencode-autocompact: options must be an object");
+  }
+  const unknown = Object.keys(raw).filter(key => !KNOWN_KEYS.has(key));
+  if (unknown.length > 0) {
+    throw new Error(`opencode-autocompact: unknown option(s): ${unknown.join(", ")}`);
+  }
+  const { idleSeconds, cacheTtlSeconds, includeSubagents, warmingPrompt, logFile } = raw as Record<string, unknown>;
+  if (logFile !== undefined && logFile !== false && (typeof logFile !== "string" || !isAbsolute(logFile))) {
+    throw new Error("opencode-autocompact: logFile must be an absolute path or false");
+  }
+  if (includeSubagents !== undefined && typeof includeSubagents !== "boolean") {
+    throw new Error("opencode-autocompact: includeSubagents must be a boolean");
+  }
+  if (warmingPrompt !== undefined && (typeof warmingPrompt !== "string" || warmingPrompt.length === 0)) {
+    throw new Error("opencode-autocompact: warmingPrompt must be a non-empty string");
+  }
+  const config: AutoCompactConfig = {
+    idleSeconds: positiveInteger(idleSeconds, "idleSeconds", DEFAULT_IDLE_SECONDS),
+    cacheTtlSeconds: positiveInteger(cacheTtlSeconds, "cacheTtlSeconds", DEFAULT_CACHE_TTL_SECONDS),
+    includeSubagents: includeSubagents ?? false,
+    warmingPrompt: warmingPrompt ?? DEFAULT_WARMING_PROMPT,
+    logFile,
+  };
+  // Compaction must be dispatched before the cache expires; an idle window at or past the TTL can never fire warm.
+  if (config.idleSeconds >= config.cacheTtlSeconds) {
+    throw new Error("opencode-autocompact: idleSeconds must be less than cacheTtlSeconds");
+  }
+  return config;
+}

package/src/index.ts

@@ -0,0 +1,112 @@
+import { Plugin } from "@opencode/plugin";
+import { createIdleCompactor } from "./compactor";
+import { parseConfig } from "./config";
+import { createDecisionLog, defaultLogPath } from "./log";
+import { failOpen } from "./safe";
+import { isWarmingPing } from "./warming";
+
+export default Plugin.define({
+  id: "hffmnnj.autocompact",
+  async setup(ctx) {
+    const config = parseConfig(ctx.options);
+    const warn = (message: string): void => console.warn(`opencode-autocompact: ${message}`);
+    const log =
+      config.logFile === false
+        ? undefined
+        : createDecisionLog(
+            config.logFile ?? defaultLogPath(),
+            { instance: ctx.location.directory, now: () => Date.now(), pid: process.pid },
+            warn,
+          );
+    const compactor = createIdleCompactor(
+      {
+        idleMs: config.idleSeconds * 1000,
+        cacheTtlMs: config.cacheTtlSeconds * 1000,
+        includeSubagents: config.includeSubagents,
+      },
+      {
+        now: () => Date.now(),
+        schedule: (run, delayMs) => {
+          const timer = setTimeout(run, delayMs);
+          return () => clearTimeout(timer);
+        },
+        isEligible: async sessionID => {
+          const info = await ctx.session.get({ sessionID });
+          // Official OpenAI models now retain their prompt cache without this idle compaction.
+          if (info.model?.providerID === "openai") return false;
+          // Hooks are location-scoped today, so only the owning instance has state. This check keeps a second
+          // instance from compacting someone else's session should that ever stop being true.
+          if (info.location.directory !== ctx.location.directory) return false;
+          return config.includeSubagents || info.parentID === undefined;
+        },
+        // Queue rather than steer: an idle session runs the compaction now, and a racing user message is never injected mid-run.
+        compact: async sessionID => {
+          await ctx.session.compact({ sessionID, delivery: "queue" });
+        },
+        report: warn,
+        trace: trace => {
+          log?.sink(trace);
+          if (trace.event === "compacting") {
+            warn(`compacting ${trace.sessionID} after ${Math.round(trace.idleMs / 1000)}s idle in ${ctx.location.directory}`);
+          }
+        },
+      },
+    );
+
+    // These hooks reach only the instance that owns the session's location, which is what makes them proof of ownership.
+    // Every observer is wrapped: a bug here must never fail the session it is watching.
+    const promptHook = await ctx.session.hook("prompt", failOpen("prompt hook", event => {
+      compactor.userPrompted(event.sessionID);
+    }, warn));
+    const contextHook = await ctx.session.hook("context", failOpen("context hook", event => {
+      compactor.modelCalled(event.sessionID);
+    }, warn));
+    const compactionHook = await ctx.session.hook("compaction", failOpen("compaction hook", event => {
+      compactor.compactionRequested(event.sessionID);
+    }, warn));
+    // Observe only: the keep-alive request is answered normally; this hook never alters it.
+    const warmingHook = await ctx.session.hook("generate", failOpen("generate hook", event => {
+      if (isWarmingPing(event.messages, config.warmingPrompt)) compactor.warmingPinged(event.sessionID);
+    }, warn));
+
+    const subscription = new AbortController();
+    // One bad event is reported and skipped; it must not end the subscription.
+    const onEvent = failOpen("event handler", (event: { type: string; data?: unknown }) => {
+      const sessionID = (event.data as { sessionID?: string } | undefined)?.sessionID;
+      if (sessionID === undefined) return;
+      switch (event.type) {
+        case "session.execution.started":
+          compactor.executionStarted(sessionID);
+          break;
+        case "session.execution.succeeded":
+        case "session.execution.failed":
+        case "session.execution.interrupted":
+          compactor.executionSettled(sessionID);
+          break;
+        case "session.deleted":
+          compactor.forget(sessionID);
+          break;
+      }
+    }, warn);
+    const observing = (async () => {
+      for await (const event of ctx.event.subscribe({ signal: subscription.signal })) onEvent(event);
+    })().catch(() => {
+      if (!subscription.signal.aborted) {
+        console.warn("opencode-autocompact: event subscription ended; automatic idle compaction is inactive");
+      }
+    });
+
+    log?.sink({ event: "loaded", idleSeconds: config.idleSeconds, cacheTtlSeconds: config.cacheTtlSeconds, includeSubagents: config.includeSubagents });
+    return async () => {
+      subscription.abort();
+      compactor.dispose();
+      await promptHook.dispose();
+      await contextHook.dispose();
+      await compactionHook.dispose();
+      await warmingHook.dispose();
+      await observing;
+      log?.sink({ event: "disposed" });
+      await log?.flush();
+    };
+  },
+});

package/src/log.ts

@@ -0,0 +1,68 @@
+import { appendFile, mkdir, rename, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import type { Trace, TraceSink } from "./trace";
+
+const MAX_BYTES = 5 * 1024 * 1024;
+const ROTATE_CHECK_EVERY = 500;
+
+/** `$XDG_STATE_HOME/opencode-autocompact/decisions.jsonl`, falling back to `~/.local/state`. */
+export function defaultLogPath(env: Readonly<Record<string, string | undefined>> = process.env): string {
+  const state = env.XDG_STATE_HOME && env.XDG_STATE_HOME.length > 0 ? env.XDG_STATE_HOME : join(homedir(), ".local", "state");
+  return join(state, "opencode-autocompact", "decisions.jsonl");
+}
+
+export interface LogContext {
+  /** Directory of the plugin instance that made the decision; the host loads one instance per location. */
+  readonly instance: string;
+  readonly now: () => number;
+  readonly pid: number;
+}
+
+export interface DecisionLog {
+  readonly sink: TraceSink;
+  /** Resolves when every queued line has been written (or has failed). */
+  flush(): Promise<void>;
+}
+
+/** One JSON object per line: easy to grep, and `O_APPEND` keeps lines from different instances intact. */
+export function formatLine(trace: Trace, context: LogContext): string {
+  return `${JSON.stringify({ at: new Date(context.now()).toISOString(), instance: context.instance, pid: context.pid, ...trace })}\n`;
+}
+
+/**
+ * Fail-open: a logging problem is reported once and never reaches the compaction path. The previous file is kept as
+ * `<path>.1` when the log grows past 5 MB; rotation renames, it never deletes.
+ */
+export function createDecisionLog(path: string, context: LogContext, warn: (message: string) => void): DecisionLog {
+  let queue: Promise<void> = Promise.resolve();
+  let written = 0;
+  let warned = false;
+
+  const rotateIfLarge = async (): Promise<void> => {
+    const size = await stat(path).then(info => info.size, () => 0);
+    if (size > MAX_BYTES) await rename(path, `${path}.1`);
+  };
+
+  const write = async (line: string): Promise<void> => {
+    try {
+      if (written++ % ROTATE_CHECK_EVERY === 0) {
+        await mkdir(dirname(path), { recursive: true });
+        await rotateIfLarge();
+      }
+      await appendFile(path, line, { mode: 0o600 });
+    } catch {
+      if (!warned) {
+        warned = true;
+        warn(`could not write the decision log at ${path}; automatic compaction is unaffected`);
+      }
+    }
+  };
+
+  return {
+    sink: trace => {
+      queue = queue.then(() => write(formatLine(trace, context)));
+    },
+    flush: () => queue,
+  };
+}

package/src/safe.ts

@@ -0,0 +1,22 @@
+/**
+ * Wraps an observer so that its own bug can never reach the host. An uncaught throw in a hook fails the session's run
+ * ("Failed to drain Session"), and this plugin only watches sessions, so it must never be the cause of that.
+ * Reports once per distinct error class to keep a repeating fault from flooding the log.
+ */
+export function failOpen<Args extends ReadonlyArray<unknown>>(
+  name: string,
+  observe: (...args: Args) => void,
+  report: (message: string) => void,
+): (...args: Args) => void {
+  const reported = new Set<string>();
+  return (...args) => {
+    try {
+      observe(...args);
+    } catch (error) {
+      const kind = error instanceof Error ? error.name : "unknown";
+      if (reported.has(kind)) return;
+      reported.add(kind);
+      report(`${name} failed (${kind}); the session was not affected`);
+    }
+  };
+}

package/src/trace.ts

@@ -0,0 +1,18 @@
+/**
+ * One decision the compactor made. Entries carry session IDs and timings only, never conversation content or
+ * native error text, so the log is safe to keep and share.
+ */
+export type Trace =
+  | { readonly event: "loaded"; readonly idleSeconds: number; readonly cacheTtlSeconds: number; readonly includeSubagents: boolean }
+  | { readonly event: "disposed" }
+  | { readonly event: "owned"; readonly sessionID: string; readonly via: "prompt" | "context" }
+  | { readonly event: "armed"; readonly sessionID: string; readonly via: "settled" | "keepalive"; readonly fireInMs: number }
+  | { readonly event: "disarmed"; readonly sessionID: string; readonly why: "prompt" | "model-call" | "execution-started" | "compaction-seen" | "forgotten" }
+  | { readonly event: "keepalive-ignored"; readonly sessionID: string; readonly why: "running" | "already-compacted" }
+  | { readonly event: "settle-ignored"; readonly sessionID: string; readonly why: "already-compacted" }
+  | { readonly event: "skipped"; readonly sessionID: string; readonly why: "cache-expired" | "ineligible" | "activity-during-lookup"; readonly idleMs: number }
+  | { readonly event: "compacting"; readonly sessionID: string; readonly idleMs: number }
+  | { readonly event: "compaction-seen"; readonly sessionID: string; readonly by: "plugin" | "other" }
+  | { readonly event: "compact-result"; readonly sessionID: string; readonly ok: boolean; readonly errorName?: string };
+
+export type TraceSink = (trace: Trace) => void;

package/src/warming.ts

@@ -0,0 +1,12 @@
+/**
+ * The native warming plugin sends a keep-alive as a generate request whose final message is exactly its prompt.
+ * Keep-alives emit no session events, so this request shape is the only signal that warming is still running.
+ */
+export function isWarmingPing(messages: ReadonlyArray<unknown>, warmingPrompt: string): boolean {
+  const last: unknown = messages.at(-1);
+  if (typeof last !== "object" || last === null) return false;
+  const { role, content } = last as { role?: unknown; content?: unknown };
+  if (role !== "user" || !Array.isArray(content) || content.length !== 1) return false;
+  const [part] = content as ReadonlyArray<{ type?: unknown; text?: unknown }>;
+  return part?.type === "text" && part.text === warmingPrompt;
+}