@aragon-agent/cli 0.6.13 → 0.6.15

package/dist/compaction/memory-validation.js

@@ -0,0 +1,268 @@
+import { COMPACTION_LIMITS as LIMITS } from './limits.js';
+/** Stable failure reason and short field path; never includes protected content. */
+export class MemoryError extends Error {
+    reason;
+    path;
+    constructor(reason, path = '$') {
+        super(`${reason}: ${path}`);
+        this.reason = reason;
+        this.path = path;
+        this.name = 'MemoryError';
+    }
+}
+function invalid(path) {
+    throw new MemoryError('invalid_memory_delta', path);
+}
+/** Parse bounded JSON, rejecting duplicate decoded keys before JSON.parse. */
+export function parseStrictJson(text) {
+    if (text.length > LIMITS.memoryJsonChars)
+        invalid('$.length');
+    const stack = [];
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (char === '"') {
+            const start = index++;
+            while (index < text.length && text[index] !== '"') {
+                if (text[index] === '\\')
+                    index += 1;
+                index += 1;
+            }
+            if (index >= text.length)
+                invalid('$.string');
+            let after = index + 1;
+            while (/\s/.test(text[after] ?? '') && after < text.length)
+                after += 1;
+            if (text[after] === ':')
+                checkKey(text.slice(start, index + 1), stack.at(-1));
+        }
+        else if (char === '{' || char === '[') {
+            stack.push(char === '{' ? new Set() : null);
+            if (stack.length > LIMITS.jsonDepth)
+                invalid('$.depth');
+        }
+        else if (char === '}' || char === ']') {
+            if (!stack.length)
+                invalid('$.nesting');
+            stack.pop();
+        }
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return invalid('$.json');
+    }
+}
+function checkKey(token, keys) {
+    let key;
+    try {
+        key = JSON.parse(token);
+    }
+    catch {
+        return invalid('$.key');
+    }
+    if (!keys || keys.has(key))
+        invalid('$.duplicate_key');
+    keys.add(key);
+}
+function object(value, required, optional, path) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        invalid(path);
+    const record = value;
+    if (required.some((key) => !Object.hasOwn(record, key)))
+        invalid(path);
+    if (Object.keys(record).some((key) => !required.includes(key) && !optional.includes(key))) {
+        invalid(path);
+    }
+    return record;
+}
+function array(value, max, path) {
+    if (!Array.isArray(value) || value.length > max)
+        invalid(path);
+    return value;
+}
+function string(value, max, path) {
+    if (typeof value !== 'string' || !value.trim() || value.length > max)
+        invalid(path);
+}
+function integer(value, positive, path) {
+    if (!Number.isSafeInteger(value) || value < (positive ? 1 : 0))
+        invalid(path);
+}
+function id(value, kind, path) {
+    string(value, 64, path);
+    const match = new RegExp(`^g([1-9][0-9]*):${kind}([0-9]+)$`).exec(value);
+    if (!match)
+        invalid(path);
+    integer(Number(match[1]), true, path);
+    integer(Number(match[2]), false, path);
+}
+function source(value, path) {
+    const record = object(value, ['messageId', 'role', 'excerpt'], [], path);
+    id(record.messageId, 'm', `${path}.messageId`);
+    if (!['user', 'assistant', 'tool_result'].includes(record.role)) {
+        invalid(`${path}.role`);
+    }
+    string(record.excerpt, LIMITS.sourceExcerptChars, `${path}.excerpt`);
+}
+const SECTIONS = [
+    'global', 'decisions', 'files', 'facts', 'tasks', 'verification', 'pitfalls', 'next',
+];
+const STATUSES = ['pending', 'in_progress', 'blocked', 'done', 'cancelled'];
+function item(value, stored, path) {
+    const record = object(value, ['section', 'text', 'sources', ...(stored ? ['id'] : [])], ['status', 'supersedes'], path);
+    if (stored)
+        id(record.id, 'i', `${path}.id`);
+    if (!SECTIONS.includes(record.section))
+        invalid(`${path}.section`);
+    string(record.text, LIMITS.itemTextChars, `${path}.text`);
+    const sources = array(record.sources, LIMITS.itemSources, `${path}.sources`);
+    if (!sources.length)
+        invalid(`${path}.sources`);
+    sources.forEach((entry, index) => source(entry, `${path}.sources[${index}]`));
+    if (record.section === 'tasks') {
+        if (!STATUSES.includes(record.status))
+            invalid(`${path}.status`);
+    }
+    else if (Object.hasOwn(record, 'status'))
+        invalid(`${path}.status`);
+    if (Object.hasOwn(record, 'supersedes'))
+        id(record.supersedes, 'i', `${path}.supersedes`);
+}
+/** Validate the model-owned schema only; throws MemoryError on invalid fields. */
+export function validateDeltaSchema(value) {
+    const record = object(value, ['schemaVersion', 'additions'], [], '$');
+    if (record.schemaVersion !== 2)
+        invalid('$.schemaVersion');
+    array(record.additions, LIMITS.memoryAdditions, '$.additions').forEach((entry, index) => item(entry, false, `$.additions[${index}]`));
+}
+function protectedUser(value, path) {
+    const entry = object(value, ['id', 'message'], [], path);
+    id(entry.id, 'm', `${path}.id`);
+    const message = object(entry.message, ['role', 'content'], ['timestamp'], `${path}.message`);
+    if (message.role !== 'user')
+        invalid(`${path}.message.role`);
+    if (typeof message.content !== 'string') {
+        // Images must remain in the top-level anchor/tail, never in this ledger.
+        array(message.content, LIMITS.memoryJsonChars, `${path}.content`).forEach((part) => {
+            const record = object(part, ['type', 'text'], [], `${path}.content`);
+            if (record.type !== 'text' || typeof record.text !== 'string')
+                invalid(`${path}.content`);
+        });
+    }
+    if (Object.hasOwn(message, 'timestamp') && !Number.isFinite(message.timestamp)) {
+        invalid(`${path}.timestamp`);
+    }
+}
+function validateCoverage(value) {
+    const coverage = object(value, ['summarizedMessages', 'clippedToolResults', 'legacyIncomplete'], [], '$.coverage');
+    integer(coverage.summarizedMessages, false, '$.coverage.summarizedMessages');
+    if (typeof coverage.legacyIncomplete !== 'boolean')
+        invalid('$.coverage.legacyIncomplete');
+    const seen = new Set();
+    const clips = array(coverage.clippedToolResults, LIMITS.coverageClips, '$.coverage.clippedToolResults');
+    clips.forEach((value) => {
+        const clip = object(value, ['messageId', 'omittedChars'], [], '$.coverage.clip');
+        id(clip.messageId, 'm', '$.coverage.clip.messageId');
+        integer(clip.omittedChars, true, '$.coverage.clip.omittedChars');
+        if (seen.has(clip.messageId))
+            invalid('$.coverage.clip.duplicate');
+        seen.add(clip.messageId);
+    });
+}
+function validateStoredChains(memory) {
+    const entries = new Map();
+    const replaced = new Set();
+    for (const entry of memory.items) {
+        if (entries.has(entry.id) || Number(entry.id.slice(1).split(':')[0]) > memory.generation) {
+            invalid('$.items.id');
+        }
+        if (entry.supersedes) {
+            const previous = entries.get(entry.supersedes);
+            if (!previous || previous.section !== entry.section || replaced.has(previous.id)) {
+                invalid('$.items.supersedes');
+            }
+            replaced.add(previous.id);
+        }
+        entries.set(entry.id, entry);
+    }
+    const users = memory.userMessages.map((entry) => entry.id);
+    if (new Set(users).size !== users.length || users.includes(memory.originalTask.sourceId)) {
+        invalid('$.userMessages.id');
+    }
+    const references = [
+        memory.originalTask.sourceId,
+        ...users,
+        ...memory.items.flatMap((entry) => entry.sources.map((source) => source.messageId)),
+        ...memory.coverage.clippedToolResults.map((clip) => clip.messageId),
+    ];
+    if (references.some((reference) => Number(reference.slice(1).split(':')[0]) > memory.generation)) {
+        invalid('$.sources.generation');
+    }
+}
+/** Validate a persisted v2 body, including unique IDs and acyclic state chains. */
+export function validateMemorySchema(value) {
+    const record = object(value, ['schemaVersion', 'generation', 'originalTask', 'userMessages', 'items', 'coverage'], ['legacySummary'], '$');
+    if (record.schemaVersion !== 2)
+        invalid('$.schemaVersion');
+    integer(record.generation, true, '$.generation');
+    const original = object(record.originalTask, ['sourceId', 'location'], [], '$.originalTask');
+    id(original.sourceId, 'm', '$.originalTask.sourceId');
+    if (original.location !== 'anchor')
+        invalid('$.originalTask.location');
+    array(record.userMessages, LIMITS.protectedUserMessages, '$.userMessages')
+        .forEach((entry, index) => protectedUser(entry, `$.userMessages[${index}]`));
+    array(record.items, LIMITS.memoryItems, '$.items')
+        .forEach((entry, index) => item(entry, true, `$.items[${index}]`));
+    if (Object.hasOwn(record, 'legacySummary')) {
+        string(record.legacySummary, LIMITS.memoryJsonChars, '$.legacySummary');
+    }
+    validateCoverage(record.coverage);
+    validateStoredChains(value);
+}
+function validateSource(reference, sourceMap, path) {
+    const original = sourceMap.get(reference.messageId);
+    if (!original || original.role !== reference.role)
+        invalid(`${path}.role`);
+    if (!original.visibleText.some((text) => text.includes(reference.excerpt))) {
+        invalid(`${path}.excerpt`);
+    }
+    return original;
+}
+function validateEvidence(entry, originals, path) {
+    const hasUser = originals.some((source) => source.role === 'user' && !source.isLegacyReference);
+    const hasToolResult = originals.some((source) => source.role === 'tool_result' && !!source.toolName);
+    const hasTool = originals.some((source) => source.role === 'tool_result' && source.isError !== true && !!source.toolName);
+    if (entry.status === 'done' && !hasUser && !hasTool)
+        invalid(`${path}.done_evidence`);
+    if (entry.status === 'cancelled' && !hasUser)
+        invalid(`${path}.cancelled_evidence`);
+    if (entry.section === 'verification' && !hasToolResult)
+        invalid(`${path}.verification_evidence`);
+    if (entry.supersedes && entry.section === 'global' && !hasUser)
+        invalid(`${path}.user_evidence`);
+    if (entry.status === 'done' && originals.some((source) => source.isError === true)) {
+        invalid(`${path}.failed_evidence`);
+    }
+}
+/** Check current-source excerpts, completion evidence and append-only supersession. */
+export function validateMemoryDelta(delta, context) {
+    validateDeltaSchema(delta);
+    if (!delta.additions.length && context.hasSummarizableMessages) {
+        throw new MemoryError('empty_memory_delta', '$.additions');
+    }
+    const prior = new Map(context.prior?.items.map((entry) => [entry.id, entry]) ?? []);
+    const replaced = new Set(context.prior?.items.flatMap((entry) => entry.supersedes ? [entry.supersedes] : []) ?? []);
+    delta.additions.forEach((entry, index) => {
+        const path = `$.additions[${index}]`;
+        const originals = entry.sources.map((reference) => validateSource(reference, context.sourceMap, `${path}.sources`));
+        validateEvidence(entry, originals, path);
+        if (!entry.supersedes)
+            return;
+        const previous = prior.get(entry.supersedes);
+        if (!previous || previous.section !== entry.section || replaced.has(previous.id)) {
+            invalid(`${path}.supersedes`);
+        }
+        replaced.add(previous.id);
+    });
+}

package/dist/compaction/memory.d.ts

@@ -0,0 +1,79 @@
+/** Host-owned append-only conversation memory; no I/O or model state. */
+import type { Message, UserMessage } from '@aragon-agent/core';
+import type { PreparedMemoryInput } from './memory-input.js';
+export { MemoryError } from './memory-validation.js';
+export interface SourceRef {
+    messageId: string;
+    role: 'user' | 'assistant' | 'tool_result';
+    excerpt: string;
+}
+export interface MemoryItem {
+    id: string;
+    section: 'global' | 'decisions' | 'files' | 'facts' | 'tasks' | 'verification' | 'pitfalls' | 'next';
+    text: string;
+    sources: SourceRef[];
+    status?: 'pending' | 'in_progress' | 'blocked' | 'done' | 'cancelled';
+    supersedes?: string;
+}
+export interface ProtectedUserMessage {
+    id: string;
+    message: UserMessage;
+}
+export interface CompactionMemory {
+    schemaVersion: 2;
+    generation: number;
+    originalTask: {
+        sourceId: string;
+        location: 'anchor';
+    };
+    userMessages: ProtectedUserMessage[];
+    items: MemoryItem[];
+    legacySummary?: string;
+    coverage: {
+        summarizedMessages: number;
+        clippedToolResults: Array<{
+            messageId: string;
+            omittedChars: number;
+        }>;
+        legacyIncomplete: boolean;
+    };
+}
+export interface MemoryDelta {
+    schemaVersion: 2;
+    additions: Array<Omit<MemoryItem, 'id'>>;
+}
+export interface MemorySource {
+    role: Message['role'];
+    visibleText: string[];
+    toolCallId?: string;
+    toolName?: string;
+    isError?: boolean;
+    isLegacyReference?: boolean;
+}
+export interface MemoryCoverage {
+    summarizedMessages: number;
+    clippedToolResults: Array<{
+        messageId: string;
+        omittedChars: number;
+    }>;
+}
+/** Recognize a legacy reference without excluding it from protected user content. */
+export declare function isLegacyMemoryText(message: Message): boolean;
+/** Parse the sole permitted model response; throws MemoryError on invalid input. */
+export declare function parseMemoryDelta(text: string): MemoryDelta;
+/** Parse a complete persisted body without inferring host identity from its shape. */
+export declare function parseMemory(text: string): CompactionMemory;
+/** Canonical UserMessage field order for protected budgets and prefix hashes. */
+export declare function canonicalUserMessage(message: UserMessage): UserMessage;
+/** Serialize fixed schema order and escaped delimiters; throws on final text budget. */
+export declare function serializeMemory(memory: CompactionMemory): string;
+/** Enforce the combined protected budget using complete serialized content. */
+export declare function assertProtectedMemoryBudget(anchor: UserMessage, memory: CompactionMemory): void;
+export interface MergeMemoryInput {
+    input: PreparedMemoryInput;
+    delta: MemoryDelta;
+    sourceMap: ReadonlyMap<string, MemorySource>;
+    coverage: MemoryCoverage;
+}
+/** Create a staged ledger; prior items and users are retained without rewriting. */
+export declare function mergeMemory(options: MergeMemoryInput): CompactionMemory;

package/dist/compaction/memory.js

@@ -0,0 +1,118 @@
+import { COMPACTION_LIMITS as LIMITS } from './limits.js';
+import { MemoryError, parseStrictJson, validateDeltaSchema, validateMemoryDelta, validateMemorySchema, } from './memory-validation.js';
+export { MemoryError } from './memory-validation.js';
+/** Recognize a legacy reference without excluding it from protected user content. */
+export function isLegacyMemoryText(message) {
+    const legacyPattern = new RegExp('^<compacted_context version="v1-2026-08"(?: [a-z]+="[^"]*")*>'
+        + '\\n[\\s\\S]*\\n</compacted_context>$');
+    return message.role === 'user' && typeof message.content === 'string'
+        && legacyPattern.test(message.content);
+}
+/** Parse the sole permitted model response; throws MemoryError on invalid input. */
+export function parseMemoryDelta(text) {
+    const value = parseStrictJson(text);
+    validateDeltaSchema(value);
+    return value;
+}
+/** Parse a complete persisted body without inferring host identity from its shape. */
+export function parseMemory(text) {
+    const value = parseStrictJson(text);
+    validateMemorySchema(value);
+    return value;
+}
+/** Canonical UserMessage field order for protected budgets and prefix hashes. */
+export function canonicalUserMessage(message) {
+    return {
+        role: 'user',
+        content: typeof message.content === 'string'
+            ? message.content
+            : message.content.map((part) => part.type === 'text'
+                ? { type: 'text', text: part.text }
+                : { type: 'image', mediaType: part.mediaType, data: part.data }),
+        ...(message.timestamp !== undefined ? { timestamp: message.timestamp } : {}),
+    };
+}
+/** Serialize fixed schema order and escaped delimiters; throws on final text budget. */
+export function serializeMemory(memory) {
+    validateMemorySchema(memory);
+    const ordered = {
+        schemaVersion: 2,
+        generation: memory.generation,
+        originalTask: { sourceId: memory.originalTask.sourceId, location: 'anchor' },
+        userMessages: memory.userMessages.map((entry) => ({
+            id: entry.id,
+            message: canonicalUserMessage(entry.message),
+        })),
+        items: memory.items.map((entry) => ({
+            id: entry.id,
+            section: entry.section,
+            text: entry.text,
+            sources: entry.sources.map((source) => ({
+                messageId: source.messageId,
+                role: source.role,
+                excerpt: source.excerpt,
+            })),
+            ...(entry.status !== undefined ? { status: entry.status } : {}),
+            ...(entry.supersedes !== undefined ? { supersedes: entry.supersedes } : {}),
+        })),
+        ...(memory.legacySummary !== undefined ? { legacySummary: memory.legacySummary } : {}),
+        coverage: {
+            summarizedMessages: memory.coverage.summarizedMessages,
+            clippedToolResults: memory.coverage.clippedToolResults.map((clip) => ({
+                messageId: clip.messageId,
+                omittedChars: clip.omittedChars,
+            })),
+            legacyIncomplete: memory.coverage.legacyIncomplete,
+        },
+    };
+    const text = JSON.stringify(ordered, null, 2).replace(/</g, '\\u003c').replace(/>/g, '\\u003e');
+    if (text.length > LIMITS.memoryJsonChars) {
+        throw new MemoryError('protected_memory_too_large', '$.serialized');
+    }
+    return text;
+}
+/** Enforce the combined protected budget using complete serialized content. */
+export function assertProtectedMemoryBudget(anchor, memory) {
+    const length = JSON.stringify(canonicalUserMessage(anchor)).length
+        + serializeMemory(memory).length;
+    if (length > LIMITS.protectedMemoryChars) {
+        throw new MemoryError('protected_memory_too_large', '$.anchor');
+    }
+}
+/** Create a staged ledger; prior items and users are retained without rewriting. */
+export function mergeMemory(options) {
+    const { input, delta, sourceMap, coverage } = options;
+    validateMemoryDelta(delta, {
+        sourceMap,
+        prior: input.prior,
+        hasSummarizableMessages: coverage.summarizedMessages > 0,
+    });
+    const items = [
+        ...(input.prior?.items ?? []),
+        ...delta.additions.map((entry, index) => ({ id: `g${input.generation}:i${index}`, ...entry })),
+    ];
+    const clips = [
+        ...(input.prior?.coverage.clippedToolResults ?? []),
+        ...coverage.clippedToolResults,
+    ];
+    if (items.length > LIMITS.memoryItems ||
+        input.userMessages.length > LIMITS.protectedUserMessages ||
+        clips.length > LIMITS.coverageClips) {
+        throw new MemoryError('protected_memory_too_large', '$.counts');
+    }
+    const memory = {
+        schemaVersion: 2,
+        generation: input.generation,
+        originalTask: { sourceId: input.originalTaskSourceId, location: 'anchor' },
+        userMessages: [...input.userMessages],
+        items,
+        ...(input.legacySummary !== undefined ? { legacySummary: input.legacySummary } : {}),
+        coverage: {
+            summarizedMessages: (input.prior?.coverage.summarizedMessages ?? 0) + coverage.summarizedMessages,
+            clippedToolResults: clips,
+            legacyIncomplete: !!input.prior?.coverage.legacyIncomplete || input.legacySummary !== undefined,
+        },
+    };
+    assertProtectedMemoryBudget(input.anchor, memory);
+    return memory;
+}

package/dist/compaction/meter.d.ts

@@ -62,6 +62,7 @@ export interface ContextMeterDeps {
      * measurement, so a live settings edit moves the denominator without a relaunch.
      */
     getWindowOverride(): number | null;
+    getRequestVersion?(): number;
 }
 export type ContextUsageListener = (usage: ContextUsageSnapshot) => void;
 /**
@@ -102,6 +103,13 @@ export declare class ContextMeter {
     private last;
     /** Whether the history has changed since the last measurement. */
     private dirty;
+    private prefixLast;
+    private sampledPrompt;
+    private sampledVersion;
+    private publishedLength;
+    private publishedLast;
+    private publishedPrompt;
+    private publishedVersion;
     constructor(deps: ContextMeterDeps);
     /**
      * Occupancy right now. FOR THE SCREEN.
@@ -130,13 +138,8 @@ export declare class ContextMeter {
     lastPublished(): Pressure | null;
     /** The published projection, or a zeroed one before the first measurement. */
     currentUsage(): ContextUsageSnapshot;
-    /**
-     * Measure with the caller's own authoritative usage. FOR A DECISION POINT.
-     *
-     * `Compactor.shouldCompact` has a `CompactionProbe.lastUsage` the meter may
-     * not have seen yet, so it supplies it rather than trusting the field here.
-     */
-    measureWith(lastUsage: TokenUsage | undefined): Pressure;
+    /** Compatibility reads cannot establish or resurrect a provider sample. */
+    measureWith(_lastUsage: TokenUsage | undefined): Pressure;
     /**
      * `turn_end` - the one moment in the whole flow that is FULLY measured.
      *
@@ -175,13 +178,13 @@ export declare class ContextMeter {
      */
     onHistoryReplaced(): void;
     /**
-     * Only the DENOMINATOR moved (`/model`, a `contextWindow` edit).
+     * Only the denominator moved (window override or model metadata refresh).
      *
      * DELIBERATELY NOT A RESET. The measured base is still a true statement about
      * the history, so throwing it away would trade a correct numerator for a whole
      * history estimate and produce a visible jump on a common operation. The
-     * numerator's calibration is one turn stale until the next `turn_end`
-     * refreshes it, which is the trade this method names (RV-13).
+     * Changing the model connection or request environment requires the deep
+     * invalidation path instead; its measurement is no longer transferable.
      */
     onWindowChanged(): void;
     /**
@@ -234,6 +237,7 @@ export declare class ContextMeter {
      * is cached" cannot drift, which is what makes `lastPublished()` a meaningful
      * answer rather than a stale one.
      */
+    private refreshValidity;
     private measureAndPublish;
     private compute;
     /**