@onmars/lunar-agent-claude 0.7.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@onmars/lunar-agent-claude",
-  "version": "0.7.0",
+  "version": "0.9.0",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -12,7 +12,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@onmars/lunar-core": "^0.7.0"
+    "@onmars/lunar-core": "^0.9.0"
   },
   "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/__tests__/token-counter-claude.test.ts

@@ -0,0 +1,211 @@
+import { describe, expect, test } from 'bun:test'
+import { ClaudeTokenCounter } from '../lib/token-counter-claude'
+
+// ─── mock fetch helper ─────────────────────────────────────
+
+interface FakeCall {
+  url: string
+  init: RequestInit
+}
+
+function makeFetch(responses: Array<{ status?: number; body: unknown }>) {
+  const calls: FakeCall[] = []
+  let idx = 0
+  const fetchImpl = (async (input: unknown, init?: RequestInit) => {
+    calls.push({ url: String(input), init: init ?? {} })
+    const resp = responses[Math.min(idx, responses.length - 1)]
+    idx++
+    return new Response(JSON.stringify(resp.body), {
+      status: resp.status ?? 200,
+      headers: { 'content-type': 'application/json' },
+    })
+  }) as unknown as typeof fetch
+  return { fetchImpl, calls }
+}
+
+// ─── tests ─────────────────────────────────────────────────
+
+describe('ClaudeTokenCounter', () => {
+  test('count returns input_tokens from API response', async () => {
+    const { fetchImpl, calls } = makeFetch([{ body: { input_tokens: 12345 } }])
+
+    const counter = new ClaudeTokenCounter({
+      apiKey: 'sk-test',
+      model: 'claude-opus-4-7',
+      fetchImpl,
+    })
+
+    const n = await counter.count([{ role: 'user', content: 'hello world' }])
+    expect(n).toBe(12345)
+    expect(calls).toHaveLength(1)
+
+    // Request shape
+    const init = calls[0].init
+    expect(init.method).toBe('POST')
+    const headers = init.headers as Record<string, string>
+    expect(headers['x-api-key']).toBe('sk-test')
+    expect(headers['anthropic-version']).toBe('2023-06-01')
+    expect(headers['content-type']).toBe('application/json')
+
+    const body = JSON.parse(init.body as string)
+    expect(body.model).toBe('claude-opus-4-7')
+    expect(body.messages).toHaveLength(1)
+  })
+
+  test('cache hit avoids second fetch for identical messages', async () => {
+    const { fetchImpl, calls } = makeFetch([{ body: { input_tokens: 100 } }])
+
+    const counter = new ClaudeTokenCounter({
+      apiKey: 'sk-test',
+      model: 'claude-sonnet-4-6',
+      fetchImpl,
+    })
+
+    const msgs = [{ role: 'user', content: 'hi' }]
+    const a = await counter.count(msgs)
+    const b = await counter.count(msgs)
+
+    expect(a).toBe(100)
+    expect(b).toBe(100)
+    expect(calls).toHaveLength(1)
+    expect(counter.cacheSize()).toBe(1)
+  })
+
+  test('different messages trigger new API call', async () => {
+    const { fetchImpl, calls } = makeFetch([
+      { body: { input_tokens: 10 } },
+      { body: { input_tokens: 20 } },
+    ])
+
+    const counter = new ClaudeTokenCounter({
+      apiKey: 'sk-test',
+      model: 'claude-haiku-4-5',
+      fetchImpl,
+    })
+
+    expect(await counter.count([{ role: 'user', content: 'first' }])).toBe(10)
+    expect(await counter.count([{ role: 'user', content: 'second' }])).toBe(20)
+    expect(calls).toHaveLength(2)
+  })
+
+  test('LRU evicts oldest after 50 unique entries', async () => {
+    // Each call returns a fresh token count. We just care about cache bookkeeping.
+    const { fetchImpl } = makeFetch([{ body: { input_tokens: 1 } }])
+
+    const counter = new ClaudeTokenCounter({
+      apiKey: 'sk-test',
+      model: 'claude-opus-4-7',
+      fetchImpl,
+    })
+
+    for (let i = 0; i < 60; i++) {
+      await counter.count([{ role: 'user', content: `msg-${i}` }])
+    }
+    expect(counter.cacheSize()).toBe(50)
+  })
+
+  test('windowSize returns 200K for standard models', () => {
+    const a = new ClaudeTokenCounter({ apiKey: 'x', model: 'claude-opus-4-7' })
+    expect(a.windowSize()).toBe(200_000)
+
+    const b = new ClaudeTokenCounter({ apiKey: 'x', model: 'claude-sonnet-4-6' })
+    expect(b.windowSize()).toBe(200_000)
+
+    const c = new ClaudeTokenCounter({ apiKey: 'x', model: 'claude-haiku-4-5' })
+    expect(c.windowSize()).toBe(200_000)
+  })
+
+  test('windowSize returns 1M when model ends with [1m]', () => {
+    const counter = new ClaudeTokenCounter({
+      apiKey: 'x',
+      model: 'claude-opus-4-7[1m]',
+    })
+    expect(counter.windowSize()).toBe(1_000_000)
+  })
+
+  test('aliases resolve: opus → claude-opus-4-7', () => {
+    const counter = new ClaudeTokenCounter({ apiKey: 'x', model: 'opus' })
+    expect(counter.windowSize()).toBe(200_000)
+  })
+
+  test('aliases + [1m]: sonnet[1m] → 1M window', () => {
+    const counter = new ClaudeTokenCounter({ apiKey: 'x', model: 'sonnet[1m]' })
+    expect(counter.windowSize()).toBe(1_000_000)
+  })
+
+  test('disabled mode (no apiKey) returns 0 without calling fetch', async () => {
+    let callCount = 0
+    const fetchImpl = (async () => {
+      callCount++
+      return new Response('{}', { status: 200 })
+    }) as unknown as typeof fetch
+
+    const counter = new ClaudeTokenCounter({
+      model: 'claude-opus-4-7',
+      fetchImpl,
+    })
+    expect(counter.isDisabled()).toBe(true)
+
+    const n = await counter.count([{ role: 'user', content: 'hi' }])
+    expect(n).toBe(0)
+    expect(callCount).toBe(0)
+    expect(counter.windowSize()).toBe(200_000)
+  })
+
+  test('empty messages returns 0 without fetching', async () => {
+    let callCount = 0
+    const fetchImpl = (async () => {
+      callCount++
+      return new Response(JSON.stringify({ input_tokens: 999 }), { status: 200 })
+    }) as unknown as typeof fetch
+
+    const counter = new ClaudeTokenCounter({
+      apiKey: 'sk-test',
+      model: 'claude-opus-4-7',
+      fetchImpl,
+    })
+
+    expect(await counter.count([])).toBe(0)
+    expect(callCount).toBe(0)
+  })
+
+  test('non-OK response returns 0 without crashing', async () => {
+    const { fetchImpl } = makeFetch([{ status: 500, body: { error: 'server down' } }])
+    const counter = new ClaudeTokenCounter({
+      apiKey: 'sk-test',
+      model: 'claude-opus-4-7',
+      fetchImpl,
+    })
+    const n = await counter.count([{ role: 'user', content: 'hi' }])
+    expect(n).toBe(0)
+  })
+
+  test('fetch throw is swallowed into 0', async () => {
+    const fetchImpl = (async () => {
+      throw new Error('network failure')
+    }) as unknown as typeof fetch
+
+    const counter = new ClaudeTokenCounter({
+      apiKey: 'sk-test',
+      model: 'claude-opus-4-7',
+      fetchImpl,
+    })
+    const n = await counter.count([{ role: 'user', content: 'hi' }])
+    expect(n).toBe(0)
+  })
+
+  test('context1m flag adds anthropic-beta header', async () => {
+    const { fetchImpl, calls } = makeFetch([{ body: { input_tokens: 7 } }])
+    const counter = new ClaudeTokenCounter({
+      apiKey: 'sk-test',
+      model: 'claude-opus-4-7[1m]',
+      fetchImpl,
+    })
+    await counter.count([{ role: 'user', content: 'hi' }])
+    const headers = calls[0].init.headers as Record<string, string>
+    expect(headers['anthropic-beta']).toBe('context-1m-2025-08-07')
+    // Model sent to API is the alias-resolved, suffix-stripped version
+    const body = JSON.parse(calls[0].init.body as string)
+    expect(body.model).toBe('claude-opus-4-7')
+  })
+})

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,2 +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
+  }
+}

package/src/lib/token-counter-claude.ts

@@ -0,0 +1,212 @@
+/**
+ * ClaudeTokenCounter — concrete TokenCounter implementation backed by
+ * Anthropic's Token Count API (https://docs.anthropic.com/en/api/messages-count-tokens).
+ *
+ * This lives in agent-claude to keep the core package provider-agnostic.
+ * A tiny in-memory LRU cache (50 entries) keeps the same message bundle
+ * from re-hitting the API when the Router checks the ratio repeatedly.
+ *
+ * If the constructor doesn't receive an API key, the counter operates in
+ * disabled mode: `count()` returns 0 and the FlushHook will simply never
+ * see a token-threshold signal above zero.
+ */
+
+import { createHash } from 'node:crypto'
+import { log } from '@onmars/lunar-core'
+import type { CountableMessage, TokenCounter } from '@onmars/lunar-core/lib/token-counter'
+import { resolveModelAlias } from '../adapter'
+
+// ════════════════════════════════════════════════════════════
+// Model → context window mapping (static; single source of truth here)
+// ════════════════════════════════════════════════════════════
+
+const MODEL_WINDOW: Readonly<Record<string, number>> = Object.freeze({
+  'claude-opus-4-7': 200_000,
+  'claude-opus-4-6': 200_000,
+  'claude-sonnet-4-6': 200_000,
+  'claude-sonnet-4-5': 200_000,
+  'claude-haiku-4-5': 200_000,
+})
+
+const ONE_MILLION = 1_000_000
+const DEFAULT_WINDOW = 200_000
+
+// ════════════════════════════════════════════════════════════
+// Tiny LRU (insertion-ordered Map trick — no dep)
+// ════════════════════════════════════════════════════════════
+
+class TinyLRU<V> {
+  private readonly max: number
+  private readonly store = new Map<string, V>()
+
+  constructor(max: number) {
+    this.max = max
+  }
+
+  get(key: string): V | undefined {
+    const v = this.store.get(key)
+    if (v !== undefined) {
+      // refresh recency
+      this.store.delete(key)
+      this.store.set(key, v)
+    }
+    return v
+  }
+
+  set(key: string, value: V): void {
+    if (this.store.has(key)) {
+      this.store.delete(key)
+    } else if (this.store.size >= this.max) {
+      // evict oldest
+      const oldest = this.store.keys().next().value as string | undefined
+      if (oldest !== undefined) this.store.delete(oldest)
+    }
+    this.store.set(key, value)
+  }
+
+  get size(): number {
+    return this.store.size
+  }
+}
+
+// ════════════════════════════════════════════════════════════
+// Public options + types
+// ════════════════════════════════════════════════════════════
+
+export interface ClaudeTokenCounterOptions {
+  /** Anthropic API key. When absent, the counter runs in disabled mode. */
+  apiKey?: string
+  /** Model ID (aliases resolved; accepts "[1m]" suffix for 1M context). */
+  model: string
+  /** Override the endpoint (tests). */
+  endpoint?: string
+  /** Override fetch (tests). */
+  fetchImpl?: typeof fetch
+  /** Anthropic API version header. Defaults to '2023-06-01'. */
+  apiVersion?: string
+}
+
+interface CountTokensResponse {
+  input_tokens: number
+}
+
+// ════════════════════════════════════════════════════════════
+// Implementation
+// ════════════════════════════════════════════════════════════
+
+export class ClaudeTokenCounter implements TokenCounter {
+  private readonly apiKey?: string
+  private readonly model: string
+  private readonly effectiveModel: string
+  private readonly endpoint: string
+  private readonly fetchImpl: typeof fetch
+  private readonly apiVersion: string
+  private readonly context1m: boolean
+  private readonly cache = new TinyLRU<number>(50)
+  private readonly disabled: boolean
+
+  constructor(options: ClaudeTokenCounterOptions) {
+    this.apiKey = options.apiKey
+    this.model = options.model
+    this.context1m = options.model.endsWith('[1m]')
+    const baseModel = this.context1m ? options.model.slice(0, -'[1m]'.length) : options.model
+    this.effectiveModel = resolveModelAlias(baseModel)
+    this.endpoint = options.endpoint ?? 'https://api.anthropic.com/v1/messages/count_tokens'
+    this.fetchImpl = options.fetchImpl ?? fetch
+    this.apiVersion = options.apiVersion ?? '2023-06-01'
+    this.disabled = !this.apiKey
+
+    if (this.disabled) {
+      log.warn(
+        { model: this.effectiveModel },
+        'ClaudeTokenCounter: no ANTHROPIC_API_KEY — token-threshold signals disabled',
+      )
+    }
+  }
+
+  /** Whether this counter is disabled (no API key). */
+  isDisabled(): boolean {
+    return this.disabled
+  }
+
+  async count(messages: CountableMessage[]): Promise<number> {
+    if (this.disabled || messages.length === 0) return 0
+
+    const key = this.cacheKey(messages)
+    const cached = this.cache.get(key)
+    if (cached !== undefined) return cached
+
+    try {
+      const headers: Record<string, string> = {
+        'content-type': 'application/json',
+        'x-api-key': this.apiKey!,
+        'anthropic-version': this.apiVersion,
+      }
+      if (this.context1m) {
+        headers['anthropic-beta'] = 'context-1m-2025-08-07'
+      }
+
+      const body = JSON.stringify({
+        model: this.effectiveModel,
+        messages: normaliseForApi(messages),
+      })
+
+      const res = await this.fetchImpl(this.endpoint, {
+        method: 'POST',
+        headers,
+        body,
+      })
+
+      if (!res.ok) {
+        log.warn(
+          { status: res.status, model: this.effectiveModel },
+          'ClaudeTokenCounter: count_tokens API returned non-OK — treating as 0',
+        )
+        return 0
+      }
+
+      const data = (await res.json()) as CountTokensResponse
+      const tokens = typeof data?.input_tokens === 'number' ? data.input_tokens : 0
+      this.cache.set(key, tokens)
+      return tokens
+    } catch (err) {
+      log.warn(
+        { err: err instanceof Error ? err.message : String(err) },
+        'ClaudeTokenCounter: count_tokens call failed — treating as 0',
+      )
+      return 0
+    }
+  }
+
+  windowSize(): number {
+    const base = MODEL_WINDOW[this.effectiveModel] ?? DEFAULT_WINDOW
+    return this.context1m ? ONE_MILLION : base
+  }
+
+  /** Exposed for tests. */
+  cacheSize(): number {
+    return this.cache.size
+  }
+
+  private cacheKey(messages: CountableMessage[]): string {
+    const serialised = JSON.stringify(messages)
+    return createHash('sha1')
+      .update(
+        this.effectiveModel + '\u0000' + (this.context1m ? '1m' : 'std') + '\u0000' + serialised,
+      )
+      .digest('hex')
+  }
+}
+
+// ════════════════════════════════════════════════════════════
+// Helpers
+// ════════════════════════════════════════════════════════════
+
+function normaliseForApi(messages: CountableMessage[]): Array<{ role: string; content: unknown }> {
+  // Anthropic accepts string or block-array content; we just pass through.
+  // If content is null/undefined, stringify to empty.
+  return messages.map((m) => ({
+    role: m.role,
+    content: m.content == null ? '' : m.content,
+  }))
+}