@aragon-agent/cli 0.6.14 → 0.6.15

package/dist/compaction/limits.js

@@ -1,172 +1,45 @@
-/**
- * COMPACTION_LIMITS — the single authority on every bound context compaction
- * enforces (context-auto-compaction §5.4).
- *
- * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope
- * (`glyphs.test.ts::inScope`), so no literal in this tree may hold a non-ASCII
- * byte. That regex is a HARDCODED DIRECTORY LIST, which is why adding this tree
- * and adding `compaction` to that list are the SAME change (C-7) - a scanner
- * that silently stops scanning is worse than no scanner. `fast/limits.ts`
- * records the identical trap one feature earlier.
- *
- * TWO KINDS OF NUMBER, AND THEY ARE NOT INTERCHANGEABLE - the distinction
- * `TEAM_LIMITS`, `TODO_LIMITS` and `FAST_LIMITS` all state:
- *
- *  - The entries below are STRUCTURAL. They describe what a digest, a
- *    summarization call and a card can physically carry. A user has no business
- *    tuning them.
- *  - The six `compaction.*` keys in `config/schema.ts` are POLICY: when to fire,
- *    how much to keep, which model, what to do on failure. Those are clamped,
- *    persisted and user-facing.
- */
+/** Structural limits for v2 compaction. All character counts are UTF-16 units. */
 export const COMPACTION_LIMITS = {
-    /** Ceiling on the rendered digest, before the summarizer-window check. ~30k tokens. */
     digestMaxChars: 120_000,
-    /** Output + system prompt + framing, kept out of the digest's share of the window. */
     summarizerReserveTokens: 8_000,
-    // --- Per-message clips in the digest (§3.6.3). ---
-    userChars: 2_000,
-    assistantChars: 2_000,
-    toolArgChars: 200,
-    toolResultChars: 600,
-    /**
-     * Clip bound on the TAGGED text anchor.
-     *
-     * A CLIP, NOT A SHAPE SWITCH (D-21 / P1-9). v1 of the design kept the anchor
-     * verbatim-standalone past this length and merged it into the block below it,
-     * which made the anchor rule LENGTH-DEPENDENT and therefore non-idempotent: on
-     * the second compaction the "first user message" is a summary. A 4 000-character
-     * first message clipped with a visible marker keeps the rule "one leading
-     * anchor, always recognizable"; a 40 000-character first message is not a goal
-     * statement, and truncating it with a marker is the honest outcome.
-     */
-    anchorChars: 4_000,
-    /** What the summarizer prompt asks for, and what the splice clips to. */
-    summaryMaxChars: 6_000,
-    summaryOutputTokens: 2_048,
-    /**
-     * Wall-clock budget for ONE summarization call.
-     *
-     * Longer than the fast reviewer's 20 s because the input is ~30x larger and the
-     * output ~4x larger, and because the cost of a timeout here is a DEGRADED RUN
-     * rather than a missing critique.
-     *
-     * COUPLED TO THE ENGINE'S `COMPACTION_HARD_TIMEOUT_MS` (120 s). The worst legal
-     * host budget is two calls at this value back to back plus the digest render,
-     * so `2 * callTimeoutMs` must stay strictly under the engine's ceiling. Raising
-     * this without raising that makes the §3.7 ladder unreachable and turns every
-     * slow-but-correct summarization into `manager_timeout`.
-     */
+    summaryMaxChars: 32_000,
+    summaryOutputTokens: 4_096,
+    memoryJsonChars: 32_000,
+    memoryEnvelopeChars: 1_024,
+    protectedMemoryChars: 48_000,
+    memoryItems: 200,
+    protectedUserMessages: 200,
+    memoryAdditions: 64,
+    coverageClips: 200,
+    jsonDepth: 32,
+    instructionsChars: 4_000,
+    itemTextChars: 1_200,
+    sourceExcerptChars: 512,
+    itemSources: 8,
+    toolResultEdgeChars: 1_500,
+    operationTimeoutMs: 120_000,
     callTimeoutMs: 45_000,
-    // --- Anti-loop guards (§3.8). ---
-    /** Turns between compactions. Never two in a row: a compaction that just ran
-     *  needs a real turn before its effect is measurable, because `lastUsage` is
-     *  still the pre-compaction number until the next `turn_end`. */
     minTurnsBetween: 2,
-    /** Compactions STARTED per run, both triggers, hard. */
     maxPerRun: 5,
-    /** A splice must project occupancy below `threshold - this`, or it bought two turns. */
     minReclaimRatio: 0.15,
-    /** Consecutive no-progress PRESSURE compactions before the proactive trigger self-disables. */
     stuckLimit: 2,
-    // --- Tail relief (hardening §3.3 / W2). ---
-    /**
-     * Clip bound on an oversized `tool_result` body inside the RETAINED tail.
-     *
-     * 2 000 rather than `toolResultChars`' 600, and the two are not the same
-     * question. That one bounds a message in the DIGEST, which the summarizer
-     * reads once and which exists to be lossy. This one bounds a message the model
-     * keeps WORKING FROM: it is the last two-to-four turns, and the run is about to
-     * continue on them. Relief only ever runs when the alternative is a request the
-     * provider cannot accept.
-     */
+    // Legacy capacity helpers remain callable, but v2 never mutates retained tails.
     tailToolResultChars: 2_000,
-    /**
-     * Room reserved for the `<compacted_context>` block in the tail-budget
-     * projection.
-     *
-     * THE BLOCK IS WRITTEN AFTER THE PROJECTION, which is why this exists at all:
-     * relief measures a spliced history whose summary body is already in it, but
-     * the `plan === null` path measures one where nothing has been written yet, and
-     * a budget with no allowance would let the block push the result back over.
-     */
     blockAllowanceTokens: 2_000,
-    // --- The archive (hardening §3.5 / W4). ---
-    /**
-     * Files kept for ONE `runId`, newest first.
-     *
-     * PER RUN, NOT PER DIRECTORY (RV-6). `<home>/compaction/` is shared by every
-     * `aragon` on the machine — `file-sink.ts:94-95` already treats concurrent
-     * processes as normal — so a global count-based prune would delete a live
-     * session's archives out from under it.
-     */
     archiveMaxFiles: 20,
-    /**
-     * The cross-run sweep: 7 days.
-     *
-     * AGE RATHER THAN COUNT, for the reason above. Age can only ever delete files
-     * whose run finished a week ago; a count can delete the newest file another
-     * process wrote a second ago.
-     */
     archiveMaxAgeMs: 604_800_000,
-    /**
-     * Per-file ceiling before dropped message bodies are clipped from the OLDEST
-     * end. The metadata and the summary are never clipped: a truncated archive
-     * that still says what happened beats none.
-     */
     archiveMaxBytes: 8_000_000,
-    // --- Sub-agent compaction (hardening §3.4 / W3). ---
-    /** A child's `keepRecentTurns`, delivered through its config view. */
     childKeepRecentTurns: 2,
-    /**
-     * A child's guard-2 ceiling, delivered through `Compactor`'s instance bound.
-     *
-     * HERE RATHER THAN AS A `compaction.*` KEY, and the placement is the whole
-     * argument: `maxPerRun` is STRUCTURAL (see this file's header), there is no
-     * config path to it by design, and a child needs a tighter one. Both numbers
-     * therefore stay in the one file that owns structural bounds.
-     */
     childMaxPerRun: 2,
-    /** Rows the collapsed transcript card renders; Ctrl+O expands. */
     cardTextRows: 6,
-    /**
-     * Below this many columns the status chip drops.
-     *
-     * 100, matching all four existing peers - `retry-view.ts`, `fast/limits.ts`,
-     * `team/limits.ts`, `todo/limits.ts` (P2-2). A status-bar degradation ladder
-     * that is nearly-but-not-quite uniform is a reading hazard bought for nothing.
-     * The guaranteed reporting surface is `/compact status`, which is what makes
-     * dropping the chip acceptable at all.
-     */
     statusCompactCols: 100,
 };
-/**
- * Bumped whenever the wording of the `<compacted_context>` block or the
- * summarizer system prompt changes, so a behaviour report can be tied to a block
- * revision with one grep - exactly what `FAST_BLOCK_VERSION` and
- * `TEAM_BLOCK_VERSION` are for.
- */
-export const COMPACTION_BLOCK_VERSION = 'v1-2026-08';
-/** Opening tag of the verbatim goal anchor (§3.6.5). */
+export const COMPACTION_BLOCK_VERSION = 'v2-2026-10';
 export const ANCHOR_TAG_OPEN = '<original_task>';
 export const ANCHOR_TAG_CLOSE = '</original_task>';
-/** Opening tag of the spliced summary block. Recognized on the NEXT compaction. */
 export const BLOCK_TAG_OPEN = '<compacted_context';
 export const BLOCK_TAG_CLOSE = '</compacted_context>';
-/** Marker appended to an anchor clipped at `anchorChars`. ASCII (see the header). */
-export const ANCHOR_TRUNCATION_MARK = ' [truncated]';
-/**
- * What tail relief writes where it removed text (hardening §3.3.2 rule 4).
- *
- * IN THE HISTORY THE MODEL READS, at the exact place the data went missing. A
- * model that sees this knows the output is partial and can re-run the tool; a
- * model handed a silently truncated file cannot tell the difference between "the
- * file ends here" and "the file was cut here".
- *
- * THE HOST OWNS IT, not core: `engine/compaction.ts` has no glyph vocabulary and
- * must not learn one, so `relieveTail` takes this as a callback. ASCII, per this
- * file's header.
- */
+/** Retained legacy helper for explicit callers; v2 compression never clips the tail. */
 export function tailClipMarker(removed) {
     return `\n[... ${removed} characters removed by context compaction ...]`;
 }

package/dist/compaction/memory-identity.d.ts

@@ -0,0 +1,16 @@
+import type { Message } from '@aragon-agent/core';
+export interface CompactionIdentity {
+    version: 1;
+    anchorIndex: 0;
+    blockIndex: 1;
+    generation: number;
+    prefixSha256: string;
+}
+/** Validate the optional session credential shape; throws on unknown or bad fields. */
+export declare function validateCompactionIdentity(value: unknown): asserts value is CompactionIdentity;
+/** Serialize the complete prefix, including content parts and timestamps, in fixed order. */
+export declare function serializeCompactionPrefix(messages: readonly Message[]): string;
+/** Create credentials only at the host's successful adoption boundary. */
+export declare function createCompactionIdentity(messages: readonly Message[]): CompactionIdentity;
+/** Verify persisted credentials without mutating history or repairing missing identity. */
+export declare function verifyCompactionIdentity(messages: readonly Message[], identity: unknown): identity is CompactionIdentity;

package/dist/compaction/memory-identity.js

@@ -0,0 +1,63 @@
+/** Adopted-prefix credentials for process-local and saved-session continuity. */
+import { createHash } from 'node:crypto';
+import { canonicalUserMessage, MemoryError } from './memory.js';
+import { parseCompactedBlock } from './summary-prompt.js';
+/** Validate the optional session credential shape; throws on unknown or bad fields. */
+export function validateCompactionIdentity(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new MemoryError('invalid_prior_memory', '$.identity');
+    }
+    const record = value;
+    const keys = ['version', 'anchorIndex', 'blockIndex', 'generation', 'prefixSha256'];
+    if (Object.keys(record).length !== keys.length ||
+        Object.keys(record).some((key) => !keys.includes(key))) {
+        throw new MemoryError('invalid_prior_memory', '$.identity.keys');
+    }
+    if (record.version !== 1 || record.anchorIndex !== 0 || record.blockIndex !== 1) {
+        throw new MemoryError('invalid_prior_memory', '$.identity.prefix');
+    }
+    if (!Number.isSafeInteger(record.generation) || record.generation < 1) {
+        throw new MemoryError('invalid_prior_memory', '$.identity.generation');
+    }
+    if (typeof record.prefixSha256 !== 'string' || !/^[a-f0-9]{64}$/.test(record.prefixSha256)) {
+        throw new MemoryError('invalid_prior_memory', '$.identity.hash');
+    }
+}
+function prefix(messages) {
+    const anchor = messages[0];
+    const block = messages[1];
+    if (anchor?.role !== 'user' || block?.role !== 'user') {
+        throw new MemoryError('invalid_prior_memory', '$.prefix.roles');
+    }
+    return [anchor, block];
+}
+/** Serialize the complete prefix, including content parts and timestamps, in fixed order. */
+export function serializeCompactionPrefix(messages) {
+    return JSON.stringify(prefix(messages).map(canonicalUserMessage));
+}
+/** Create credentials only at the host's successful adoption boundary. */
+export function createCompactionIdentity(messages) {
+    const [, block] = prefix(messages);
+    const { memory } = parseCompactedBlock(block);
+    return {
+        version: 1,
+        anchorIndex: 0,
+        blockIndex: 1,
+        generation: memory.generation,
+        prefixSha256: createHash('sha256').update(serializeCompactionPrefix(messages)).digest('hex'),
+    };
+}
+/** Verify persisted credentials without mutating history or repairing missing identity. */
+export function verifyCompactionIdentity(messages, identity) {
+    try {
+        validateCompactionIdentity(identity);
+        const current = createCompactionIdentity(messages);
+        return current.generation === identity.generation
+            && current.prefixSha256 === identity.prefixSha256;
+    }
+    catch (error) {
+        if (error instanceof MemoryError)
+            return false;
+        throw error;
+    }
+}

package/dist/compaction/memory-input.d.ts

@@ -0,0 +1,25 @@
+/** Prepare protected host input and move multimodal messages behind safe cuts. */
+import { type Message, type UserMessage } from '@aragon-agent/core';
+import { type CompactionMemory, type ProtectedUserMessage } from './memory.js';
+import { type AnchorShape } from './summary-prompt.js';
+import { type CompactionIdentity } from './memory-identity.js';
+export interface PreparedMemoryInput {
+    anchor: UserMessage;
+    anchorShape: AnchorShape;
+    prior?: CompactionMemory;
+    generation: number;
+    originalTaskSourceId: string;
+    userMessages: ProtectedUserMessage[];
+    head: Message[];
+    headStartIndex: number;
+    tail: Message[];
+    cutIndex: number;
+    legacySummary?: string;
+}
+export interface PrepareMemoryOptions {
+    messages: readonly Message[];
+    cutIndex: number;
+    identity?: CompactionIdentity;
+}
+/** Prepare a snapshot without mutation; throws before payment when protection cannot fit. */
+export declare function prepareMemoryInput(options: PrepareMemoryOptions): PreparedMemoryInput;

package/dist/compaction/memory-input.js

@@ -0,0 +1,106 @@
+/** Prepare protected host input and move multimodal messages behind safe cuts. */
+import { findSafeCutIndices } from '@aragon-agent/core';
+import { assertProtectedMemoryBudget, isLegacyMemoryText, MemoryError, } from './memory.js';
+import { parseCompactedBlock } from './summary-prompt.js';
+import { verifyCompactionIdentity } from './memory-identity.js';
+import { COMPACTION_LIMITS as LIMITS } from './limits.js';
+import { buildDigest } from './digest.js';
+function hasImage(message) {
+    return message.role !== 'assistant' && Array.isArray(message.content)
+        && message.content.some((part) => part.type === 'image');
+}
+function protectImages(messages, cutIndex, anchorIndex) {
+    const imageIndex = messages.findIndex((message, index) => index < cutIndex && index !== anchorIndex && hasImage(message));
+    if (imageIndex < 0)
+        return cutIndex;
+    return findSafeCutIndices(messages).filter((index) => index <= imageIndex).at(-1) ?? 0;
+}
+function legacyReference(messages) {
+    // This copy is read-only evidence of lost provenance; all originals stay protected.
+    const blocks = messages.filter(isLegacyMemoryText);
+    return blocks.length
+        ? blocks.map((message) => message.content).join('\n\n')
+        : undefined;
+}
+function preflightBudget(input) {
+    if (input.userMessages.length > LIMITS.protectedUserMessages) {
+        throw new MemoryError('protected_memory_too_large', '$.userMessages');
+    }
+    const { coverage } = buildDigest({
+        head: input.head,
+        generation: input.generation,
+        startIndex: input.headStartIndex,
+    });
+    const clips = [
+        ...(input.prior?.coverage.clippedToolResults ?? []),
+        ...coverage.clippedToolResults,
+    ];
+    if (clips.length > LIMITS.coverageClips) {
+        throw new MemoryError('protected_memory_too_large', '$.coverage');
+    }
+    const minimum = {
+        schemaVersion: 2,
+        generation: input.generation,
+        originalTask: { sourceId: input.originalTaskSourceId, location: 'anchor' },
+        userMessages: input.userMessages,
+        items: input.prior?.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, minimum);
+}
+/** Prepare a snapshot without mutation; throws before payment when protection cannot fit. */
+export function prepareMemoryInput(options) {
+    const { messages, identity } = options;
+    if (identity && !verifyCompactionIdentity(messages, identity)) {
+        throw new MemoryError('invalid_prior_memory', '$.identity');
+    }
+    const parsed = identity ? parseCompactedBlock(messages[1]) : undefined;
+    const prior = parsed?.memory;
+    const anchorIndex = identity ? 0 : messages.findIndex((message) => message.role === 'user');
+    const anchor = messages[anchorIndex];
+    if (anchor?.role !== 'user')
+        throw new MemoryError('nothing_to_drop', '$.anchor');
+    if (!Number.isSafeInteger(options.cutIndex) ||
+        !findSafeCutIndices(messages).includes(options.cutIndex)) {
+        throw new MemoryError('invalid_history', '$.cutIndex');
+    }
+    const generation = (prior?.generation ?? 0) + 1;
+    if (!Number.isSafeInteger(generation)) {
+        throw new MemoryError('invalid_prior_memory', '$.generation');
+    }
+    const cutIndex = protectImages(messages, options.cutIndex, anchorIndex);
+    const headStartIndex = identity ? 2 : anchorIndex + 1;
+    // Core histories normally start with a user; never silently discard a preceding message.
+    if (anchorIndex !== 0)
+        throw new MemoryError('invalid_history', '$.anchorIndex');
+    if (cutIndex <= headStartIndex) {
+        throw new MemoryError(cutIndex < options.cutIndex ? 'protected_multimodal_tail' : 'nothing_to_drop', '$.cutIndex');
+    }
+    const userMessages = [...(prior?.userMessages ?? [])];
+    for (let index = headStartIndex; index < cutIndex; index += 1) {
+        const message = messages[index];
+        if (message.role === 'user')
+            userMessages.push({ id: `g${generation}:m${index}`, message });
+    }
+    const input = {
+        anchor,
+        anchorShape: parsed?.anchor ?? 'verbatim',
+        ...(prior ? { prior } : {}),
+        generation,
+        originalTaskSourceId: prior?.originalTask.sourceId ?? `g${generation}:m${anchorIndex}`,
+        userMessages,
+        head: messages.slice(headStartIndex, cutIndex),
+        headStartIndex,
+        tail: messages.slice(cutIndex),
+        cutIndex,
+        legacySummary: prior?.legacySummary
+            ?? (!identity ? legacyReference(messages.slice(0, cutIndex)) : undefined),
+    };
+    preflightBudget(input);
+    return input;
+}

package/dist/compaction/memory-render.d.ts

@@ -0,0 +1,4 @@
+/** Human-readable views; never the authoritative serialized working memory. */
+import type { CompactionMemory } from './memory.js';
+/** Render fixed sections and active chain tails, retaining full chains in JSON only. */
+export declare function renderMemoryMarkdown(memory: CompactionMemory): string;

package/dist/compaction/memory-render.js

@@ -0,0 +1,47 @@
+function itemText(item) {
+    const status = item.status ? `[${item.status}] ` : '';
+    const sources = item.sources
+        .map((source) => `${source.messageId} (${source.role}): ${JSON.stringify(source.excerpt)}`)
+        .join('; ');
+    return `- ${status}${item.text}\n  Sources (model extracted): ${sources}`;
+}
+/** Render fixed sections and active chain tails, retaining full chains in JSON only. */
+export function renderMemoryMarkdown(memory) {
+    const superseded = new Set(memory.items.flatMap((item) => item.supersedes ? [item.supersedes] : []));
+    const active = memory.items.filter((item) => !superseded.has(item.id));
+    const select = (...sections) => active
+        .filter((item) => sections.includes(item.section))
+        .map(itemText)
+        .join('\n');
+    const requirements = memory.userMessages.map((entry) => {
+        const content = entry.message.content;
+        return `- ${entry.id}: ${typeof content === 'string'
+            ? content
+            : content.map((part) => part.type === 'text' ? part.text : '[image retained]').join('\n')}`;
+    }).join('\n');
+    const sections = [
+        ['Goal', `Original task retained verbatim in anchor (${memory.originalTask.sourceId}).`],
+        ['User requirements', requirements],
+        ['Global context', select('global')],
+        ['Decisions', select('decisions')],
+        ['Files and facts', select('files', 'facts')],
+        ['Tasks', select('tasks')],
+        ['Verification', select('verification')],
+        ['Pitfalls', select('pitfalls')],
+        ['Next steps', select('next')],
+        [
+            'Coverage',
+            `Generation: ${memory.generation}`
+                + `\nSummarized messages: ${memory.coverage.summarizedMessages}`
+                + `\nClipped tool results: ${memory.coverage.clippedToolResults.length}`
+                + `\nLegacy incomplete: ${memory.coverage.legacyIncomplete}`
+                + memory.coverage.clippedToolResults
+                    .map((clip) => `\n- ${clip.messageId}: ${clip.omittedChars} characters omitted`)
+                    .join('')
+                + (memory.legacySummary
+                    ? `\n\nLegacy reference (unverified):\n${memory.legacySummary}`
+                    : ''),
+        ],
+    ];
+    return sections.map(([title, body]) => `## ${title}\n${body || '(none)'}`).join('\n\n');
+}

package/dist/compaction/memory-validation.d.ts

@@ -0,0 +1,21 @@
+/** Bounded syntax, schema and evidence checks for untrusted memory input. */
+import type { CompactionMemory, MemoryDelta, MemorySource } from './memory.js';
+/** Stable failure reason and short field path; never includes protected content. */
+export declare class MemoryError extends Error {
+    readonly reason: string;
+    readonly path: string;
+    constructor(reason: string, path?: string);
+}
+/** Parse bounded JSON, rejecting duplicate decoded keys before JSON.parse. */
+export declare function parseStrictJson(text: string): unknown;
+/** Validate the model-owned schema only; throws MemoryError on invalid fields. */
+export declare function validateDeltaSchema(value: unknown): asserts value is MemoryDelta;
+/** Validate a persisted v2 body, including unique IDs and acyclic state chains. */
+export declare function validateMemorySchema(value: unknown): asserts value is CompactionMemory;
+export interface DeltaValidationContext {
+    sourceMap: ReadonlyMap<string, MemorySource>;
+    prior?: CompactionMemory;
+    hasSummarizableMessages: boolean;
+}
+/** Check current-source excerpts, completion evidence and append-only supersession. */
+export declare function validateMemoryDelta(delta: MemoryDelta, context: DeltaValidationContext): void;