@onmars/lunar-agent-claude 0.8.0 → 0.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onmars/lunar-agent-claude",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@onmars/lunar-core": "^0.8.0"
+    "@onmars/lunar-core": "^0.9.1"
   },
   "description": "Claude CLI agent adapter for Lunar",
   "author": "onMars Tech",

package/src/__tests__/compaction-bridge.test.ts

@@ -0,0 +1,291 @@
+/**
+ * # ClaudeCompactionBridge — Functional Specification
+ *
+ * Phase 1.5 bridge between Anthropic's Compaction API (and Claude Code
+ * PreCompact hook) and the agnostic FlushHook that lives in
+ * @onmars/lunar-core.
+ *
+ * ## onStreamEvent(event)
+ * Pattern-matches Anthropic streaming events. When a
+ * `content_block_start` event with `content_block.type === 'compaction'`
+ * is seen, emits `{ kind: 'compaction-incoming', source:
+ * 'anthropic-stream', model? }` on the wired FlushHook. Other event
+ * types (including `message_start`, `content_block_delta`, unrelated
+ * blocks) are ignored. `message_start` events are sniffed for the
+ * active model so subsequent compaction signals can be annotated.
+ *
+ * ## handlePreCompactHook(payload)
+ * Public entry point for Claude Code's PreCompact hook. Emits
+ * `{ kind: 'compaction-incoming', source: 'claude-code-hook', model? }`
+ * and returns exit code 0 — the native compaction must never be
+ * blocked. Errors from the FlushHook are swallowed (logged) and still
+ * resolve to 0.
+ *
+ * ## shutdown()
+ * Makes the bridge inert. Subsequent onStreamEvent/handlePreCompactHook
+ * calls are no-ops.
+ *
+ * ## Defensive: missing FlushHook
+ * When constructed with `undefined`, every method is a silent no-op.
+ */
+import { describe, expect, test } from 'bun:test'
+import type { CurationEngine, CurationResult, PressureSignal } from '@onmars/lunar-core'
+import { FlushHook } from '@onmars/lunar-core'
+import {
+  type AnthropicStreamEvent,
+  ClaudeCompactionBridge,
+  type PreCompactPayload,
+} from '../lib/compaction-bridge'
+
+// ─── helpers ────────────────────────────────────────────────
+
+/** Minimal CurationEngine stub that records signals it receives. */
+function makeEngineStub(result?: CurationResult) {
+  const signals: PressureSignal[] = []
+  const stub = {
+    curate: async (ctx: { signal: PressureSignal }) => {
+      signals.push(ctx.signal)
+      return (
+        result ?? {
+          strategy: 'delegate' as const,
+          savedFacts: [],
+          skipped: [],
+          instructionToInject: '[SYSTEM FLUSH] test',
+        }
+      )
+    },
+    signals,
+  } as unknown as CurationEngine & { signals: PressureSignal[] }
+  return stub
+}
+
+function makeFlushHook(): {
+  hook: FlushHook
+  signals: PressureSignal[]
+  engine: CurationEngine & { signals: PressureSignal[] }
+} {
+  const engine = makeEngineStub()
+  const hook = new FlushHook({ curationEngine: engine, cooldownMs: 0, threshold: 0.7 })
+  // Buffer a message so the signal does not get skipped as 'empty-buffer'.
+  hook.pushMessage({ role: 'user', content: 'hello' })
+  return { hook, signals: engine.signals, engine }
+}
+
+/** Wait a tick for fire-and-forget onSignal to flush through. */
+async function flushMicrotasks(ms = 10): Promise<void> {
+  await new Promise<void>((r) => setTimeout(r, ms))
+}
+
+// ─── tests ──────────────────────────────────────────────────
+
+describe('ClaudeCompactionBridge — onStreamEvent', () => {
+  test('emits compaction-incoming when content_block_start.type is compaction', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    // Observe the model from a prior message_start so the signal can
+    // annotate it.
+    bridge.onStreamEvent({
+      type: 'message_start',
+      message: { model: 'claude-opus-4-7' },
+    } satisfies AnthropicStreamEvent)
+
+    bridge.onStreamEvent({
+      type: 'content_block_start',
+      content_block: { type: 'compaction' },
+    } satisfies AnthropicStreamEvent)
+
+    await flushMicrotasks()
+
+    expect(signals).toHaveLength(1)
+    const [signal] = signals
+    expect(signal.kind).toBe('compaction-incoming')
+    if (signal.kind === 'compaction-incoming') {
+      expect(signal.source).toBe('anthropic-stream')
+      expect(signal.model).toBe('claude-opus-4-7')
+    }
+  })
+
+  test('emits signal with undefined model when no message_start was seen', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    bridge.onStreamEvent({
+      type: 'content_block_start',
+      content_block: { type: 'compaction' },
+    })
+
+    await flushMicrotasks()
+
+    expect(signals).toHaveLength(1)
+    const [signal] = signals
+    if (signal.kind === 'compaction-incoming') {
+      expect(signal.model).toBeUndefined()
+    }
+  })
+
+  test('ignores unrelated content_block_start types', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    bridge.onStreamEvent({
+      type: 'content_block_start',
+      content_block: { type: 'text' },
+    })
+    bridge.onStreamEvent({
+      type: 'content_block_start',
+      content_block: { type: 'tool_use' },
+    })
+
+    await flushMicrotasks()
+
+    expect(signals).toHaveLength(0)
+  })
+
+  test('ignores unrelated event types', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    bridge.onStreamEvent({ type: 'message_delta' })
+    bridge.onStreamEvent({ type: 'message_stop' })
+    bridge.onStreamEvent({ type: 'content_block_delta', content_block: { type: 'compaction' } })
+    bridge.onStreamEvent({ type: 'ping' })
+
+    await flushMicrotasks()
+
+    expect(signals).toHaveLength(0)
+  })
+
+  test('ignores malformed events gracefully', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    // None of these should throw; none should emit.
+    bridge.onStreamEvent({ type: 'content_block_start' })
+    bridge.onStreamEvent({ type: 'content_block_start', content_block: { type: '' } })
+    bridge.onStreamEvent({ type: '' })
+
+    await flushMicrotasks()
+
+    expect(signals).toHaveLength(0)
+  })
+
+  test('tracks model across multiple message_start events', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    bridge.onStreamEvent({ type: 'message_start', message: { model: 'claude-sonnet-4-6' } })
+    bridge.onStreamEvent({ type: 'message_start', message: { model: 'claude-opus-4-7' } })
+
+    bridge.onStreamEvent({
+      type: 'content_block_start',
+      content_block: { type: 'compaction' },
+    })
+
+    await flushMicrotasks()
+
+    expect(signals).toHaveLength(1)
+    const [signal] = signals
+    if (signal.kind === 'compaction-incoming') {
+      expect(signal.model).toBe('claude-opus-4-7')
+    }
+  })
+})
+
+describe('ClaudeCompactionBridge — handlePreCompactHook', () => {
+  test('emits compaction-incoming with claude-code-hook source and returns 0', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    const code = await bridge.handlePreCompactHook({
+      model: 'claude-opus-4-7',
+      session_id: 'sess-123',
+    } satisfies PreCompactPayload)
+
+    expect(code).toBe(0)
+    expect(signals).toHaveLength(1)
+    const [signal] = signals
+    expect(signal.kind).toBe('compaction-incoming')
+    if (signal.kind === 'compaction-incoming') {
+      expect(signal.source).toBe('claude-code-hook')
+      expect(signal.model).toBe('claude-opus-4-7')
+    }
+  })
+
+  test('accepts payload without model', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    const code = await bridge.handlePreCompactHook({})
+    expect(code).toBe(0)
+    expect(signals).toHaveLength(1)
+    const [signal] = signals
+    if (signal.kind === 'compaction-incoming') {
+      expect(signal.model).toBeUndefined()
+    }
+  })
+
+  test('returns 0 even when the underlying flush throws', async () => {
+    const { hook } = makeFlushHook()
+    // Monkey-patch onSignal to throw — handlePreCompactHook must still
+    // return 0 so it never blocks the native compaction.
+    const original = hook.onSignal.bind(hook)
+    hook.onSignal = async () => {
+      throw new Error('boom')
+    }
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    const code = await bridge.handlePreCompactHook({ model: 'claude-opus-4-7' })
+    expect(code).toBe(0)
+
+    // Restore to avoid cross-test contamination.
+    hook.onSignal = original
+  })
+})
+
+describe('ClaudeCompactionBridge — shutdown', () => {
+  test('onStreamEvent is a no-op after shutdown', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+
+    bridge.shutdown()
+    expect(bridge.isShutdown).toBe(true)
+
+    bridge.onStreamEvent({
+      type: 'content_block_start',
+      content_block: { type: 'compaction' },
+    })
+
+    await flushMicrotasks()
+    expect(signals).toHaveLength(0)
+  })
+
+  test('handlePreCompactHook returns 0 and emits nothing after shutdown', async () => {
+    const { hook, signals } = makeFlushHook()
+    const bridge = new ClaudeCompactionBridge(hook)
+    bridge.shutdown()
+
+    const code = await bridge.handlePreCompactHook({ model: 'x' })
+    expect(code).toBe(0)
+    expect(signals).toHaveLength(0)
+  })
+})
+
+describe('ClaudeCompactionBridge — defensive (no FlushHook)', () => {
+  test('onStreamEvent is a no-op when constructed without a FlushHook', () => {
+    const bridge = new ClaudeCompactionBridge(undefined)
+
+    expect(() =>
+      bridge.onStreamEvent({
+        type: 'content_block_start',
+        content_block: { type: 'compaction' },
+      }),
+    ).not.toThrow()
+  })
+
+  test('handlePreCompactHook returns 0 when constructed without a FlushHook', async () => {
+    const bridge = new ClaudeCompactionBridge(undefined)
+    const code = await bridge.handlePreCompactHook({ model: 'claude-opus-4-7' })
+    expect(code).toBe(0)
+  })
+})

package/src/adapter.ts

@@ -2,6 +2,7 @@ import type { Agent, AgentEvent, AgentInput, AgentUsage } from '@onmars/lunar-co
 import { log } from '@onmars/lunar-core'
 import type { SecurityConfig } from '@onmars/lunar-core/lib/config-loader'
 import { buildSafeEnv } from '@onmars/lunar-core/lib/security'
+import type { ClaudeCompactionBridge } from './lib/compaction-bridge'
 
 export interface ClaudeAgentOptions {
   /** Agent ID for routing — defaults to 'claude' */
@@ -100,11 +101,29 @@ export class ClaudeAgent implements Agent {
 
   private activeProcess: ReturnType<typeof Bun.spawn> | null = null
 
+  /**
+   * Optional Claude-specific compaction bridge. When set, every parsed
+   * CLI stream event is forwarded so the bridge can emit
+   * `compaction-incoming` pressure signals. The bridge remains fully
+   * opt-in — if unset (or the feature is disabled upstream), the adapter
+   * behaves exactly as before.
+   */
+  private compactionBridge: ClaudeCompactionBridge | undefined
+
   constructor(private options: ClaudeAgentOptions) {
     this.id = options.id ?? 'claude'
     this.name = options.name ?? 'Claude Code (CLI)'
   }
 
+  /**
+   * Inject a compaction bridge after construction. The bridge is
+   * optional and installed post-hoc from `start.ts` because the
+   * FlushHook it wraps is built later in the boot sequence.
+   */
+  setCompactionBridge(bridge: ClaudeCompactionBridge | undefined): void {
+    this.compactionBridge = bridge
+  }
+
   async init(): Promise<void> {
     const binary = this.options.binaryPath ?? 'claude'
 
@@ -389,6 +408,26 @@ export class ClaudeAgent implements Agent {
 
           try {
             const msg: ClaudeJsonMessage = JSON.parse(trimmed)
+
+            // Forward raw stream event to the compaction bridge (if any)
+            // BEFORE we transform into AgentEvents. The bridge does its
+            // own structural matching and ignores unrelated messages.
+            if (this.compactionBridge) {
+              try {
+                this.compactionBridge.onStreamEvent(
+                  msg as unknown as import('./lib/compaction-bridge').AnthropicStreamEvent,
+                )
+              } catch (bridgeErr) {
+                // Bridge failures must never break the stream loop.
+                log.debug(
+                  {
+                    err: bridgeErr instanceof Error ? bridgeErr.message : String(bridgeErr),
+                  },
+                  'Compaction bridge onStreamEvent threw (ignored)',
+                )
+              }
+            }
+
             for (const evt of this.processMessage(msg)) {
               if (evt.type === 'text') hasAssistantText = true
               yield evt

package/src/index.ts

@@ -1,4 +1,9 @@
 export type { ClaudeAgentOptions } from './adapter'
 export { CLAUDE_MODEL_ALIASES, ClaudeAgent, resolveModelAlias } from './adapter'
+export type {
+  AnthropicStreamEvent,
+  PreCompactPayload,
+} from './lib/compaction-bridge'
+export { ClaudeCompactionBridge } from './lib/compaction-bridge'
 export type { ClaudeTokenCounterOptions } from './lib/token-counter-claude'
 export { ClaudeTokenCounter } from './lib/token-counter-claude'

package/src/lib/compaction-bridge.ts

@@ -0,0 +1,182 @@
+/**
+ * ClaudeCompactionBridge — Claude-specific translator between Anthropic's
+ * Compaction API (and Claude Code's PreCompact hook) and the agnostic
+ * `FlushHook` that lives in @onmars/lunar-core.
+ *
+ * Phase 1.5 bridge. Responsibilities:
+ *
+ *   • onStreamEvent(event)       — inspect a Claude stream event. If we
+ *                                  detect a `content_block_start` of
+ *                                  type `compaction` (Anthropic's
+ *                                  Compaction API, beta header
+ *                                  `compact-2026-01-12` with
+ *                                  `pause_after_compaction: true`), emit
+ *                                  a `compaction-incoming` PressureSignal
+ *                                  with source = 'anthropic-stream'.
+ *
+ *   • handlePreCompactHook(p)    — public entry point for Claude Code's
+ *                                  PreCompact hook. Claude Code can be
+ *                                  configured (via settings.json's
+ *                                  hooks.PreCompact) to shell out to a
+ *                                  local endpoint that ultimately calls
+ *                                  this method. Emits the same signal
+ *                                  with source = 'claude-code-hook'.
+ *                                  Returns exit code 0 so the native
+ *                                  compact proceeds unblocked.
+ *
+ *   • shutdown()                 — mark the bridge inert. After shutdown,
+ *                                  further events/hooks are ignored.
+ *
+ * Design constraints:
+ *
+ *   • Zero runtime dependency on @anthropic-ai/sdk. We accept a minimal
+ *     structural `AnthropicStreamEvent` shape so integrators are free to
+ *     feed events from any source (SDK, CLI stream-json, mock tests).
+ *   • No @onmars/lunar-core types leak Anthropic-specific fields upward.
+ *     This file is the only place that knows about Anthropic's
+ *     compaction block shape.
+ *   • Opt-in. If no FlushHook is provided, every method is a no-op.
+ *     Callers should simply skip constructing the bridge when the
+ *     feature is disabled.
+ */
+
+import type { FlushHook } from '@onmars/lunar-core'
+import { log } from '@onmars/lunar-core'
+
+// ════════════════════════════════════════════════════════════
+// Public types — structural, no SDK import required
+// ════════════════════════════════════════════════════════════
+
+/**
+ * Minimal structural shape of an Anthropic streaming event we need to
+ * recognise compaction. Matches the public Messages API streaming
+ * contract (see Anthropic docs). Only the fields we actually inspect
+ * are declared; integrators may feed richer events and we'll ignore
+ * the rest.
+ *
+ * Compaction detection uses the `content_block_start` event whose
+ * `content_block.type === 'compaction'` (Anthropic Compaction API, beta
+ * header `compact-2026-01-12`).
+ */
+export interface AnthropicStreamEvent {
+  type: string
+  /** Present on content_block_start / content_block_delta events. */
+  content_block?: {
+    type: string
+    [key: string]: unknown
+  }
+  /** Present on message_start — we use it to annotate the signal. */
+  message?: {
+    model?: string
+    [key: string]: unknown
+  }
+  [key: string]: unknown
+}
+
+/**
+ * Payload shape for Claude Code's PreCompact hook. The upstream CLI
+ * currently writes a JSON object on stdin to hook commands; we accept
+ * whatever it provides and only read what we need.
+ */
+export interface PreCompactPayload {
+  /** The model about to compact, if reported. */
+  model?: string
+  /** Optional session identifier for log context. */
+  session_id?: string
+  /** Allow arbitrary additional fields without type loss. */
+  [key: string]: unknown
+}
+
+// ════════════════════════════════════════════════════════════
+// Implementation
+// ════════════════════════════════════════════════════════════
+
+export class ClaudeCompactionBridge {
+  private shutdownRequested = false
+
+  /** Last model seen on a message_start — lets us tag stream signals. */
+  private lastKnownModel: string | undefined
+
+  constructor(private readonly flushHook: FlushHook | undefined) {}
+
+  /**
+   * Feed a single Anthropic stream event to the bridge. The method is
+   * intentionally synchronous and fire-and-forget on the FlushHook side:
+   * we trigger the signal but do not await the flush (callers must not
+   * block the streaming loop).
+   */
+  onStreamEvent(event: AnthropicStreamEvent): void {
+    if (this.shutdownRequested) return
+    if (!this.flushHook) return
+    if (!event || typeof event !== 'object') return
+
+    // Track model from message_start so we can annotate downstream
+    // signals with the active model id.
+    if (event.type === 'message_start' && event.message?.model) {
+      this.lastKnownModel = event.message.model
+      return
+    }
+
+    if (event.type !== 'content_block_start') return
+    if (!event.content_block || event.content_block.type !== 'compaction') return
+
+    const model = this.lastKnownModel
+    log.info(
+      { source: 'anthropic-stream', model },
+      'Claude Compaction bridge: compaction block detected in stream',
+    )
+
+    // Fire and forget — the FlushHook is already async-safe internally
+    // and will coalesce concurrent signals.
+    void this.flushHook.onSignal({
+      kind: 'compaction-incoming',
+      source: 'anthropic-stream',
+      model,
+    })
+  }
+
+  /**
+   * Public entry point for Claude Code's PreCompact hook. Intended to
+   * be invoked by whatever process bridges the CLI hook payload into
+   * the Lunar runtime (future: a lightweight HTTP endpoint). Always
+   * returns 0 so the native compaction proceeds unblocked — we are a
+   * last-chance persister, not a gatekeeper.
+   */
+  async handlePreCompactHook(payload: PreCompactPayload): Promise<number> {
+    if (this.shutdownRequested) return 0
+    if (!this.flushHook) return 0
+
+    const model = typeof payload?.model === 'string' ? payload.model : undefined
+    log.info(
+      { source: 'claude-code-hook', model, sessionId: payload?.session_id },
+      'Claude Compaction bridge: PreCompact hook received',
+    )
+
+    try {
+      await this.flushHook.onSignal({
+        kind: 'compaction-incoming',
+        source: 'claude-code-hook',
+        model,
+      })
+    } catch (err) {
+      // Never block the native compaction on our side — log and swallow.
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        'Claude Compaction bridge: PreCompact flush failed (continuing)',
+      )
+    }
+
+    return 0
+  }
+
+  /** Mark the bridge inert. Subsequent events/hooks are no-ops. */
+  shutdown(): void {
+    this.shutdownRequested = true
+    this.lastKnownModel = undefined
+  }
+
+  /** Observability helper — tests and logs only. */
+  get isShutdown(): boolean {
+    return this.shutdownRequested
+  }
+}