@aragon-agent/cli 0.6.2 → 0.6.3

package/dist/compaction/wiring.d.ts

@@ -0,0 +1,255 @@
+/**
+ * `CompactionWiring` — the controller-side glue for context compaction
+ * (context-auto-compaction §3.2.1 / §5.2).
+ *
+ * ASCII ONLY: `src/compaction/**` is inside the glyph scanner's scope.
+ *
+ * CONSTRUCT BEFORE THE `Agent`, ATTACH AFTER IT (C-12 / D-19), and the split is
+ * the whole reason this class has an `attach` method at all:
+ *
+ *   - The PORT has to be INSIDE the `Agent`'s constructor argument, because
+ *     `AgentConfig.contextManager` has no setter and the loop reads it from the
+ *     loop context.
+ *   - The WIRING has to SUBSCRIBE to the `Agent`, because `compaction_end` is
+ *     where the engine's `applied` verdict arrives and `agent_start` is what
+ *     resets the per-run cap.
+ *
+ * `AgentController` cannot do both in one step: `new Agent({...})` runs before
+ * every optional subsystem, precisely because `FastWiring`'s constructor
+ * subscribes. So THIS CONSTRUCTOR MUST NOT SUBSCRIBE. A field assigned after the
+ * `new Agent` call and spread into it conditionally produces a build where the
+ * feature is registered, enabled, and SILENTLY ABSENT - the exact shape of
+ * failure `controller.ts`'s `toolOutputs` comment documents.
+ *
+ * `manager()` returns a STABLE object for the controller's lifetime, whose two
+ * methods delegate to a compactor that reads config LIVE - which is what lets
+ * `/compact off`, `/compact threshold 0.8` and a settings-screen save take effect
+ * mid-session without touching the `Agent`.
+ */
+import { type AgentEvent, type ContextManager, type Message, type ModelInfo, type ModelRef, type ProviderRegistry, type ProviderRegistryOptions, type TokenUsage } from '@aragon-agent/core';
+import type { CliConfig } from '../config/schema.js';
+import type { NoticeLevel } from '../agent/reducer.js';
+import { type ChildContextManagerFactory } from './child.js';
+import type { CompactionEventListener, CompactionSnapshot } from './types.js';
+export interface CompactionWiringDeps {
+    /** Read LIVE on every call - the controller replaces the object on mutation. */
+    getConfig: () => CliConfig;
+    hasKey: (providerId: string) => boolean;
+    getApiKey: (providerId: string) => string | undefined;
+    getModelInfoFor: (ref: Pick<ModelRef, 'providerId' | 'modelId'>) => ModelInfo;
+    isPricedModel: (ref: Pick<ModelRef, 'providerId' | 'modelId'>) => boolean;
+    /**
+     * LAZY, and they must be: this class is constructed BEFORE the `Agent`, so a
+     * closure that touches it is only valid from inside an event handler.
+     */
+    getMessages: () => readonly Message[];
+    getSystemPrompt: () => string;
+    notify: (level: NoticeLevel, text: string) => void;
+    /**
+     * How the summarizer's own registry is built. Defaults to `initProviders`.
+     *
+     * THE ONE PRODUCTION SEAM ADDED FOR TESTABILITY (hardening DH-13 / W6).
+     * Everything else the offline harness needs is already public:
+     * `ProviderRegistry.register` overwrites by id, `AgentController` exposes the
+     * lead's registry, and `Agent` accepts one in its config. `getRegistry()` was
+     * the only closed door - it calls `initProviders` with no injection point, so
+     * the lead's transport was scriptable in a test and the SUMMARIZER'S was not.
+     * A test-only seam per module is how a codebase acquires a shadow API; this is
+     * one, and it is named.
+     */
+    createRegistry?: (options: ProviderRegistryOptions) => ProviderRegistry;
+    /**
+     * The archive directory, injected by the tests. Production passes nothing and
+     * `archive.ts` resolves `<home>/compaction` itself.
+     */
+    archiveDir?: string;
+}
+/** The status of a session that never had compaction (the wiring is `null`). */
+export declare function offCompactionSnapshot(): CompactionSnapshot;
+export declare class CompactionWiring {
+    private readonly deps;
+    private readonly log;
+    private readonly listeners;
+    private readonly compactor;
+    /** The compactor's OWN transport (D-10). Lazy - see `getRegistry()`. */
+    private registry;
+    private unsubscribe;
+    /** The stable port handed to `new Agent({...})`. Never reassigned. */
+    private readonly port;
+    /**
+     * The record the compactor produced, waiting for the ENGINE's verdict.
+     *
+     * `applied` is not knowable on the host side: validation happens after
+     * `compact()` returns, inside the loop. So the compactor's record is held here
+     * and corrected when the core `compaction_end` arrives (§3.2.1). The IDLE
+     * `/compact` path has no core event and settles its own record directly.
+     */
+    private pending;
+    /**
+     * What the CLI-local `compaction_start` announced, and `null` once the card has
+     * been settled.
+     *
+     * THE ENGINE'S VERDICT CAN ARRIVE BEFORE THE COMPACTOR'S RECORD, and Esc is the
+     * ordinary way it happens: `runCompaction` races `compact()` against the run's
+     * signal, so an abort resolves the race and emits `compaction_end` while
+     * `compact()` is still unwinding its own call. With nothing held here,
+     * `settlePending` would find no record, return, and leave the card `live:
+     * true` FOREVER — which is C-8's failure mode exactly: `Transcript`'s settled
+     * boundary is monotonic, so the whole tail re-renders on every frame for the
+     * rest of the session, and the card goes on claiming a compaction is running.
+     * `manager_timeout` and a `compact()` that rejects outright reach the same
+     * place.
+     *
+     * So the verdict settles the card from whatever is available — the compactor's
+     * record when it exists, this skeleton when it does not — and clearing this
+     * field is what tells a LATE record that its card is already closed.
+     */
+    private open;
+    /** Live flag, flipped by `/compact on|off`. Starts equal to `enabled`. */
+    private enabled;
+    /**
+     * Identifies THIS RUN's archives in a directory several runs share (RV-6).
+     *
+     * NOT `SessionMeta.id`: that exists only once a session has been saved, and the
+     * unattended long run this feature serves is exactly the one nobody saved.
+     * Short, filename-safe, and only ever compared for equality - it is a grouping
+     * key, not an identity.
+     */
+    private readonly runId;
+    constructor(deps: CompactionWiringDeps);
+    /**
+     * The port for `new Agent({...})`.
+     *
+     * Spread CONDITIONALLY at the call site so `contextManager` stays genuinely
+     * `undefined` when the feature is off (AC-1): the loop's gate is
+     * `if (!ctx.contextManager) return false` against an ABSENT field, not a live
+     * object whose predicate says no.
+     */
+    manager(): ContextManager;
+    /**
+     * Subscribe to the lead agent's stream. IDEMPOTENT, and separate from the
+     * constructor - see the file header.
+     */
+    attach(subscribe: (listener: (event: AgentEvent) => void) => () => void): void;
+    dispose(): void;
+    isEnabled(): boolean;
+    setEnabled(enabled: boolean): void;
+    /** Re-emit the snapshot after any config mutation, so the chip and the gauge move. */
+    onConfigChanged(): void;
+    abort(): void;
+    /**
+     * The host replaced or cleared the history (hardening §3.2.3, sites 3 and 4).
+     *
+     * `/clear`, `/resume`, and any future host-side rewrite. A recorded prefix
+     * length indexes an array that no longer exists, so the delta must be
+     * abandoned rather than applied to a different history.
+     */
+    onHistoryReplaced(): void;
+    /**
+     * The per-child manager factory, or `null` when children get none
+     * (hardening §3.4 / W3).
+     *
+     * `null` RATHER THAN A NO-OP FACTORY, so `subagent.ts` can spread NOTHING and
+     * the child's loop gate tests a genuinely absent `contextManager` - the same
+     * byte-identity argument `AgentController` makes for the lead (AC-H10).
+     */
+    childFactory(): ChildContextManagerFactory | null;
+    queueManual(instructions?: string): void;
+    hasPendingManual(): boolean;
+    clearPendingManual(): void;
+    /**
+     * The IDLE `/compact` path (§4.4 / D-25).
+     *
+     * IT VALIDATES BEFORE IT SPLICES, AND THAT IS NOT OPTIONAL (P1-7). When the
+     * agent is idle there is no loop, so §3.3 step 5 does not run — and the only
+     * way to replace the history is `Agent.replaceMessages`, which validates
+     * nothing. D-4 declares that gate unbypassable and R-2 calls an invalid splice
+     * the worst possible outcome, so this path mirrors the engine's steps 3-5
+     * exactly, INCLUDING the failure vocabulary: the card, the log and
+     * `/compact status` cannot tell the two paths apart.
+     *
+     * No watchdog handling is needed — `runLoopWithLifecycle`'s `finally` already
+     * called `watchdog.stop()`, so nothing is armed while idle.
+     *
+     * ITS CALLER MUST ADOPT `messages` — THE ARCHIVE IS ALREADY WRITTEN BY THE
+     * TIME THIS RETURNS (hardening RV-7). This path settles `applied: true` here,
+     * one statement before the caller splices, so the "never archive a live
+     * history" rule holds only because that caller applies unconditionally. That is
+     * a fact about one call site rather than an invariant, which is why it is
+     * written down where it can be checked.
+     */
+    compactNow(args: {
+        messages: readonly Message[];
+        systemPrompt: string;
+        model: ModelRef;
+        signal: AbortSignal;
+        lastUsage?: TokenUsage;
+        instructions?: string;
+    }): Promise<{
+        ok: true;
+        messages: Message[];
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    snapshot(): CompactionSnapshot;
+    /**
+     * `snapshot()` with the pressure argument substituted for the re-measurement.
+     *
+     * SO THE CHECKPOINT DOES NOT MEASURE TWICE. `shouldCompact` has already walked
+     * the appended slice; measuring again here would double the one cost DH-15
+     * accepted, and - worse - the second measurement could differ from the one the
+     * decision was made on if anything appended in between.
+     */
+    private snapshotWith;
+    /** The summarizer that would be used right now, for `/compact status`. */
+    summarizerRef(): ModelRef | null;
+    subscribe(listener: CompactionEventListener): () => void;
+    /**
+     * The transport one summarization call goes through - separate from the lead's,
+     * and fail-fast (D-10).
+     *
+     * LAZY, SO OFF STAYS BYTE-IDENTICAL. Nothing is constructed until a compaction
+     * actually calls, so a session that never crosses the threshold allocates no
+     * registry and registers no adapters.
+     */
+    private getRegistry;
+    private onCompactorEvent;
+    private onAgentEvent;
+    /**
+     * Settle the held record with the authoritative verdict, then emit it.
+     *
+     * `tokensBefore` / `tokensAfter` come from CORE'S OWN estimator on BOTH sides
+     * (§5.1), so the card's headline claim compares two numbers in one unit rather
+     * than a measurement against a guess. `tokensReclaimed` is accumulated from the
+     * same pair, which is what keeps `/compact status` and the card agreeing.
+     */
+    private settlePending;
+    /**
+     * Write the archive, if there is one to write (hardening §3.5.3 / W4).
+     *
+     * ONLY ON `applied: true`, because the rule the writer enforces is "never
+     * archive a history that is still live" - and the two paths reach that verdict
+     * at different moments relative to the splice. In loop, the ENGINE decides
+     * after `validateHistory`, so this runs AFTER adoption. On the manual path the
+     * WIRING decides and `compactNow`'s caller adopts on the next statement, so
+     * this runs BEFORE adoption; `compactNow`'s doc comment carries that obligation
+     * for its one caller (RV-7).
+     *
+     * BEST-EFFORT AND SYNCHRONOUS-BUT-GUARDED. `writeArchive` never throws and
+     * logs its own failure; a failed archive never affects the compaction, and it
+     * never notifies - a toast for a best-effort audit file trains users to ignore
+     * toasts.
+     */
+    private archive;
+    /** This run's archive key, for `/compact history` and `/compact show`. */
+    archiveRunId(): string;
+    /**
+     * The minimum a card needs to settle when the compactor's own record has not
+     * arrived (see `open`). `null` when no card was ever opened — the
+     * `shouldCompact`-threw path, where the engine emits a pair of events the CLI
+     * stream knows nothing about.
+     */
+    private skeletonRecord;
+    private emit;
+}