@aragon-agent/cli 0.6.14 → 0.6.16

package/dist/compaction/operation.d.ts

@@ -0,0 +1,18 @@
+/** Local cancellation and deadline ownership, independent of transport cooperation. */
+export declare class CompactionOperation {
+    readonly id: number;
+    private readonly parent;
+    readonly controller: AbortController;
+    readonly deadline: number;
+    private settled;
+    private reason;
+    private readonly onParentAbort;
+    constructor(id: number, parent: AbortSignal, timeoutMs: number);
+    get signal(): AbortSignal;
+    /** Abort is local; a late remote reply never restores ownership. */
+    abort(reason?: string): void;
+    /** One settlement per operation, including rejected or abandoned candidates. */
+    settle(): boolean;
+    /** Race every call locally and attach rejection handling even to late promises. */
+    run<T>(call: () => Promise<T>, timeoutMs: number): Promise<T>;
+}

package/dist/compaction/operation.js

@@ -0,0 +1,68 @@
+/** Local cancellation and deadline ownership, independent of transport cooperation. */
+export class CompactionOperation {
+    id;
+    parent;
+    controller = new AbortController();
+    deadline;
+    settled = false;
+    reason = 'aborted';
+    onParentAbort = () => this.abort();
+    constructor(id, parent, timeoutMs) {
+        this.id = id;
+        this.parent = parent;
+        this.deadline = Date.now() + timeoutMs;
+        parent.addEventListener('abort', this.onParentAbort, { once: true });
+        if (parent.aborted)
+            this.abort();
+    }
+    get signal() { return this.controller.signal; }
+    /** Abort is local; a late remote reply never restores ownership. */
+    abort(reason = 'aborted') {
+        if (this.signal.aborted)
+            return;
+        this.reason = reason;
+        this.controller.abort();
+    }
+    /** One settlement per operation, including rejected or abandoned candidates. */
+    settle() {
+        if (this.settled)
+            return false;
+        this.settled = true;
+        this.parent.removeEventListener('abort', this.onParentAbort);
+        this.abort();
+        return true;
+    }
+    /** Race every call locally and attach rejection handling even to late promises. */
+    async run(call, timeoutMs) {
+        if (this.signal.aborted || this.settled)
+            throw new Error(this.reason);
+        const remaining = Math.min(timeoutMs, this.deadline - Date.now());
+        if (remaining <= 0)
+            throw new Error('timeout');
+        let timer;
+        let onAbort = () => { };
+        const cancelled = new Promise((_, reject) => {
+            onAbort = () => reject(new Error(this.reason));
+            this.signal.addEventListener('abort', onAbort, { once: true });
+            if (this.signal.aborted)
+                onAbort();
+            timer = setTimeout(() => this.abort('timeout'), remaining);
+        });
+        try {
+            if (this.signal.aborted)
+                throw new Error(this.reason);
+            const remote = Promise.resolve().then(() => {
+                if (this.signal.aborted || this.settled)
+                    throw new Error(this.reason);
+                if (Date.now() >= this.deadline)
+                    throw new Error('timeout');
+                return call();
+            });
+            return await Promise.race([remote, cancelled]);
+        }
+        finally {
+            clearTimeout(timer);
+            this.signal.removeEventListener('abort', onAbort);
+        }
+    }
+}

package/dist/compaction/pressure.d.ts

@@ -119,24 +119,9 @@ export declare function isApproximate(p: Pressure): boolean;
  * support thread about a wrong percentage.
  */
 export declare function computePressure(input: PressureInput): Pressure;
-export interface HeadroomRequirement {
-    /** The session's effective output cap for one call. */
+/** Only actual occupancy authorizes automatic compaction. */
+export declare function shouldCompactAt(p: Pressure, threshold: number): boolean;
+/** Capacity helper retained for the standalone tail-budget API, never a trigger. */
+export declare function requiredHeadroom(req: {
     maxOutputTokens: number;
-}
-/**
- * The tokens the NEXT request needs on top of the history.
- *
- * `THINKING_HEADROOM_TOKENS` (4096) and `CONTEXT_SAFETY_MARGIN_TOKENS` (1024) are
- * existing core exports and are reused rather than re-spelled.
- */
-export declare function requiredHeadroom(req: HeadroomRequirement): number;
-/**
- * The trigger, and the second term is not belt-and-braces (D-12).
- *
- * 90 % OF A 200 k WINDOW LEAVES 20 k, WHICH IS PLENTY. 90 % OF A 32 k WINDOW
- * LEAVES 3.2 k, WHICH IS LESS THAN A SINGLE `max_tokens` OF 8192 - the request is
- * already impossible. A pure ratio trigger is therefore correct for the models
- * most users run and quietly wrong for the small ones, and "quietly wrong on the
- * cheap models" is not a property this product ships.
- */
-export declare function shouldCompactAt(p: Pressure, threshold: number, req: HeadroomRequirement): boolean;
+}): number;

package/dist/compaction/pressure.js

@@ -123,9 +123,8 @@ export function computePressure(input) {
         source = 'usage';
     }
     else {
-        // Before the first `turn_end` there is nothing to calibrate against and the
-        // raw estimate is used - still under-reporting, but `requiredHeadroom` below
-        // is the belt for that case and it does not depend on the ratio being right.
+        // Before the first turn_end there is no calibration. Keep the estimate
+        // explicit: output reservations never authorize automatic compaction.
         const raw = estimatePromptTokens(input.messages, input.systemPrompt);
         occupied = raw + (input.estimateOffset ?? 0);
         source = 'estimate';
@@ -147,26 +146,17 @@ export function computePressure(input) {
         deltaTokens,
     };
 }
-/**
- * The tokens the NEXT request needs on top of the history.
- *
- * `THINKING_HEADROOM_TOKENS` (4096) and `CONTEXT_SAFETY_MARGIN_TOKENS` (1024) are
- * existing core exports and are reused rather than re-spelled.
- */
+/** Only actual occupancy authorizes automatic compaction. */
+export function shouldCompactAt(p, threshold) {
+    if (!Number.isFinite(p.occupied) || p.occupied < 0)
+        return false;
+    if (!Number.isFinite(p.contextWindow) || p.contextWindow <= 0)
+        return false;
+    if (!Number.isFinite(threshold) || threshold < 0.5 || threshold > 0.95)
+        return false;
+    return p.occupied / p.contextWindow >= threshold;
+}
+/** Capacity helper retained for the standalone tail-budget API, never a trigger. */
 export function requiredHeadroom(req) {
     return req.maxOutputTokens + THINKING_HEADROOM_TOKENS + CONTEXT_SAFETY_MARGIN_TOKENS;
 }
-/**
- * The trigger, and the second term is not belt-and-braces (D-12).
- *
- * 90 % OF A 200 k WINDOW LEAVES 20 k, WHICH IS PLENTY. 90 % OF A 32 k WINDOW
- * LEAVES 3.2 k, WHICH IS LESS THAN A SINGLE `max_tokens` OF 8192 - the request is
- * already impossible. A pure ratio trigger is therefore correct for the models
- * most users run and quietly wrong for the small ones, and "quietly wrong on the
- * cheap models" is not a property this product ships.
- */
-export function shouldCompactAt(p, threshold, req) {
-    if (p.contextWindow <= 0)
-        return false;
-    return p.ratio >= threshold || p.headroom < requiredHeadroom(req);
-}

package/dist/compaction/summarize-call.d.ts

@@ -1,19 +1,4 @@
-/**
- * The bounded summarization call (context-auto-compaction §3.6.4).
- *
- * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
- *
- * THIS MODULE DOES NOT OWN AN `AbortController`, AND THAT IS A PROHIBITION
- * RATHER THAN AN OVERSIGHT - the identical rule `fast/review-call.ts` records at
- * length, and for the identical reason: the retry layer returns SILENTLY on
- * abort, so a cancellation and a timeout arrive as byte-identical bare `Error`s
- * carrying no `errorType`. Once the controller is private to this module, the
- * caller can no longer stamp WHICH of the two happened, and every cancelled
- * summarization is misreported as a failure.
- *
- * So this module RECEIVES the signal and a timeout callback, and returns an
- * outcome. It does not create, own, or classify the abort.
- */
+/** Bounded summary transport; local cancellation also settles uncooperative providers. */
 import type { AssistantMessage, LLMRequest, ModelRef, TokenUsage } from '@aragon-agent/core';
 /** The assistant text of a completion, or `''` for an answer with no text block. */
 export declare function assistantText(message: AssistantMessage | undefined): string;
@@ -34,6 +19,7 @@ export interface SummarizeRequestParams {
     digest: string;
     instructions?: string;
     hasPriorSummary: boolean;
+    validationError?: string;
     /** Created and owned by the compactor; forwarded into the provider from there. */
     signal: AbortSignal;
     now: number;
@@ -57,6 +43,7 @@ export interface SummarizeCallParams extends SummarizeRequestParams {
      * THE CALLER ABORTS, NOT THIS MODULE. See the file header.
      */
     onTimeout(): void;
+    onUsage?(usage: TokenUsage): void;
 }
 export type SummarizeOutcome = {
     ok: true;

package/dist/compaction/summarize-call.js

@@ -1,21 +1,6 @@
-/**
- * The bounded summarization call (context-auto-compaction §3.6.4).
- *
- * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
- *
- * THIS MODULE DOES NOT OWN AN `AbortController`, AND THAT IS A PROHIBITION
- * RATHER THAN AN OVERSIGHT - the identical rule `fast/review-call.ts` records at
- * length, and for the identical reason: the retry layer returns SILENTLY on
- * abort, so a cancellation and a timeout arrive as byte-identical bare `Error`s
- * carrying no `errorType`. Once the controller is private to this module, the
- * caller can no longer stamp WHICH of the two happened, and every cancelled
- * summarization is misreported as a failure.
- *
- * So this module RECEIVES the signal and a timeout callback, and returns an
- * outcome. It does not create, own, or classify the abort.
- */
 import { COMPACTION_LIMITS } from './limits.js';
 import { buildSummarySystemPrompt, buildSummaryUserMessage } from './summary-prompt.js';
+import { CompactionOperation } from './operation.js';
 /** The assistant text of a completion, or `''` for an answer with no text block. */
 export function assistantText(message) {
     if (!message || !Array.isArray(message.content))
@@ -44,6 +29,10 @@ export function accumulateUsage(total, next) {
     return {
         inputTokens: total.inputTokens + next.inputTokens,
         outputTokens: total.outputTokens + next.outputTokens,
+        ...((total.cacheReadTokens !== undefined || next.cacheReadTokens !== undefined)
+            ? { cacheReadTokens: (total.cacheReadTokens ?? 0) + (next.cacheReadTokens ?? 0) } : {}),
+        ...((total.cacheWriteTokens !== undefined || next.cacheWriteTokens !== undefined)
+            ? { cacheWriteTokens: (total.cacheWriteTokens ?? 0) + (next.cacheWriteTokens ?? 0) } : {}),
     };
 }
 /**
@@ -59,7 +48,8 @@ export function buildSummarizeRequest(params) {
             maxChars: COMPACTION_LIMITS.summaryMaxChars,
             ...(params.instructions ? { instructions: params.instructions } : {}),
             hasPriorSummary: params.hasPriorSummary,
-        }),
+        }) + (params.validationError
+            ? `\nPrevious delta rejected: ${params.validationError.slice(0, 200)}. Correct that error.` : ''),
         messages: [buildSummaryUserMessage(params.digest, params.now)],
         maxTokens: COMPACTION_LIMITS.summaryOutputTokens,
         // PAIRED WITH `temperature: 0` ON PURPOSE: the Anthropic adapter deletes
@@ -72,15 +62,25 @@ export function buildSummarizeRequest(params) {
 }
 /** Send one summarization and bound it in wall clock. */
 export async function runSummarizeCall(params) {
-    const timer = setTimeout(params.onTimeout, COMPACTION_LIMITS.callTimeoutMs);
+    const operation = new CompactionOperation(0, params.signal, COMPACTION_LIMITS.callTimeoutMs);
+    let charged = false;
     try {
-        const message = await params.complete(params.ref.providerId, buildSummarizeRequest(params));
+        const message = await operation.run(async () => {
+            const result = await params.complete(params.ref.providerId, buildSummarizeRequest({ ...params, signal: operation.signal }));
+            if (result.usage && !charged) {
+                charged = true;
+                params.onUsage?.(result.usage);
+            }
+            return result;
+        }, COMPACTION_LIMITS.callTimeoutMs);
         return { ok: true, text: assistantText(message), usage: usageOf(message) };
     }
     catch (error) {
+        if (errorText(error) === 'timeout')
+            params.onTimeout();
         return { ok: false, error };
     }
     finally {
-        clearTimeout(timer);
+        operation.settle();
     }
 }

package/dist/compaction/summary-prompt.d.ts

@@ -1,85 +1,48 @@
-/**
- * The summarizer's system prompt and the `<compacted_context>` splice
- * (context-auto-compaction §3.6.4 / §3.6.5).
- *
- * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
- *
- * PURE. Every input arrives as an argument, so the block a session produced can
- * be reconstructed from a bug report with one call.
- */
+/** Strict v2 framing and summarizer instructions. Text shape never grants authority. */
 import type { Message, UserMessage } from '@aragon-agent/core';
-/**
- * The section skeleton the summary must fill.
- *
- * THE HEADINGS ARE PART OF THE CONTRACT, because the next model to read them is
- * an LLM: a summary with predictable sections can be scanned for "what is still
- * open" without re-reading the whole thing.
- */
+import { type CompactionMemory } from './memory.js';
+import { type CompactionIdentity } from './memory-identity.js';
+/** Build a strict delta-only prompt; throws on an oversized manual focus. */
 export declare function buildSummarySystemPrompt(opts: {
     maxChars: number;
-    /** Free text from `/compact <instructions>`, appended as `## Focus`. */
     instructions?: string;
-    /** True when the digest opens with a `PRIOR SUMMARY` section. */
     hasPriorSummary: boolean;
 }): string;
-/** The user message the summarization call sends: the digest, and nothing else. */
+/** Wrap a digest for the summary request without changing its body. */
 export declare function buildSummaryUserMessage(digest: string, now: number): UserMessage;
 export type AnchorShape = 'tagged' | 'verbatim';
 export interface AnchorInfo {
-    /** The message to place first, verbatim in the history. */
-    message: Message;
+    message: UserMessage;
     shape: AnchorShape;
 }
-/**
- * Recognize an anchor this feature produced on a previous pass.
- *
- * STRUCTURAL, NOT LENGTH-DEPENDENT (D-21 / P1-9). v1 of the design identified
- * the anchor as "the first `user` message of the conversation" and chose between
- * two shapes by length. Neither rule composes across repeated compactions,
- * because after the first pass the first user message IS the compacted block:
- * the merged shape promotes a SUMMARY to "the user's original task", and the
- * standalone shape keeps the block as an anchor AND re-digests it. Neither
- * failure raises anything, and both get worse every pass.
- */
-export declare function isTaggedAnchor(message: Message): boolean;
-/**
- * Build (or carry through) the leading anchor.
- *
- * ALWAYS ITS OWN LEADING MESSAGE, AND ALWAYS STRUCTURALLY IDENTIFIABLE. A
- * summarizer that is 90 % faithful is fine for the middle of a conversation and
- * catastrophic for the sentence that says what the user wanted (D-6).
- */
+/** Preserve the first original user Message, including all parts and timestamp. */
 export declare function buildAnchor(messages: readonly Message[]): AnchorInfo | null;
-/**
- * How many leading messages are ALREADY structurally preserved, and must be
- * carried through untouched rather than digested.
- *
- * This is `planCompaction`'s `protectedPrefix` (§3.6.2). The HOST computes it
- * because it is the host that knows what an `<original_task>` message is; core
- * stays free of any knowledge of the block format.
- */
-export declare function countProtectedPrefix(messages: readonly Message[]): number;
-/** Read `generation="N"` off a prior block, so the next one can say `N + 1`. */
-export declare function readGeneration(messages: readonly Message[]): number;
+/** Legacy syntax helper only; callers must independently establish provenance. */
+export declare function isTaggedAnchor(message: Message): boolean;
+/** Count only an adopted or restored verified prefix; tags alone protect nothing. */
+export declare function countProtectedPrefix(messages: readonly Message[], identity?: CompactionIdentity): number;
+/** Read the adopted generation; never continue a user-supplied block's authority. */
+export declare function readGeneration(messages: readonly Message[], identity?: CompactionIdentity): number;
 export interface BlockInput {
-    summary: string;
+    memory?: CompactionMemory;
+    /** Compatibility argument accepts only a complete validated v2 JSON body. */
+    summary?: string;
     replaced: number;
     turns: number;
     anchor: AnchorShape;
     generation: number;
-    /** True for a `mode: 'truncated'` splice — the model is entitled to know. */
-    truncated: boolean;
+    truncated?: boolean;
+    timestamp?: number;
 }
-/** The body used when the ladder ran out and there is no summary (§3.7 rung 3). */
-export declare function truncationBody(replaced: number): string;
-/**
- * The spliced block.
- *
- * A `user` MESSAGE, NEVER A FABRICATED ASSISTANT ONE (D-5). An assistant message
- * claiming the model said something it did not is a lie the model will then act
- * on, and it corrupts every subsequent turn. The XML tag is the same disclosure
- * device `<fast_review>` and `<skill>` already use in this codebase, and the
- * instruction line is what stops the model reading the block as the user ASKING
- * for a summary.
- */
+/** Build a complete v2 block; rejects free text, truncation and mismatched metadata. */
 export declare function buildCompactedBlock(input: BlockInput): UserMessage;
+export interface ParsedCompactedBlock {
+    memory: CompactionMemory;
+    anchor: AnchorShape;
+    replaced: number;
+    turns: number;
+}
+/** Parse exact v2 syntax and schema. This does not authenticate a history prefix. */
+export declare function parseCompactedBlock(message: Message): ParsedCompactedBlock;
+/** Retained legacy display helper; v2 never uses it to delete history. */
+export declare function truncationBody(replaced: number): string;