twinclaw 1.0.0

package/dist/services/browser-service.js

@@ -0,0 +1,334 @@
+import { chromium } from 'playwright-core';
+const SNAPSHOT_CONTEXT_LIMIT = 8;
+const REFERENCE_CANDIDATE_LIMIT = 256;
+const REF_PREFIX = 'ref';
+export class BrowserReferenceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'BrowserReferenceError';
+        this.code = code;
+    }
+}
+function normalizeRole(value) {
+    const normalized = (value ?? '').trim().toLowerCase();
+    return normalized || 'generic';
+}
+function normalizeName(value) {
+    return (value ?? '').replace(/\s+/g, ' ').trim().slice(0, 160);
+}
+function sanitizeSelector(value) {
+    return value.trim();
+}
+function normalizeBounds(bounds) {
+    const normalize = (value) => Number.isFinite(value) ? Math.round(value * 100) / 100 : 0;
+    return {
+        x: normalize(bounds.x),
+        y: normalize(bounds.y),
+        width: Math.max(0, normalize(bounds.width)),
+        height: Math.max(0, normalize(bounds.height)),
+    };
+}
+export function normalizeBrowserReferenceCandidates(candidates) {
+    const deduped = new Map();
+    for (const candidate of candidates) {
+        const selector = sanitizeSelector(candidate.selector);
+        if (!selector) {
+            continue;
+        }
+        const entry = {
+            selector,
+            role: normalizeRole(candidate.role),
+            name: normalizeName(candidate.name),
+            bounds: normalizeBounds(candidate.bounds),
+        };
+        const dedupeKey = [
+            entry.selector,
+            entry.role,
+            entry.name,
+            entry.bounds.x,
+            entry.bounds.y,
+            entry.bounds.width,
+            entry.bounds.height,
+        ].join('|');
+        if (!deduped.has(dedupeKey)) {
+            deduped.set(dedupeKey, entry);
+        }
+    }
+    const sorted = [...deduped.values()].sort((left, right) => left.bounds.y - right.bounds.y ||
+        left.bounds.x - right.bounds.x ||
+        left.selector.localeCompare(right.selector) ||
+        left.role.localeCompare(right.role) ||
+        left.name.localeCompare(right.name));
+    return sorted.map((entry, index) => ({
+        ...entry,
+        ref: `${REF_PREFIX}-${String(index + 1).padStart(3, '0')}`,
+    }));
+}
+export class BrowserService {
+    browser = null;
+    context = null;
+    page = null;
+    snapshotContexts = [];
+    snapshotCounter = 0;
+    async init() {
+        if (!this.browser) {
+            this.browser = await chromium.launch({ headless: true });
+            this.context = await this.browser.newContext();
+            this.page = await this.context.newPage();
+        }
+    }
+    async navigate(url) {
+        if (!this.page)
+            await this.init();
+        await this.page.goto(url, { waitUntil: 'networkidle' });
+    }
+    async getAccessibilityTree() {
+        if (!this.page)
+            await this.init();
+        const bodyLocator = this.page.locator('body');
+        if (typeof bodyLocator.ariaSnapshot === 'function') {
+            return await bodyLocator.ariaSnapshot();
+        }
+        return await this.page.content();
+    }
+    async captureSnapshotReferenceContext() {
+        if (!this.page)
+            await this.init();
+        const rawCandidates = await this.page.evaluate((limit) => {
+            const normalizeText = (value) => {
+                if (typeof value !== 'string') {
+                    return null;
+                }
+                const trimmed = value.replace(/\s+/g, ' ').trim();
+                return trimmed.length > 0 ? trimmed : null;
+            };
+            const inferRole = (element) => {
+                const explicitRole = normalizeText(element.getAttribute('role'));
+                if (explicitRole) {
+                    return explicitRole.toLowerCase();
+                }
+                const tag = element.tagName.toLowerCase();
+                if (tag === 'a' && element.hasAttribute('href'))
+                    return 'link';
+                if (tag === 'button')
+                    return 'button';
+                if (tag === 'select')
+                    return 'combobox';
+                if (tag === 'textarea')
+                    return 'textbox';
+                if (tag === 'summary')
+                    return 'button';
+                if (tag === 'option')
+                    return 'option';
+                if (tag === 'input') {
+                    const inputType = normalizeText(element.getAttribute('type'))?.toLowerCase() ?? 'text';
+                    if (inputType === 'button' || inputType === 'submit' || inputType === 'reset')
+                        return 'button';
+                    if (inputType === 'checkbox')
+                        return 'checkbox';
+                    if (inputType === 'radio')
+                        return 'radio';
+                    if (inputType === 'range')
+                        return 'slider';
+                    if (inputType === 'search')
+                        return 'searchbox';
+                    return 'textbox';
+                }
+                return null;
+            };
+            const inferName = (element) => {
+                const ariaLabel = normalizeText(element.getAttribute('aria-label'));
+                if (ariaLabel)
+                    return ariaLabel;
+                const labelledBy = normalizeText(element.getAttribute('aria-labelledby'));
+                if (labelledBy) {
+                    const label = labelledBy
+                        .split(/\s+/g)
+                        .map((id) => normalizeText(document.getElementById(id)?.textContent))
+                        .filter((value) => !!value)
+                        .join(' ');
+                    if (label) {
+                        return label;
+                    }
+                }
+                const title = normalizeText(element.getAttribute('title'));
+                if (title)
+                    return title;
+                const placeholder = normalizeText(element.getAttribute('placeholder'));
+                if (placeholder)
+                    return placeholder;
+                if (element instanceof HTMLInputElement || element instanceof HTMLTextAreaElement) {
+                    const value = normalizeText(element.value);
+                    if (value)
+                        return value;
+                }
+                return normalizeText(element.textContent);
+            };
+            const isVisible = (element) => {
+                const rect = element.getBoundingClientRect();
+                const style = window.getComputedStyle(element);
+                return (rect.width > 0 &&
+                    rect.height > 0 &&
+                    style.display !== 'none' &&
+                    style.visibility !== 'hidden' &&
+                    style.opacity !== '0');
+            };
+            const cssPath = (element) => {
+                const simpleIdPattern = /^[A-Za-z][A-Za-z0-9\-_:.\u00A0-\uFFFF]*$/;
+                if (element.id && simpleIdPattern.test(element.id)) {
+                    return `#${element.id}`;
+                }
+                const segments = [];
+                let current = element;
+                while (current && current !== document.body) {
+                    const parent = current.parentElement;
+                    const tag = current.tagName.toLowerCase();
+                    if (!parent) {
+                        segments.unshift(tag);
+                        break;
+                    }
+                    const siblings = Array.from(parent.children).filter((child) => child.tagName === current.tagName);
+                    const index = Math.max(1, siblings.indexOf(current) + 1);
+                    segments.unshift(`${tag}:nth-of-type(${index})`);
+                    current = parent;
+                }
+                if (segments.length === 0) {
+                    return 'body';
+                }
+                return `body > ${segments.join(' > ')}`;
+            };
+            const selectors = 'a[href],button,input,select,textarea,[role],summary,[tabindex]';
+            const nodes = Array.from(document.querySelectorAll(selectors));
+            const candidates = [];
+            for (const node of nodes) {
+                if (candidates.length >= limit) {
+                    break;
+                }
+                if (!(node instanceof HTMLElement)) {
+                    continue;
+                }
+                if (!isVisible(node)) {
+                    continue;
+                }
+                const rect = node.getBoundingClientRect();
+                if (rect.width <= 1 || rect.height <= 1) {
+                    continue;
+                }
+                candidates.push({
+                    selector: cssPath(node),
+                    role: inferRole(node),
+                    name: inferName(node),
+                    bounds: {
+                        x: rect.x,
+                        y: rect.y,
+                        width: rect.width,
+                        height: rect.height,
+                    },
+                });
+            }
+            return candidates;
+        }, REFERENCE_CANDIDATE_LIMIT);
+        const references = normalizeBrowserReferenceCandidates(rawCandidates);
+        const snapshotContext = {
+            snapshotId: this.nextSnapshotId(),
+            createdAt: new Date().toISOString(),
+            references,
+        };
+        this.snapshotContexts.push(snapshotContext);
+        if (this.snapshotContexts.length > SNAPSHOT_CONTEXT_LIMIT) {
+            this.snapshotContexts.splice(0, this.snapshotContexts.length - SNAPSHOT_CONTEXT_LIMIT);
+        }
+        return snapshotContext;
+    }
+    async takeScreenshot(path) {
+        if (!this.page)
+            await this.init();
+        await this.page.screenshot({ path });
+    }
+    async takeScreenshotForVlm(filePath, fullPage = true) {
+        if (!this.page)
+            await this.init();
+        await this.page.screenshot({ path: filePath, fullPage });
+        const viewport = this.page.viewportSize() ?? { width: 1280, height: 720 };
+        return {
+            path: filePath,
+            viewport,
+        };
+    }
+    async close() {
+        if (this.browser) {
+            await this.browser.close();
+            this.browser = null;
+            this.context = null;
+            this.page = null;
+            this.snapshotContexts = [];
+            this.snapshotCounter = 0;
+        }
+    }
+    async click(selector) {
+        if (!this.page)
+            await this.init();
+        await this.page.click(selector);
+    }
+    async clickAt(point) {
+        if (!this.page)
+            await this.init();
+        await this.page.mouse.click(point.x, point.y);
+    }
+    async clickByReference(input) {
+        if (!this.page)
+            await this.init();
+        const snapshot = input.snapshotId
+            ? this.snapshotContexts.find((context) => context.snapshotId === input.snapshotId)
+            : this.snapshotContexts.at(-1);
+        if (!snapshot && input.snapshotId) {
+            throw new BrowserReferenceError('snapshot_context_stale', `Snapshot '${input.snapshotId}' is no longer available. Capture a fresh snapshot and retry.`);
+        }
+        if (!snapshot) {
+            throw new BrowserReferenceError('snapshot_context_missing', 'No snapshot reference context is available. Capture /browser/snapshot before clicking by ref.');
+        }
+        const reference = snapshot.references.find((entry) => entry.ref === input.ref);
+        if (!reference) {
+            throw new BrowserReferenceError('reference_not_found', `Reference '${input.ref}' was not found in snapshot '${snapshot.snapshotId}'.`);
+        }
+        try {
+            await this.page.locator(reference.selector).first().click();
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            throw new BrowserReferenceError('reference_unresolved', `Reference '${input.ref}' could not be resolved to a clickable element. ${detail}`);
+        }
+        return {
+            snapshotId: snapshot.snapshotId,
+            reference,
+        };
+    }
+    async clickFromViewportPercentage(xRatio, yRatio) {
+        if (!this.page)
+            await this.init();
+        const viewport = this.page.viewportSize() ?? { width: 1280, height: 720 };
+        const boundedX = Math.max(0, Math.min(1, xRatio));
+        const boundedY = Math.max(0, Math.min(1, yRatio));
+        const point = {
+            x: Math.round(viewport.width * boundedX),
+            y: Math.round(viewport.height * boundedY),
+        };
+        await this.clickAt(point);
+        return point;
+    }
+    async getViewportInfo() {
+        if (!this.page)
+            await this.init();
+        return this.page.viewportSize() ?? { width: 1280, height: 720 };
+    }
+    async type(selector, text) {
+        if (!this.page)
+            await this.init();
+        await this.page.type(selector, text);
+    }
+    nextSnapshotId() {
+        this.snapshotCounter += 1;
+        return `snapshot-${Date.now()}-${String(this.snapshotCounter).padStart(4, '0')}`;
+    }
+}

package/dist/services/context-lifecycle.js

@@ -0,0 +1,314 @@
+import { getConfigValue } from '../config/config-loader.js';
+const CHARS_PER_TOKEN = 4;
+const DEFAULT_CONTEXT_BUDGET_CONFIG = {
+    totalBudgetTokens: 6_000,
+    systemBudgetTokens: 1_800,
+    historyBudgetTokens: 1_600,
+    memoryBudgetTokens: 1_100,
+    delegationBudgetTokens: 900,
+    lifecycleBudgetTokens: 600,
+    hotMessageLimit: 16,
+    warmMessageLimit: 28,
+    memoryTopKMin: 2,
+    memoryTopKMax: 8,
+    tokensPerMemoryItem: 130,
+    maxSummaryEntries: 12,
+    summarySnippetChars: 180,
+};
+export function estimateTokenCount(value) {
+    const normalized = value.trim();
+    if (!normalized) {
+        return 0;
+    }
+    return Math.max(1, Math.ceil(normalized.length / CHARS_PER_TOKEN));
+}
+export function resolveContextBudgetConfig(overrides = {}) {
+    const configured = {
+        totalBudgetTokens: readIntEnv('CONTEXT_BUDGET_TOTAL_TOKENS', DEFAULT_CONTEXT_BUDGET_CONFIG.totalBudgetTokens),
+        systemBudgetTokens: readIntEnv('CONTEXT_BUDGET_SYSTEM_TOKENS', DEFAULT_CONTEXT_BUDGET_CONFIG.systemBudgetTokens),
+        historyBudgetTokens: readIntEnv('CONTEXT_BUDGET_HISTORY_TOKENS', DEFAULT_CONTEXT_BUDGET_CONFIG.historyBudgetTokens),
+        memoryBudgetTokens: readIntEnv('CONTEXT_BUDGET_MEMORY_TOKENS', DEFAULT_CONTEXT_BUDGET_CONFIG.memoryBudgetTokens),
+        delegationBudgetTokens: readIntEnv('CONTEXT_BUDGET_DELEGATION_TOKENS', DEFAULT_CONTEXT_BUDGET_CONFIG.delegationBudgetTokens),
+        lifecycleBudgetTokens: readIntEnv('CONTEXT_BUDGET_LIFECYCLE_TOKENS', DEFAULT_CONTEXT_BUDGET_CONFIG.lifecycleBudgetTokens),
+        hotMessageLimit: readIntEnv('CONTEXT_HOT_MESSAGE_LIMIT', DEFAULT_CONTEXT_BUDGET_CONFIG.hotMessageLimit),
+        warmMessageLimit: readIntEnv('CONTEXT_WARM_MESSAGE_LIMIT', DEFAULT_CONTEXT_BUDGET_CONFIG.warmMessageLimit),
+        memoryTopKMin: readIntEnv('CONTEXT_MEMORY_TOPK_MIN', DEFAULT_CONTEXT_BUDGET_CONFIG.memoryTopKMin),
+        memoryTopKMax: readIntEnv('CONTEXT_MEMORY_TOPK_MAX', DEFAULT_CONTEXT_BUDGET_CONFIG.memoryTopKMax),
+        tokensPerMemoryItem: readIntEnv('CONTEXT_MEMORY_TOKENS_PER_ITEM', DEFAULT_CONTEXT_BUDGET_CONFIG.tokensPerMemoryItem),
+        maxSummaryEntries: readIntEnv('CONTEXT_SUMMARY_MAX_ENTRIES', DEFAULT_CONTEXT_BUDGET_CONFIG.maxSummaryEntries),
+        summarySnippetChars: readIntEnv('CONTEXT_SUMMARY_SNIPPET_CHARS', DEFAULT_CONTEXT_BUDGET_CONFIG.summarySnippetChars),
+    };
+    const merged = {
+        ...DEFAULT_CONTEXT_BUDGET_CONFIG,
+        ...configured,
+        ...overrides,
+    };
+    const memoryTopKMin = Math.max(1, merged.memoryTopKMin);
+    const memoryTopKMax = Math.max(memoryTopKMin, merged.memoryTopKMax);
+    return {
+        ...merged,
+        totalBudgetTokens: Math.max(1_000, merged.totalBudgetTokens),
+        systemBudgetTokens: Math.max(200, merged.systemBudgetTokens),
+        historyBudgetTokens: Math.max(200, merged.historyBudgetTokens),
+        memoryBudgetTokens: Math.max(100, merged.memoryBudgetTokens),
+        delegationBudgetTokens: Math.max(100, merged.delegationBudgetTokens),
+        lifecycleBudgetTokens: Math.max(80, merged.lifecycleBudgetTokens),
+        hotMessageLimit: Math.max(1, merged.hotMessageLimit),
+        warmMessageLimit: Math.max(0, merged.warmMessageLimit),
+        memoryTopKMin,
+        memoryTopKMax,
+        tokensPerMemoryItem: Math.max(20, merged.tokensPerMemoryItem),
+        maxSummaryEntries: Math.max(1, merged.maxSummaryEntries),
+        summarySnippetChars: Math.max(40, merged.summarySnippetChars),
+    };
+}
+export class ContextLifecycleOrchestrator {
+    #config;
+    constructor(overrides = {}) {
+        this.#config = resolveContextBudgetConfig(overrides);
+    }
+    get config() {
+        return this.#config;
+    }
+    estimateTokens(value) {
+        return estimateTokenCount(value);
+    }
+    planHistoryWindow(conversationHistory) {
+        const indexed = conversationHistory.map((message, index) => ({
+            index: index + 1,
+            message,
+        }));
+        const hotStart = Math.max(0, indexed.length - this.#config.hotMessageLimit);
+        const warmStart = Math.max(0, hotStart - this.#config.warmMessageLimit);
+        const hotCandidates = indexed.slice(hotStart);
+        const warmCandidates = indexed.slice(warmStart, hotStart);
+        const archivedCandidates = indexed.slice(0, warmStart);
+        const selectedHot = [];
+        const overflowToWarm = [];
+        let hotTokens = 0;
+        for (let pointer = hotCandidates.length - 1; pointer >= 0; pointer -= 1) {
+            const candidate = hotCandidates[pointer];
+            if (!candidate) {
+                continue;
+            }
+            const candidateTokens = this.#estimateMessageTokens(candidate.message);
+            const withinBudget = hotTokens + candidateTokens <= this.#config.historyBudgetTokens;
+            if (selectedHot.length === 0 || withinBudget) {
+                selectedHot.push(candidate);
+                hotTokens += candidateTokens;
+            }
+            else {
+                overflowToWarm.push(candidate);
+            }
+        }
+        selectedHot.reverse();
+        overflowToWarm.reverse();
+        const warmPool = [...warmCandidates, ...overflowToWarm].sort((a, b) => a.index - b.index);
+        const hotHistory = selectedHot.map((entry) => entry.message);
+        const warmSummary = this.#buildTierSummary('warm', warmPool);
+        const archivedSummary = this.#buildArchivedSummary(archivedCandidates);
+        const unusedHistoryTokens = Math.max(0, this.#config.historyBudgetTokens - hotTokens);
+        const memoryBudgetTokens = this.#config.memoryBudgetTokens + Math.floor(unusedHistoryTokens / 2);
+        const derivedTopK = Math.floor(memoryBudgetTokens / this.#config.tokensPerMemoryItem);
+        const memoryTopK = clamp(derivedTopK, this.#config.memoryTopKMin, this.#config.memoryTopKMax);
+        const diagnostics = [];
+        if (overflowToWarm.length > 0) {
+            diagnostics.push(`Shifted ${overflowToWarm.length} recent message(s) from hot tier to warm summary due to history budget limits.`);
+        }
+        if (archivedCandidates.length > 0) {
+            diagnostics.push(`Archived ${archivedCandidates.length} older message(s) into compact provenance summaries.`);
+        }
+        diagnostics.push(`Adaptive memory retrieval depth selected topK=${memoryTopK} using memory budget ${memoryBudgetTokens} tokens.`);
+        const warmSummaryTokens = this.estimateTokens(warmSummary);
+        const archivedSummaryTokens = this.estimateTokens(archivedSummary);
+        return {
+            hotHistory,
+            warmSummary,
+            archivedSummary,
+            memoryTopK,
+            diagnostics,
+            stats: {
+                totalHistoryMessages: indexed.length,
+                hotMessages: hotHistory.length,
+                warmMessages: warmPool.length,
+                archivedMessages: archivedCandidates.length,
+                hotTokens,
+                warmSummaryTokens,
+                archivedSummaryTokens,
+                historyBudgetTokens: this.#config.historyBudgetTokens,
+                memoryBudgetTokens,
+                memoryTopK,
+                wasCompacted: overflowToWarm.length > 0 || archivedCandidates.length > 0,
+            },
+        };
+    }
+    planRuntimeContext(input) {
+        const memory = this.#compactSection('memory context', input.memoryContext, this.#config.memoryBudgetTokens);
+        const delegation = this.#compactSection('delegation context', input.delegationContext, this.#config.delegationBudgetTokens);
+        const lifecycleBudgetTokens = this.#config.lifecycleBudgetTokens;
+        let warmBudgetTokens = Math.floor(lifecycleBudgetTokens * 0.65);
+        let archivedBudgetTokens = lifecycleBudgetTokens - warmBudgetTokens;
+        if (warmBudgetTokens < 40) {
+            warmBudgetTokens = 40;
+            archivedBudgetTokens = Math.max(0, lifecycleBudgetTokens - warmBudgetTokens);
+        }
+        if (archivedBudgetTokens < 30) {
+            archivedBudgetTokens = Math.min(30, lifecycleBudgetTokens);
+            warmBudgetTokens = Math.max(0, lifecycleBudgetTokens - archivedBudgetTokens);
+        }
+        const warm = this.#compactSection('warm tier summary', input.warmSummary, warmBudgetTokens);
+        const archived = this.#compactSection('archived tier summary', input.archivedSummary, archivedBudgetTokens);
+        const sections = [];
+        if (memory.content) {
+            sections.push(`### RETRIEVED MEMORIES\n${memory.content}`);
+        }
+        if (delegation.content) {
+            sections.push(`### DELEGATION CONTEXT\n${delegation.content}`);
+        }
+        if (warm.content) {
+            sections.push(`### WARM MEMORY SUMMARY\n${warm.content}`);
+        }
+        if (archived.content) {
+            sections.push(`### ARCHIVED MEMORY SUMMARY\n${archived.content}`);
+        }
+        const diagnostics = [memory, delegation, warm, archived]
+            .filter((section) => section.wasCompacted || section.wasOmitted)
+            .map((section) => section.note ?? `${section.label} was compacted.`);
+        const totalTokens = memory.usedTokens + delegation.usedTokens + warm.usedTokens + archived.usedTokens;
+        return {
+            runtimeContext: sections.join('\n\n'),
+            diagnostics,
+            sections: {
+                memory,
+                delegation,
+                warm,
+                archived,
+            },
+            stats: {
+                memoryTokens: memory.usedTokens,
+                delegationTokens: delegation.usedTokens,
+                warmTokens: warm.usedTokens,
+                archivedTokens: archived.usedTokens,
+                totalTokens,
+                wasCompacted: [memory, delegation, warm, archived].some((section) => section.wasCompacted || section.wasOmitted),
+            },
+        };
+    }
+    compactSystemPrompt(systemPrompt) {
+        return this.#compactSection('system prompt', systemPrompt, this.#config.systemBudgetTokens);
+    }
+    #compactSection(label, source, budgetTokens) {
+        const normalized = source.trim();
+        const originalTokens = this.estimateTokens(normalized);
+        if (!normalized || originalTokens === 0) {
+            return {
+                label,
+                content: '',
+                originalTokens: 0,
+                usedTokens: 0,
+                wasCompacted: false,
+                wasOmitted: false,
+            };
+        }
+        if (originalTokens <= budgetTokens) {
+            return {
+                label,
+                content: normalized,
+                originalTokens,
+                usedTokens: originalTokens,
+                wasCompacted: false,
+                wasOmitted: false,
+            };
+        }
+        const budgetChars = Math.max(120, budgetTokens * CHARS_PER_TOKEN);
+        if (budgetChars < 160) {
+            const omitted = `[${label} omitted: insufficient budget (${budgetTokens} tokens).]`;
+            return {
+                label,
+                content: omitted,
+                originalTokens,
+                usedTokens: this.estimateTokens(omitted),
+                wasCompacted: true,
+                wasOmitted: true,
+                note: `${label} omitted because budget ${budgetTokens} tokens was below safe compaction threshold.`,
+            };
+        }
+        const headChars = Math.max(48, Math.floor(budgetChars * 0.72));
+        const tailChars = Math.max(32, Math.floor(budgetChars * 0.18));
+        const head = normalized.slice(0, headChars).trimEnd();
+        const tail = normalized.slice(-tailChars).trimStart();
+        const compacted = `${head}\n...[${label} compacted ${originalTokens}→~${budgetTokens} tokens]...\n${tail}`;
+        return {
+            label,
+            content: compacted,
+            originalTokens,
+            usedTokens: this.estimateTokens(compacted),
+            wasCompacted: true,
+            wasOmitted: false,
+            note: `${label} compacted from ${originalTokens} tokens to fit budget ${budgetTokens}.`,
+        };
+    }
+    #buildTierSummary(label, entries) {
+        if (entries.length === 0) {
+            return '';
+        }
+        const selected = entries.slice(-this.#config.maxSummaryEntries);
+        const omittedCount = Math.max(0, entries.length - selected.length);
+        const lines = selected.map((entry) => {
+            const role = entry.message.role.toUpperCase();
+            const snippet = this.#snippet(entry.message.content ?? '[no text]');
+            return `- [#${entry.index}] ${role}: ${snippet}`;
+        });
+        if (omittedCount > 0) {
+            lines.unshift(`- ${omittedCount} additional ${label} turn(s) omitted for compactness.`);
+        }
+        return [`${label.toUpperCase()} tier summary (${entries.length} turn(s))`, ...lines].join('\n');
+    }
+    #buildArchivedSummary(entries) {
+        if (entries.length === 0) {
+            return '';
+        }
+        const head = entries.slice(0, Math.min(2, entries.length));
+        const tail = entries.slice(Math.max(2, entries.length - 2));
+        const sampled = [...head, ...tail]
+            .sort((a, b) => a.index - b.index)
+            .filter((entry, index, arr) => index === 0 || arr[index - 1]?.index !== entry.index);
+        const lines = sampled.map((entry) => {
+            const role = entry.message.role.toUpperCase();
+            const snippet = this.#snippet(entry.message.content ?? '[no text]');
+            return `- [#${entry.index}] ${role}: ${snippet}`;
+        });
+        return [
+            `ARCHIVED tier summary (${entries.length} turn(s) outside hot/warm retention windows)`,
+            ...lines,
+        ].join('\n');
+    }
+    #snippet(value) {
+        const normalized = value.replace(/\s+/g, ' ').trim();
+        if (!normalized) {
+            return '[empty]';
+        }
+        if (normalized.length <= this.#config.summarySnippetChars) {
+            return normalized;
+        }
+        return `${normalized.slice(0, this.#config.summarySnippetChars - 3)}...`;
+    }
+    #estimateMessageTokens(message) {
+        const content = message.content ?? '';
+        return this.estimateTokens(`${message.role.toUpperCase()}: ${content}`);
+    }
+}
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, value));
+}
+function readIntEnv(name, fallback) {
+    const raw = getConfigValue(name);
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed)) {
+        return fallback;
+    }
+    return Math.floor(parsed);
+}