an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions
HTML agent-harnessagent-orchestrationagentsai-agentsautonomous-agentsclaude-codecodexcoding-agentsdesktop-appdeveloper-toolselectrongemini-cliharnessharness-engineeringlocal-firstmemorymulti-agentopencodeorchestrationtypescript
feat(compact-protocol): implement COMPACT PROTOCOL + REFRESH PROTOCOL behind flag (default off)
Chaitanya Giri2a6ad847f140
diff --git a/src/main/compact-gate.cjs b/src/main/compact-gate.cjsnew file mode 100644index 00000000..5d381989--- /dev/null+++ b/src/main/compact-gate.cjs@@ -0,0 +1,107 @@+'use strict';++// CompactGate — core logic for the COMPACT PROTOCOL (see hive/protocols/COMPACT-PROTOCOL.md).+//+// Plain CommonJS so tests can require() this without transpilation and so it+// can be imported from compact.ts with no bundler special-casing.+//+// Responsibilities:+// - Single-flight: at most one compaction per agent in flight+// - Cooldown: after a compaction completes, suppresses all compact requests+// (from any service) for the cooldown window — no compact-on-top-of-compact+// - 50% threshold: trigger at 50% context utilisation (was 80% in old watchdog)+// - Fire counter: after every N fires, emit 'refresh' instead of 'compact' so+// the agent receives the REFRESH PROTOCOL message instead of a silent /compact+// - Counter reset: when context drops well below threshold the counter resets,+// indicating a genuine workload drop / context reclaim++const DEFAULT_THRESHOLD = 0.50;+const DEFAULT_COOLDOWN_MS = 90_000; // 90 s — long enough to cover most /compact ops+const DEFAULT_REFRESH_AFTER_FIRES = 3;++class CompactGate {+ constructor({+ enabled = false,+ threshold = DEFAULT_THRESHOLD,+ cooldownMs = DEFAULT_COOLDOWN_MS,+ refreshAfterFires = DEFAULT_REFRESH_AFTER_FIRES,+ } = {}) {+ this.enabled = enabled;+ this.threshold = threshold;+ this.cooldownMs = cooldownMs;+ this.refreshAfterFires = refreshAfterFires;++ /** agentId → true while a compaction request is in flight (not yet completed). */+ this.pending = new Set();+ /** agentId → timestamp (ms) after which the cooldown expires. */+ this.cooldownUntil = new Map();+ /** agentId → consecutive compaction fire count (resets on workload drop). */+ this.fireCount = new Map();+ }++ /**+ * Called by the Status hook handler with each context-window reading.+ *+ * Returns:+ * 'skip' — below threshold or gate disabled; do nothing+ * 'blocked' — above threshold but single-flight or cooldown active; do nothing+ * 'compact' — threshold crossed; issue /compact for this agent+ * 'refresh' — every Nth fire; emit REFRESH PROTOCOL message instead+ */+ check(agentId, contextPct) {+ if (!this.enabled) return 'skip';++ if (contextPct < this.threshold) {+ // Well below threshold (< threshold/2) → workload dropped; reset the fire+ // counter so the next crossing starts fresh rather than escalating to REFRESH+ // prematurely after a genuine context reclaim.+ if (contextPct < this.threshold / 2) {+ this.fireCount.delete(agentId);+ this.pending.delete(agentId);+ }+ return 'skip';+ }++ // Single-flight guard+ if (this.pending.has(agentId)) return 'blocked';++ // Cooldown guard (dedup across any service that might trigger a compact)+ const cd = this.cooldownUntil.get(agentId);+ if (cd !== undefined && Date.now() < cd) return 'blocked';++ // Increment consecutive fire count+ const fires = (this.fireCount.get(agentId) ?? 0) + 1;+ this.fireCount.set(agentId, fires);+ this.pending.add(agentId);++ return fires % this.refreshAfterFires === 0 ? 'refresh' : 'compact';+ }++ /**+ * Call when a compaction has completed (e.g., the post-compact Stop hook fires).+ * Clears the in-flight flag and starts the cooldown window.+ */+ onCompacted(agentId) {+ this.pending.delete(agentId);+ this.cooldownUntil.set(agentId, Date.now() + this.cooldownMs);+ }++ /**+ * Returns true when this gate would suppress a compact request for agentId.+ * Use this to let the scheduler standup or janitor defer to the gate.+ */+ isBlocked(agentId) {+ if (this.pending.has(agentId)) return true;+ const cd = this.cooldownUntil.get(agentId);+ return cd !== undefined && Date.now() < cd;+ }++ /** Remove all per-agent state (agent removed / disconnected). */+ remove(agentId) {+ this.pending.delete(agentId);+ this.cooldownUntil.delete(agentId);+ this.fireCount.delete(agentId);+ }+}++module.exports = { CompactGate, DEFAULT_THRESHOLD, DEFAULT_COOLDOWN_MS, DEFAULT_REFRESH_AFTER_FIRES };diff --git a/src/main/compact.ts b/src/main/compact.tsnew file mode 100644index 00000000..0d8f547c--- /dev/null+++ b/src/main/compact.ts@@ -0,0 +1,60 @@+/**+ * TypeScript wrapper around compact-gate.cjs so the main process and hooks.ts+ * can import with full types. The plain-JS core lives in compact-gate.cjs so+ * tests can require() it directly without a TypeScript compile step.+ */++// eslint-disable-next-line @typescript-eslint/no-require-imports+const { CompactGate: _CG, DEFAULT_THRESHOLD, DEFAULT_COOLDOWN_MS, DEFAULT_REFRESH_AFTER_FIRES } =+ require('./compact-gate.cjs') as {+ CompactGate: new (opts?: CompactGateConfig) => _GateInstance;+ DEFAULT_THRESHOLD: number;+ DEFAULT_COOLDOWN_MS: number;+ DEFAULT_REFRESH_AFTER_FIRES: number;+ };++export { DEFAULT_THRESHOLD, DEFAULT_COOLDOWN_MS, DEFAULT_REFRESH_AFTER_FIRES };++export type CompactAction = 'compact' | 'refresh' | 'blocked' | 'skip';++export interface CompactGateConfig {+ /** Feature flag — default false. Zero behavior change when off. */+ enabled?: boolean;+ /** Context-window utilisation threshold (0–1). Default 0.50 (50%). */+ threshold?: number;+ /** Milliseconds to suppress all compact requests after one completes. Default 90 000. */+ cooldownMs?: number;+ /** Issue REFRESH PROTOCOL after every N fires. Default 3. */+ refreshAfterFires?: number;+}++interface _GateInstance {+ enabled: boolean;+ threshold: number;+ pending: Set<string>;+ fireCount: Map<string, number>;+ check(agentId: string, contextPct: number): string;+ onCompacted(agentId: string): void;+ isBlocked(agentId: string): boolean;+ remove(agentId: string): void;+}++export class CompactGate {+ readonly enabled: boolean;+ readonly threshold: number;+ private _g: _GateInstance;++ constructor(config: CompactGateConfig = {}) {+ this._g = new _CG(config);+ this.enabled = this._g.enabled;+ this.threshold = this._g.threshold;+ }++ check(agentId: string, contextPct: number): CompactAction {+ return this._g.check(agentId, contextPct) as CompactAction;+ }++ onCompacted(agentId: string): void { this._g.onCompacted(agentId); }+ isBlocked(agentId: string): boolean { return this._g.isBlocked(agentId); }+ remove(agentId: string): void { this._g.remove(agentId); }+}diff --git a/src/main/config.ts b/src/main/config.tsindex 8b11c83e..ec2df1ac 100644--- a/src/main/config.ts+++ b/src/main/config.ts@@ -72,6 +72,21 @@ export const HEARTBEAT_MISSION: ScheduledMission = {quietThresholdMs: 300_000};+/** COMPACT PROTOCOL config (see hive/protocols/COMPACT-PROTOCOL.md).+ * Default off — zero behavior change until explicitly enabled. Shared floor+ * infra; requires god + human sign-off before activation (flag flip). */+export interface CompactProtocolConfig {+ /** Master feature flag. Default false = old 80%-watchdog + standup path unchanged. */+ enabled?: boolean;+ /** Context utilisation threshold (0–1) to trigger compaction. Default 0.50. */+ threshold?: number;+ /** Cooldown (ms) after a compaction completes — any service is suppressed for+ * this window (dedup gate). Default 90 000 (90 s). */+ cooldownMs?: number;+ /** After every N fires, emit REFRESH PROTOCOL instead of /compact. Default 3. */+ refreshAfterFires?: number;+}+/** Circuit-breaker thresholds (Lane A #6.6b). The breaker runs inside the* heartbeat beat, so it only ticks when the heartbeat is enabled. Trip* conditions are behavioral by default; `costCapUsd` is the only $-based one and@@ -136,6 +151,9 @@ export interface HarnessConfig {maxTurns?: number;/** Circuit-breaker thresholds (Lane A #6.6b). Unset = conservative defaults. */circuitBreaker?: CircuitBreakerConfig;+ /** COMPACT PROTOCOL (see hive/protocols/COMPACT-PROTOCOL.md). Default off —+ * requires god + human sign-off before enabling. */+ compactProtocol?: CompactProtocolConfig;/** Fire native desktop notifications on agent lifecycle events (idle finish / waiting for input). */notifications?: boolean;/** Terminal theme — mirrored into each agent's per-session Claude settingsdiff --git a/src/main/hooks.ts b/src/main/hooks.tsindex 4ed79aed..bb4f747d 100644--- a/src/main/hooks.ts+++ b/src/main/hooks.ts@@ -18,6 +18,7 @@ import type { HiveManager } from './hive';import type { HarnessConfig } from './config';import type { ControlRegistry } from './control';import type { CircuitBreaker } from './breaker';+import { CompactGate, type CompactGateConfig } from './compact';interface HookPayload {hook_event_name?: string;@@ -44,6 +45,9 @@ export class HookServer {* Lets the harness read per-agent telemetry (e.g. current context size)* even when several agents share one cwd. */private transcriptPaths = new Map<string, string>();+ /** COMPACT PROTOCOL gate — lazily initialised from config when the flag is on.+ * null when the feature flag is off (zero behavior change). */+ private compactGate: CompactGate | null = null;constructor(private hive: HiveManager,@@ -118,6 +122,13 @@ export class HookServer {tokens: cw.total_input_tokens,limit: cw.context_window_size});+ // COMPACT PROTOCOL gate (flag-gated — zero effect when disabled).+ // Check on every Status tick; the gate deduplicates via pending+cooldown.+ const pct = cw.total_input_tokens / cw.context_window_size;+ const action = this.getGate()?.check(agentId, pct);+ if (action === 'compact' || action === 'refresh') {+ this.getWebContents()?.send('hive:compactAgent', { agentId, action });+ }}return {};}@@ -141,6 +152,9 @@ export class HookServer {}if ((event === 'Stop' || event === 'SubagentStop') && agentId) {+ // Notify the compact gate that the agent has stopped (compact completed or+ // genuinely idle) — starts the cooldown window so no service double-compacts.+ this.getGate()?.onCompacted(agentId);// Loop guard: a previous Stop hook already blocked this turn → let it stop.if (p.stop_hook_active) { this.emit(agentId, event, p); return {}; }const drain = this.hive.drainForStop(agentId);@@ -204,6 +218,16 @@ export class HookServer {return {};}+ /** Return the active CompactGate if the feature flag is on, else null.+ * Lazily creates the gate on first use; nulls it when the flag turns off.+ * Reading config per-call is cheap (in-memory read from disk-backed JSON). */+ private getGate(): CompactGate | null {+ const cp = this.getConfig().compactProtocol as CompactGateConfig | undefined;+ if (!cp?.enabled) { this.compactGate = null; return null; }+ if (!this.compactGate) this.compactGate = new CompactGate(cp);+ return this.compactGate;+ }+/** Fire a native desktop notification — gated on the user's `notifications`* setting. Only the OS toast is gated; the hive:hookEvent emit is always sent* so avatars/UI stay live regardless. Best-effort: never throw into the hook. */diff --git a/src/preload/index.ts b/src/preload/index.tsindex 4430eda1..94f0d5a2 100644--- a/src/preload/index.ts+++ b/src/preload/index.ts@@ -572,6 +572,16 @@ const api = {ipcRenderer.on('mission:autoCompact', listener);return () => ipcRenderer.removeListener('mission:autoCompact', listener);},+ /** COMPACT PROTOCOL (flag-gated): the main-process gate detected a threshold+ * crossing for a specific agent. Action is 'compact' (issue /compact) or+ * 'refresh' (emit REFRESH PROTOCOL message). Only fires when the flag is on. */+ onCompactAgent: (+ cb: (e: { agentId: string; action: 'compact' | 'refresh' }) => void+ ): (() => void) => {+ const listener = (_e: IpcRendererEvent, payload: { agentId: string; action: 'compact' | 'refresh' }) => cb(payload);+ ipcRenderer.on('hive:compactAgent', listener);+ return () => ipcRenderer.removeListener('hive:compactAgent', listener);+ },// ─── Full-text search across hive files (board, tasks, memory) ─────────────textSearch: (q: string): Promise<{ ok: boolean; results: Array<{ source: string; excerpt: string }> }> =>diff --git a/src/renderer/src/hooks/useHive.ts b/src/renderer/src/hooks/useHive.tsindex cd23f879..90dffbeb 100644--- a/src/renderer/src/hooks/useHive.ts+++ b/src/renderer/src/hooks/useHive.ts@@ -42,6 +42,17 @@ const COMPACT_CMD ='/compact Summarise exactly what you are currently working on and the next step, ' +'so you can resume from the same point — then continue that work after compacting.';+// REFRESH PROTOCOL message — sent after every 3rd COMPACT PROTOCOL fire when+// compaction is no longer reclaiming enough headroom. Instructs the agent to+// flush state, checkpoint the task, and start a fresh context session.+const REFRESH_MSG =+ 'Context window has grown. Repeated compaction is no longer reclaiming enough headroom ' ++ 'and performance degradation is likely if you continue. Follow the REFRESH PROTOCOL:\n' ++ '1. Flush all working state to memory.md (let the miner push it to MemPalace).\n' ++ '2. Checkpoint the in-flight task in tasks.json + board so nothing is lost.\n' ++ '3. Start a fresh context (/clear or a new session), then run `mempalace wake-up` ' ++ 'to rehydrate the durable digest. Resume on a clean slate backed by the palace.';+// Per-pty submission chain. Every submitToPty for a given pty is appended here so// two callers (e.g. the boot sequence's /remote-control and the inbox-wake nudge)// can NEVER interleave their text + Enter — which jammed them onto one line and@@ -584,9 +595,13 @@ export function useHive(config: HarnessConfig | null): void {// /compact for each live agent so the drain (#4) delivers it only when the// agent is idle — never jamming a working terminal. Deduped: if a /compact// is already queued for an agent, skip it (no second one piles up).+ // When the COMPACT PROTOCOL gate is enabled, the gate drives per-agent+ // compaction via effect #7 below — skip the blanket standup queue to avoid+ // compact-on-top-of-compact (the gate already deduplicates via cooldown).useEffect(() => {if (!config?.onboardingComplete) return;return window.cth.onAutoCompact(() => {+ if (config?.compactProtocol?.enabled) return; // gate-driven path handles itconst { agents, messageQueues, enqueueMessage } = useStore.getState();for (const a of agents) {if (!a.ptyId) continue;@@ -598,5 +613,30 @@ export function useHive(config: HarnessConfig | null): void {enqueueMessage(a.id, COMPACT_CMD);}});+ }, [config?.onboardingComplete, config?.compactProtocol?.enabled]);++ // 7) COMPACT PROTOCOL gate (flag-gated). Main process detected a 50% threshold+ // crossing for a specific agent and requests either a /compact or a REFRESH.+ // Only fires when compactProtocol.enabled is true — deduped at the gate level.+ useEffect(() => {+ if (!config?.onboardingComplete) return;+ return window.cth.onCompactAgent?.((e) => {+ const { agents, messageQueues, enqueueMessage } = useStore.getState();+ const a = agents.find((x) => x.id === e.agentId);+ if (!a?.ptyId) return;+ if (!isClaudeProvider(inferAgentProvider(a.command, a.provider))) return;+ if (e.action === 'refresh') {+ // REFRESH PROTOCOL: send the full refresh instructions (not a /compact).+ // Dedup: skip if a refresh message is already queued.+ const queued = messageQueues[a.id] ?? [];+ if (queued.some((m) => m.text.startsWith('Context window has grown'))) return;+ enqueueMessage(a.id, REFRESH_MSG);+ } else {+ // 'compact': enqueue /compact, deduped.+ const queued = messageQueues[a.id] ?? [];+ if (queued.some((m) => m.text.trimStart().startsWith('/compact'))) return;+ enqueueMessage(a.id, COMPACT_CMD);+ }+ });}, [config?.onboardingComplete]);}diff --git a/test/compact.test.cjs b/test/compact.test.cjsnew file mode 100644index 00000000..1acc2782--- /dev/null+++ b/test/compact.test.cjs@@ -0,0 +1,162 @@+'use strict';++const assert = require('assert');+const { CompactGate, DEFAULT_THRESHOLD, DEFAULT_COOLDOWN_MS, DEFAULT_REFRESH_AFTER_FIRES } =+ require('../src/main/compact-gate.cjs');++function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }++let failures = 0;+async function test(name, fn) {+ try {+ await fn();+ console.log(` ✓ ${name}`);+ } catch (err) {+ failures++;+ console.log(` ✗ ${name}\n ${err.message}`);+ }+}++(async () => {+ console.log('compact gate tests (COMPACT PROTOCOL)');++ // ─── Defaults ──────────────────────────────────────────────────────────────++ await test('exported defaults match spec', async () => {+ assert.strictEqual(DEFAULT_THRESHOLD, 0.50);+ assert.strictEqual(DEFAULT_COOLDOWN_MS, 90_000);+ assert.strictEqual(DEFAULT_REFRESH_AFTER_FIRES, 3);+ });++ // ─── Feature flag ──────────────────────────────────────────────────────────++ await test('disabled gate → always skip regardless of context %', async () => {+ const g = new CompactGate({ enabled: false });+ assert.strictEqual(g.check('a', 1.0), 'skip');+ assert.strictEqual(g.check('a', 0.99), 'skip');+ });++ // ─── 50% threshold ─────────────────────────────────────────────────────────++ await test('below threshold → skip', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50 });+ assert.strictEqual(g.check('a', 0.49), 'skip');+ });++ await test('exactly at threshold → compact', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50 });+ assert.strictEqual(g.check('a', 0.50), 'compact');+ });++ await test('above threshold → compact', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50 });+ assert.strictEqual(g.check('a', 0.80), 'compact');+ });++ // ─── Single-flight ─────────────────────────────────────────────────────────++ await test('second check while pending → blocked (single-flight)', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50 });+ assert.strictEqual(g.check('a', 0.75), 'compact');+ assert.strictEqual(g.check('a', 0.80), 'blocked');+ assert.strictEqual(g.check('a', 0.99), 'blocked');+ });++ await test('different agents are independent (single-flight is per-agent)', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50 });+ assert.strictEqual(g.check('a', 0.75), 'compact');+ assert.strictEqual(g.check('b', 0.75), 'compact'); // 'b' not blocked by 'a'+ assert.strictEqual(g.check('a', 0.80), 'blocked'); // 'a' still blocked+ });++ // ─── Dedup cooldown across services ────────────────────────────────────────++ await test('cooldown blocks all services after compacted', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 300 });+ g.check('a', 0.75); // puts in pending+ g.onCompacted('a'); // clears pending, starts 300ms cooldown+ assert.ok(g.isBlocked('a'), 'blocked immediately after compacted');+ assert.strictEqual(g.check('a', 0.75), 'blocked', 'check returns blocked during cooldown');+ });++ await test('cooldown expires → not blocked', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 100 });+ g.check('a', 0.75);+ g.onCompacted('a');+ await sleep(150);+ assert.ok(!g.isBlocked('a'), 'not blocked after cooldown expires');+ assert.strictEqual(g.check('a', 0.75), 'compact', 'can compact again after cooldown');+ });++ await test('isBlocked returns false when not pending and no cooldown', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50 });+ assert.ok(!g.isBlocked('a'));+ });++ // ─── 3-fire → REFRESH escalation ───────────────────────────────────────────++ await test('fires 1 and 2 produce compact, fire 3 produces refresh', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 0, refreshAfterFires: 3 });+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 1');+ g.onCompacted('a');+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 2');+ g.onCompacted('a');+ assert.strictEqual(g.check('a', 0.75), 'refresh', 'fire 3 → REFRESH');+ });++ await test('counter continues after refresh: fires 4,5 compact, fire 6 refresh', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 0, refreshAfterFires: 3 });+ // fires 1–3+ g.check('a', 0.75); g.onCompacted('a');+ g.check('a', 0.75); g.onCompacted('a');+ g.check('a', 0.75); g.onCompacted('a'); // fire 3 = refresh+ // fires 4–6+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 4');+ g.onCompacted('a');+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 5');+ g.onCompacted('a');+ assert.strictEqual(g.check('a', 0.75), 'refresh', 'fire 6 → REFRESH');+ });++ // ─── Counter reset on context drop ─────────────────────────────────────────++ await test('context drops to threshold/2 → fire counter resets', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 0, refreshAfterFires: 3 });+ // Two fires (fires 1 and 2 — next would be refresh on 3)+ g.check('a', 0.75); g.onCompacted('a');+ g.check('a', 0.75); g.onCompacted('a');+ // Context drops well below threshold (< 0.25)+ g.check('a', 0.20); // should reset counter and return 'skip'+ // Now the counter is reset — next three fires should be 1,2,compact then 3=refresh+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 1 after reset');+ g.onCompacted('a');+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 2 after reset');+ g.onCompacted('a');+ assert.strictEqual(g.check('a', 0.75), 'refresh', 'fire 3 after reset → REFRESH');+ });++ await test('context between threshold/2 and threshold → no counter reset', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 0, refreshAfterFires: 3 });+ g.check('a', 0.75); g.onCompacted('a'); // fire 1+ g.check('a', 0.75); g.onCompacted('a'); // fire 2+ // Context drops to 30% — above threshold/2 (25%) so no reset+ g.check('a', 0.30); // skip, but no reset+ assert.strictEqual(g.check('a', 0.75), 'refresh', 'fire 3 without reset → REFRESH');+ });++ // ─── remove() cleans up all state ──────────────────────────────────────────++ await test('remove clears pending, cooldown, and fire count', async () => {+ const g = new CompactGate({ enabled: true, threshold: 0.50, cooldownMs: 10_000, refreshAfterFires: 3 });+ g.check('a', 0.75); // pending + fire 1+ g.onCompacted('a'); // cooldown active+ g.remove('a');+ assert.ok(!g.isBlocked('a'), 'not blocked after remove');+ assert.strictEqual(g.check('a', 0.75), 'compact', 'fire 1 again (counter reset by remove)');+ });++ // ─── Summary ───────────────────────────────────────────────────────────────++ console.log(failures === 0 ? '\nall passed' : `\n${failures} failure(s)`);+ process.exit(failures === 0 ? 0 : 1);+})();