freddie 0.0.41

package/skills/software-development/systematic-debugging/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: systematic-debugging
+description: "Apply systematic debugging methodology: reproduction, hypothesis, experiment, root cause, fix verification"
+category: software-development
+---
+
+# Systematic Debugging
+
+Do not guess. Form hypotheses, design experiments, eliminate candidates, converge on root cause through observation.
+
+## The debugging loop
+
+```
+OBSERVE → HYPOTHESISE → EXPERIMENT → ELIMINATE → CONVERGE
+```
+
+Never skip to EXPERIMENT without OBSERVE. Never fix without CONVERGE.
+
+## Phase 1: OBSERVE — reproduce the bug
+
+1. Write a **reproduction recipe** — exact steps, inputs, environment.
+2. Confirm **deterministic** (always fails) vs **intermittent** (% failure rate).
+3. Find the **smallest reproduction** — strip everything not needed to trigger the bug.
+4. Capture: error message, stack trace, logs, HTTP request/response, query.
+
+## Phase 2: HYPOTHESISE — list candidate causes
+
+Write every possible cause. Rank by:
+- **Proximity** to the failure point
+- **Recent changes** (last deploy, last config change)
+- **Complexity** (more complex code = more places to hide bugs)
+
+## Phase 3: EXPERIMENT — test one hypothesis at a time
+
+```
+Hypothesis: Redis is evicting sessions under memory pressure
+Experiment: redis-cli INFO memory | grep used_memory_human; redis-cli MONITOR | grep DEL
+Expected if TRUE: memory near maxmemory, DEL commands on session keys
+Expected if FALSE: memory headroom, no unexpected DELs
+Result: ...
+```
+
+**Never change two things at once.** One variable per experiment.
+
+## Phase 4: ELIMINATE — cross off falsified hypotheses
+
+- **FALSIFIED** — evidence rules it out
+- **CONFIRMED** — evidence supports it
+- **INCONCLUSIVE** — need more data
+
+Stop when exactly one hypothesis is CONFIRMED and all others FALSIFIED.
+
+## Phase 5: CONVERGE — fix at root cause
+
+1. Write a **failing test** that reproduces the bug.
+2. Implement the fix.
+3. Confirm the test now passes.
+4. Check for **similar bugs** in adjacent code.
+
+## Debugging tools
+
+| Situation | Tool |
+|---|---|
+| Slow code path | Profiler (node --prof, py-spy) |
+| Memory leak | Heap snapshot (Chrome DevTools) |
+| Network issue | tcpdump, curl -v |
+| DB slow query | EXPLAIN ANALYZE |
+| Race condition | Thread sanitiser, stress test |
+| Intermittent failure | Log correlation by request ID |
+
+## Rules
+
+- **Never assume** — every assumption is an untested hypothesis.
+- **Reproduce first** — if you can't reproduce it, say so.
+- **Binary search** — midpoint log to halve the search space.
+- **Read the error message** — 40% of bugs solved this way.
+- **Check recent changes** — `git log --oneline -20` before anything else.
+- **Take notes** — a session without notes wastes the next session.
+
+Describe the bug (symptoms, error, stack trace, recent changes) and I will guide you through systematic diagnosis.

package/src/acp/auth.js

@@ -0,0 +1,21 @@
+import { getAuthStore } from '../auth.js'
+import crypto from 'node:crypto'
+const KEY = 'ACP_SHARED_SECRET'
+export async function getSharedSecret() {
+    if (process.env.ACP_SHARED_SECRET) return process.env.ACP_SHARED_SECRET
+    const stored = await getAuthStore().getCredential(KEY)
+    return stored?.value || null
+}
+export async function setSharedSecret(secret) { return await getAuthStore().setCredential(KEY, secret) }
+export async function rotateSecret() {
+    const fresh = crypto.randomBytes(32).toString('hex')
+    await setSharedSecret(fresh)
+    return fresh
+}
+export async function authenticateRequest(headers) {
+    const expected = await getSharedSecret()
+    if (!expected) return { ok: true, mode: 'open' }
+    const got = headers?.['x-acp-secret'] || headers?.authorization?.replace(/^Bearer\s+/, '')
+    if (got && got.length === expected.length && crypto.timingSafeEqual(Buffer.from(got), Buffer.from(expected))) return { ok: true, mode: 'shared-secret' }
+    return { ok: false, reason: 'invalid or missing ACP secret' }
+}

package/src/acp/entry.js

@@ -0,0 +1,2 @@
+import { startAcpStdio } from './main.js'
+export function entry() { return startAcpStdio() }

package/src/acp/events.js

@@ -0,0 +1,10 @@
+export function emitEvent(send, kind, payload) { send({ jsonrpc: '2.0', method: 'event/' + kind, params: payload }) }
+export const Events = {
+    toolStart: (send, p) => emitEvent(send, 'tool.start', p),
+    toolProgress: (send, p) => emitEvent(send, 'tool.progress', p),
+    toolComplete: (send, p) => emitEvent(send, 'tool.complete', p),
+    messageDelta: (send, p) => emitEvent(send, 'message.delta', p),
+    messageComplete: (send, p) => emitEvent(send, 'message.complete', p),
+    permissionRequest: (send, p) => emitEvent(send, 'permission.request', p),
+    sessionEnded: (send, p) => emitEvent(send, 'session.ended', p),
+}

package/src/acp/main.js

@@ -0,0 +1,8 @@
+import { AcpServer } from './server.js'
+export function startAcpStdio() {
+    const srv = new AcpServer()
+    srv.start()
+    process.on('SIGINT', () => { srv.stop(); process.exit(0) })
+    process.on('SIGTERM', () => { srv.stop(); process.exit(0) })
+    return srv
+}

package/src/acp/permissions.js

@@ -0,0 +1,29 @@
+import { getConfigValue } from '../config.js'
+
+const _allowed = new Map()
+const _denied = new Map()
+
+export function isAlwaysAllow(tool) {
+    const list = getConfigValue('acp.always_allow', []) || []
+    return list.includes(tool)
+}
+export function isAlwaysDeny(tool) {
+    const list = getConfigValue('acp.always_deny', []) || []
+    return list.includes(tool)
+}
+export function rememberAllow(sessionId, tool) {
+    if (!_allowed.has(sessionId)) _allowed.set(sessionId, new Set())
+    _allowed.get(sessionId).add(tool)
+}
+export function rememberDeny(sessionId, tool) {
+    if (!_denied.has(sessionId)) _denied.set(sessionId, new Set())
+    _denied.get(sessionId).add(tool)
+}
+export function checkPermission(sessionId, tool) {
+    if (isAlwaysDeny(tool)) return 'deny'
+    if (isAlwaysAllow(tool)) return 'allow'
+    if (_denied.get(sessionId)?.has(tool)) return 'deny'
+    if (_allowed.get(sessionId)?.has(tool)) return 'allow'
+    return 'ask'
+}
+export function resetForTests() { _allowed.clear(); _denied.clear() }

package/src/acp/server.js

@@ -0,0 +1,84 @@
+import readline from 'node:readline'
+import { EventEmitter } from 'node:events'
+import { registry, discoverBuiltinTools } from '../tools/registry.js'
+import { runTurn } from '../agent/machine.js'
+import { logger } from '../observability/log.js'
+import { Events } from './events.js'
+import { checkPermission, rememberAllow, rememberDeny } from './permissions.js'
+import { AcpSessionManager } from './session.js'
+
+const log = logger('acp')
+
+const CAPABILITIES = {
+    name: 'freddie', version: '0.4.0',
+    methods: ['initialize', 'session.new', 'session.resume', 'session.list', 'session.end', 'prompt.submit', 'tool.list', 'permission.respond', 'shutdown'],
+    events: ['tool.start', 'tool.progress', 'tool.complete', 'message.delta', 'message.complete', 'permission.request', 'session.ended'],
+}
+
+export class AcpServer extends EventEmitter {
+    constructor({ stdin = process.stdin, stdout = process.stdout, callLLM = null } = {}) {
+        super()
+        this.in = stdin; this.out = stdout; this.callLLM = callLLM
+        this.sessions = new AcpSessionManager()
+        this._pendingPerm = new Map()
+    }
+    start() {
+        const rl = readline.createInterface({ input: this.in, crlfDelay: Infinity })
+        rl.on('line', (l) => this.handle(l).catch(e => this.send({ jsonrpc: '2.0', error: { message: String(e) } })))
+        this.rl = rl
+    }
+    stop() { this.rl?.close() }
+    send(o) { this.out.write(JSON.stringify(o) + '\n') }
+    async handle(line) {
+        if (!line.trim()) return
+        let req; try { req = JSON.parse(line) } catch { return this.send({ jsonrpc: '2.0', error: { message: 'invalid json' } }) }
+        const { id, method, params = {} } = req
+        log.info('rpc', { method, id })
+        const fn = METHODS[method]
+        if (!fn) return this.send({ jsonrpc: '2.0', id, error: { code: -32601, message: 'unknown method: ' + method } })
+        try {
+            const result = await fn(this, params)
+            this.send({ jsonrpc: '2.0', id, result })
+        } catch (e) { this.send({ jsonrpc: '2.0', id, error: { message: String(e?.message || e) } }) }
+    }
+    requestPermission(sessionId, tool) {
+        const decided = checkPermission(sessionId, tool)
+        if (decided !== 'ask') return Promise.resolve(decided)
+        return new Promise((resolve) => {
+            const reqId = sessionId + ':' + tool + ':' + Date.now()
+            this._pendingPerm.set(reqId, { resolve, sessionId, tool })
+            Events.permissionRequest((o) => this.send(o), { reqId, sessionId, tool })
+        })
+    }
+}
+
+const METHODS = {
+    initialize: () => CAPABILITIES,
+    'session.new': (srv, params) => srv.sessions.new(params),
+    'session.resume': (srv, { sessionId }) => srv.sessions.resume(sessionId) || (() => { throw new Error('session not found') })(),
+    'session.list': (srv) => srv.sessions.list(),
+    'session.end': (srv, { sessionId }) => { Events.sessionEnded((o) => srv.send(o), { sessionId }); return srv.sessions.end(sessionId) },
+    'tool.list': async () => {
+        await discoverBuiltinTools()
+        return { tools: registry.list().map(t => ({ name: t.name, toolset: t.toolset, schema: t.schema })) }
+    },
+    'permission.respond': (srv, { reqId, decision }) => {
+        const pending = srv._pendingPerm.get(reqId)
+        if (!pending) return { ok: false, error: 'unknown reqId' }
+        srv._pendingPerm.delete(reqId)
+        if (decision === 'allow' || decision === 'always_allow') rememberAllow(pending.sessionId, pending.tool)
+        if (decision === 'deny' || decision === 'always_deny') rememberDeny(pending.sessionId, pending.tool)
+        pending.resolve(decision === 'allow' || decision === 'always_allow' ? 'allow' : 'deny')
+        return { ok: true }
+    },
+    'prompt.submit': async (srv, { sessionId, prompt }) => {
+        if (!srv.sessions.isActive(sessionId)) throw new Error('session not active')
+        srv.sessions.appendUser(sessionId, prompt)
+        Events.messageDelta((o) => srv.send(o), { sessionId, role: 'user', content: prompt })
+        const out = await runTurn({ prompt, callLLM: srv.callLLM })
+        srv.sessions.appendAssistant(sessionId, out.result || '')
+        Events.messageComplete((o) => srv.send(o), { sessionId, role: 'assistant', content: out.result || '' })
+        return { result: out.result, error: out.error, iterations: out.iterations }
+    },
+    shutdown: (srv) => { srv.stop(); return { ok: true } },
+}

package/src/acp/session.js

@@ -0,0 +1,26 @@
+import { createSession, appendMessage, getMessages, listSessions } from '../sessions.js'
+
+export class AcpSessionManager {
+    constructor() { this.active = new Map() }
+    new(opts = {}) {
+        const id = createSession({ platform: 'acp', ...opts })
+        this.active.set(id, { id, created: Date.now(), opts })
+        return { sessionId: id }
+    }
+    resume(sessionId) {
+        const messages = getMessages(sessionId)
+        if (!messages) return null
+        this.active.set(sessionId, { id: sessionId, resumed: Date.now(), messages })
+        return { sessionId, messages }
+    }
+    list() {
+        return { sessions: listSessions(50).filter(s => s.platform === 'acp') }
+    }
+    end(sessionId) {
+        this.active.delete(sessionId)
+        return { ended: sessionId }
+    }
+    appendUser(sessionId, content) { appendMessage(sessionId, { role: 'user', content }) }
+    appendAssistant(sessionId, content) { appendMessage(sessionId, { role: 'assistant', content }) }
+    isActive(sessionId) { return this.active.has(sessionId) }
+}

package/src/acp/tools.js

@@ -0,0 +1,17 @@
+import { registry, discoverBuiltinTools } from '../tools/registry.js'
+import { Events } from './events.js'
+export async function listToolsForAcp() {
+    await discoverBuiltinTools()
+    return registry.list().map(t => ({ name: t.name, toolset: t.toolset, schema: t.schema, requiresEnv: t.requiresEnv || [] }))
+}
+export async function dispatchWithEvents({ name, args, send, sessionId = null }) {
+    Events.toolStart(send, { sessionId, name, args })
+    try {
+        const result = await registry.dispatch(name, args, { sessionId })
+        Events.toolComplete(send, { sessionId, name, result })
+        return { ok: true, result }
+    } catch (e) {
+        Events.toolComplete(send, { sessionId, name, error: String(e?.message || e) })
+        return { ok: false, error: String(e?.message || e) }
+    }
+}

package/src/agent/account_usage.js

@@ -0,0 +1,19 @@
+import { db } from '../db.js'
+
+async function init() {
+    const d = await db()
+    d.exec(`CREATE TABLE IF NOT EXISTS account_usage (id INTEGER PRIMARY KEY AUTOINCREMENT, session_id TEXT, model TEXT, prompt_tokens INTEGER, completion_tokens INTEGER, cost_usd REAL, ts INTEGER NOT NULL)`)
+    return d
+}
+export async function record({ sessionId = null, model, promptTokens = 0, completionTokens = 0, costUsd = 0 } = {}) {
+    (await init()).prepare(`INSERT INTO account_usage (session_id, model, prompt_tokens, completion_tokens, cost_usd, ts) VALUES (?, ?, ?, ?, ?, ?)`).run(sessionId, model, promptTokens, completionTokens, costUsd, Date.now())
+}
+export async function totalForSession(sessionId) {
+    return (await init()).prepare(`SELECT SUM(prompt_tokens) AS prompt, SUM(completion_tokens) AS completion, SUM(cost_usd) AS cost FROM account_usage WHERE session_id = ?`).get(sessionId) || { prompt: 0, completion: 0, cost: 0 }
+}
+export async function totalLifetime() {
+    return (await init()).prepare(`SELECT SUM(prompt_tokens) AS prompt, SUM(completion_tokens) AS completion, SUM(cost_usd) AS cost FROM account_usage`).get() || { prompt: 0, completion: 0, cost: 0 }
+}
+export async function listRecent(limit = 50) {
+    return (await init()).prepare(`SELECT * FROM account_usage ORDER BY id DESC LIMIT ?`).all(limit)
+}

package/src/agent/acptoapi-bridge.js

@@ -0,0 +1,80 @@
+import { logger } from '../observability/log.js'
+
+const log = logger('acptoapi')
+
+export function getAcptoapiUrl() {
+    return process.env.FREDDIE_LLM_URL || 'http://127.0.0.1:4800/v1'
+}
+
+export function getAcptoapiModel() {
+    return process.env.FREDDIE_LLM_MODEL || 'claude/haiku'
+}
+
+export async function callLLM({ messages, tools = [], model } = {}) {
+    const base = getAcptoapiUrl()
+    const useModel = model || getAcptoapiModel()
+    const body = {
+        model: useModel,
+        messages: messages.map(adaptMessage),
+        stream: false,
+        max_tokens: 1024,
+    }
+    if (Array.isArray(tools) && tools.length) body.tools = tools.map(adaptTool)
+    const res = await fetch(base.replace(/\/$/, '') + '/chat/completions', {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', authorization: 'Bearer none' },
+        body: JSON.stringify(body),
+    })
+    if (!res.ok) {
+        const text = await res.text()
+        throw new Error(`acptoapi ${res.status}: ${text.slice(0, 400)}`)
+    }
+    const json = await res.json()
+    log.info('completed', { model: useModel, usage: json.usage })
+    return adaptResponse(json)
+}
+
+function adaptMessage(m) {
+    if (m.role === 'tool') return { role: 'tool', tool_call_id: m.tool_call_id, content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content) }
+    if (m.role === 'assistant' && Array.isArray(m.tool_calls) && m.tool_calls.length) {
+        return {
+            role: 'assistant',
+            content: m.content || '',
+            tool_calls: m.tool_calls.map(tc => ({
+                id: tc.id || tc.tool_call_id,
+                type: 'function',
+                function: { name: tc.name || tc.function?.name, arguments: typeof tc.arguments === 'string' ? tc.arguments : JSON.stringify(tc.arguments || tc.function?.arguments || {}) },
+            })),
+        }
+    }
+    return { role: m.role, content: typeof m.content === 'string' ? m.content : JSON.stringify(m.content) }
+}
+
+function adaptTool(t) {
+    return {
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters || t.input_schema || { type: 'object', properties: {} },
+        },
+    }
+}
+
+function adaptResponse(r) {
+    const choice = r.choices?.[0]?.message || {}
+    const content = typeof choice.content === 'string' ? choice.content : ''
+    const tool_calls = Array.isArray(choice.tool_calls)
+        ? choice.tool_calls.map(tc => ({ id: tc.id, name: tc.function?.name, arguments: tryParseJson(tc.function?.arguments) }))
+        : []
+    return { content, tool_calls, raw: r }
+}
+
+function tryParseJson(s) { try { return typeof s === 'string' ? JSON.parse(s) : (s || {}) } catch { return {} } }
+
+export async function isReachable() {
+    try {
+        const res = await fetch(getAcptoapiUrl().replace(/\/$/, '') + '/models', { headers: { authorization: 'Bearer none' } })
+        return res.ok
+    } catch { return false }
+}

package/src/agent/anthropic_adapter.js

@@ -0,0 +1,10 @@
+import { callLLM as piCallLLM } from './pi-bridge.js'
+import { resolveKey } from './credential_sources.js'
+import { annotateBreakpoints } from './prompt_caching.js'
+export async function chat({ messages, tools = [], model = 'claude-sonnet-4-6', cache = true } = {}) {
+    const k = await resolveKey('anthropic')
+    if (!k.value) throw new Error('ANTHROPIC_API_KEY required (source: ' + k.source + ')')
+    if (!process.env.ANTHROPIC_API_KEY) process.env.ANTHROPIC_API_KEY = k.value
+    return await piCallLLM({ messages: cache ? annotateBreakpoints(messages, { provider: 'anthropic' }) : messages, tools, model, provider: 'anthropic' })
+}
+export const provider = 'anthropic'

package/src/agent/auxiliary_client.js

@@ -0,0 +1,20 @@
+import { resolveKey } from './credential_sources.js'
+import { calculateCost } from './usage_pricing.js'
+import { record as recordUsage } from './account_usage.js'
+import { retryAsync } from './retry_utils.js'
+import { record as recordRateLimit } from './rate_limit_tracker.js'
+export async function call_llm({ messages, model = 'claude-haiku-4-5', provider = 'anthropic', tools = [], max_tokens = 4096, sessionId = null } = {}) {
+    const k = await resolveKey(provider)
+    if (!k.value) throw new Error(provider.toUpperCase() + '_API_KEY required (source: ' + k.source + ')')
+    return await retryAsync(async () => {
+        try {
+            const { callLLM } = await import('./pi-bridge.js')
+            if (!process.env[provider.toUpperCase() + '_API_KEY']) process.env[provider.toUpperCase() + '_API_KEY'] = k.value
+            const out = await callLLM({ messages, tools, model, provider })
+            const usage = out?.raw?.usage || {}
+            const cost = calculateCost({ model, prompt_tokens: usage.input_tokens || 0, completion_tokens: usage.output_tokens || 0 })
+            recordUsage({ sessionId, model, promptTokens: usage.input_tokens || 0, completionTokens: usage.output_tokens || 0, costUsd: cost })
+            return { ...out, usage, cost }
+        } catch (e) { recordRateLimit(provider, e); throw e }
+    }, { attempts: 3, backoff: 250 })
+}

package/src/agent/bedrock_adapter.js

@@ -0,0 +1,11 @@
+import { resolveKey } from './credential_sources.js'
+const REGION = () => process.env.AWS_REGION || 'us-east-1'
+export async function chat({ messages, model = 'anthropic.claude-sonnet-4-v1:0', tools = [] } = {}) {
+    const id = (await resolveKey('aws')).value || process.env.AWS_ACCESS_KEY_ID
+    if (!id) throw new Error('AWS_ACCESS_KEY_ID required for bedrock')
+    const url = 'https://bedrock-runtime.' + REGION() + '.amazonaws.com/model/' + encodeURIComponent(model) + '/invoke'
+    const body = JSON.stringify({ anthropic_version: 'bedrock-2023-05-31', max_tokens: 4096, messages, ...(tools.length ? { tools } : {}) })
+    const r = await fetch(url, { method: 'POST', headers: { authorization: 'AWS4-HMAC-SHA256 ' + (process.env.AWS_SESSION_TOKEN || ''), 'content-type': 'application/json' }, body })
+    return await r.json()
+}
+export const provider = 'bedrock'

package/src/agent/codex_responses_adapter.js

@@ -0,0 +1,10 @@
+import { resolveKey } from './credential_sources.js'
+import { isCodexModel } from '../cli/codex_models.js'
+export async function chat({ input, model = 'o3-mini', tools = [], reasoning_effort = 'medium' } = {}) {
+    const k = await resolveKey('openai')
+    if (!k.value) throw new Error('OPENAI_API_KEY required (source: ' + k.source + ')')
+    if (!isCodexModel(model)) console.warn('[codex_responses] non-codex model: ' + model)
+    const r = await fetch('https://api.openai.com/v1/responses', { method: 'POST', headers: { authorization: 'Bearer ' + k.value, 'content-type': 'application/json' }, body: JSON.stringify({ model, input, ...(tools.length ? { tools } : {}), reasoning: { effort: reasoning_effort } }) })
+    return await r.json()
+}
+export const provider = 'codex_responses'

package/src/agent/compress/compressor.js

@@ -0,0 +1,55 @@
+import { shouldCompress, computeCompressionPlan, MINIMUM_CONTEXT_LENGTH } from './policy.js'
+import { pruneOldToolResults } from './prune.js'
+import { SUMMARY_PREFIX, LEGACY_SUMMARY_PREFIX, SUMMARIZER_SYSTEM_PROMPT, buildSummarizerInput } from './prompt.js'
+import { markFailure, shouldRetry } from './fallback.js'
+import { logger } from '../../observability/log.js'
+
+const log = logger('compressor')
+
+export async function compress({ messages, modelContextLength = MINIMUM_CONTEXT_LENGTH, callLLM, auxModel = null, threshold } = {}) {
+    if (!shouldCompress({ messages, modelContextLength, threshold })) return { compressedMessages: messages, summary: null, didCompress: false, reason: 'below threshold' }
+    if (!shouldRetry()) return { compressedMessages: messages, summary: null, didCompress: false, reason: 'cooldown' }
+    if (typeof callLLM !== 'function') throw new Error('compress: callLLM required')
+
+    const plan = computeCompressionPlan(messages, modelContextLength)
+    if (plan.middle.length === 0) return { compressedMessages: messages, summary: null, didCompress: false, reason: 'no middle' }
+
+    const existing = extractExistingSummary(plan.head)
+    const prunedMiddle = pruneOldToolResults(plan.middle, 0)
+    const summarizerMessages = [
+        { role: 'system', content: SUMMARIZER_SYSTEM_PROMPT },
+        { role: 'user', content: (existing ? `Previous summary:\n${existing}\n\nNew turns to fold in:\n` : '') + buildSummarizerInput(prunedMiddle) },
+    ]
+    let summary
+    try {
+        const out = await callLLM({ messages: summarizerMessages, tools: [], model: auxModel, maxTokens: plan.summaryBudget })
+        summary = (out?.content || '').trim()
+        if (!summary) throw new Error('empty summary')
+    } catch (e) {
+        markFailure()
+        log.error('summarization failed', { err: String(e) })
+        return { compressedMessages: messages, summary: null, didCompress: false, error: String(e) }
+    }
+
+    const headWithoutOldSummary = stripExistingSummary(plan.head)
+    const summaryMsg = { role: 'user', content: `${SUMMARY_PREFIX}\n\n${summary}` }
+    const compressedMessages = [...headWithoutOldSummary, summaryMsg, ...plan.tail]
+    log.info('compressed', { in: messages.length, out: compressedMessages.length, summary_chars: summary.length })
+    return { compressedMessages, summary, didCompress: true, plan }
+}
+
+function extractExistingSummary(head) {
+    for (const m of head) {
+        const c = typeof m.content === 'string' ? m.content : ''
+        if (c.startsWith(SUMMARY_PREFIX)) return c.slice(SUMMARY_PREFIX.length).trim()
+        if (c.startsWith(LEGACY_SUMMARY_PREFIX)) return c.slice(LEGACY_SUMMARY_PREFIX.length).trim()
+    }
+    return null
+}
+
+function stripExistingSummary(head) {
+    return head.filter(m => {
+        const c = typeof m.content === 'string' ? m.content : ''
+        return !c.startsWith(SUMMARY_PREFIX) && !c.startsWith(LEGACY_SUMMARY_PREFIX)
+    })
+}

package/src/agent/compress/fallback.js

@@ -0,0 +1,14 @@
+export const SUMMARY_FAILURE_COOLDOWN_SECONDS = 600
+
+let _lastFailure = null
+
+export function markFailure(now = Date.now()) { _lastFailure = now }
+
+export function shouldRetry(now = Date.now()) {
+    if (_lastFailure === null) return true
+    return (now - _lastFailure) >= SUMMARY_FAILURE_COOLDOWN_SECONDS * 1000
+}
+
+export function clearFailure() { _lastFailure = null }
+
+export function lastFailureAt() { return _lastFailure }

package/src/agent/compress/index.js

@@ -0,0 +1,6 @@
+export { compress } from './compressor.js'
+export { shouldCompress, computeCompressionPlan, COMPRESSION_THRESHOLD, MINIMUM_CONTEXT_LENGTH, SUMMARY_RATIO } from './policy.js'
+export { SUMMARY_PREFIX, LEGACY_SUMMARY_PREFIX, SUMMARIZER_SYSTEM_PROMPT, buildSummarizerInput } from './prompt.js'
+export { pruneOldToolResults, PRUNED_TOOL_PLACEHOLDER } from './prune.js'
+export { estimateMessagesTokens, estimateMessageTokens, contentLengthForBudget, IMAGE_TOKEN_ESTIMATE, CHARS_PER_TOKEN } from './tokens.js'
+export { markFailure, shouldRetry, clearFailure, SUMMARY_FAILURE_COOLDOWN_SECONDS } from './fallback.js'

package/src/agent/compress/policy.js

@@ -0,0 +1,47 @@
+import { estimateMessagesTokens } from './tokens.js'
+
+export const MINIMUM_CONTEXT_LENGTH = 8000
+export const SUMMARY_RATIO = 0.20
+export const MIN_SUMMARY_TOKENS = 2000
+export const SUMMARY_TOKENS_CEILING = 12000
+export const COMPRESSION_THRESHOLD = 0.85
+
+export function shouldCompress({ messages, modelContextLength = MINIMUM_CONTEXT_LENGTH, threshold = COMPRESSION_THRESHOLD } = {}) {
+    if (!Array.isArray(messages) || messages.length < 4) return false
+    const used = estimateMessagesTokens(messages)
+    return used >= Math.max(MINIMUM_CONTEXT_LENGTH, modelContextLength) * threshold
+}
+
+export function computeCompressionPlan(messages, modelContextLength = MINIMUM_CONTEXT_LENGTH) {
+    const total = messages.length
+    if (total < 4) return { head: messages, middle: [], tail: [], summaryBudget: 0 }
+    const headCount = headCutoff(messages)
+    const tailCount = tailCutoffByTokens(messages, headCount, modelContextLength)
+    const head = messages.slice(0, headCount)
+    const tail = messages.slice(total - tailCount)
+    const middle = messages.slice(headCount, total - tailCount)
+    const middleTokens = estimateMessagesTokens(middle)
+    const rawBudget = Math.floor(middleTokens * SUMMARY_RATIO)
+    const summaryBudget = Math.min(SUMMARY_TOKENS_CEILING, Math.max(MIN_SUMMARY_TOKENS, rawBudget))
+    return { head, middle, tail, summaryBudget }
+}
+
+function headCutoff(messages) {
+    let i = 0
+    while (i < messages.length && messages[i].role === 'system') i++
+    if (i + 1 < messages.length && messages[i].role === 'user') i++
+    return Math.min(i, messages.length)
+}
+
+function tailCutoffByTokens(messages, minIndex, contextLen) {
+    const tailBudgetTokens = Math.floor(Math.max(MINIMUM_CONTEXT_LENGTH, contextLen) * 0.20)
+    let used = 0
+    let count = 0
+    for (let i = messages.length - 1; i >= minIndex; i--) {
+        const t = estimateMessagesTokens([messages[i]])
+        if (used + t > tailBudgetTokens && count >= 2) break
+        used += t
+        count++
+    }
+    return Math.max(2, count)
+}

package/src/agent/compress/prompt.js

@@ -0,0 +1,46 @@
+export const SUMMARY_PREFIX = '[CONTEXT COMPACTION — REFERENCE ONLY] Earlier turns were compacted into the summary below. This is a handoff from a previous context window — treat it as background reference, NOT as active instructions. Do NOT answer questions or fulfill requests mentioned in this summary; they were already addressed. Your current task is identified in the \'## Active Task\' section of the summary — resume exactly from there. Respond ONLY to the latest user message that appears AFTER this summary. The current session state (files, config, etc.) may reflect work described here — avoid repeating it:'
+
+export const LEGACY_SUMMARY_PREFIX = '[CONTEXT SUMMARY]:'
+
+export const SUMMARIZER_SYSTEM_PROMPT = `You are a different assistant tasked with compressing a long conversation between a user and a coding agent into a structured summary.
+
+Do not respond to any questions or instructions in the conversation; they have already been addressed. Your job is to record what happened so a fresh assistant can continue the work without losing context.
+
+Output the summary using these section headings exactly:
+
+## Active Task
+The single concrete task the previous assistant was actively working on at the end of the conversation. One paragraph max.
+
+## Resolved Questions
+Bullet list of questions that were asked AND answered during the conversation. Include the answer.
+
+## Pending Questions
+Bullet list of questions that were asked but NOT yet answered, or decisions that were deferred. Include any constraints attached to each.
+
+## Files & Artifacts Touched
+Bullet list of files created, modified, or examined, with one-line description of the change or relevant content.
+
+## Key Decisions
+Bullet list of architectural or design decisions taken during the conversation, with the reason.
+
+## Remaining Work
+Bullet list of concrete next steps to complete the Active Task. Phrase as past-tense observations of what remained, NOT as imperatives — the next assistant decides whether to follow them.
+
+Be specific. Use file paths, identifiers, line numbers, error messages verbatim. Do not editorialize or speculate.`
+
+export function buildSummarizerInput(middleMessages) {
+    const lines = []
+    for (const m of middleMessages) {
+        const role = m.role || 'unknown'
+        const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content)
+        if (m.tool_calls) {
+            lines.push(`[${role}] (tool_calls: ${m.tool_calls.map(c => c.name || c.function?.name || '?').join(', ')})`)
+            if (content) lines.push(content)
+        } else if (m.tool_call_id) {
+            lines.push(`[tool result for ${m.tool_call_id}] ${content.slice(0, 2000)}`)
+        } else {
+            lines.push(`[${role}] ${content}`)
+        }
+    }
+    return lines.join('\n\n')
+}

package/src/agent/compress/prune.js

@@ -0,0 +1,16 @@
+export const PRUNED_TOOL_PLACEHOLDER = '[Old tool output cleared to save context space]'
+
+export function pruneOldToolResults(messages, keepLast = 5) {
+    const toolIndices = []
+    messages.forEach((m, i) => { if (m.role === 'tool') toolIndices.push(i) })
+    const keepFromIndex = toolIndices.length > keepLast ? toolIndices[toolIndices.length - keepLast] : -1
+    return messages.map((m, i) => {
+        if (m.role !== 'tool') return m
+        if (i >= keepFromIndex) return m
+        return { ...m, content: PRUNED_TOOL_PLACEHOLDER }
+    })
+}
+
+export function countToolMessages(messages) {
+    return messages.filter(m => m.role === 'tool').length
+}