peaks-loop 4.1.2 → 4.1.4

package/dist/services/code/auto-compact-orchestrator.d.ts

@@ -1,243 +1,14 @@
-import { type CompactTrigger, type ConvergencePlan, type InFlightBatchProbe, type AutoCompactResult } from '../context/auto-compact-types.js';
-import type { CompactTarget } from '../context/auto-compact-dispatcher.js';
-import { type AutoCompactMode } from './auto-compact-modes.js';
-import type { CompactLifecycleRecord, CompactLifecycleStage } from '../compact-statusline/compact-lifecycle-store.js';
-export interface AutoCompactInput {
-    /** Project root for context (default cwd). */
-    readonly projectRoot: string;
-    /**
-     * Caller-provided in-flight batch probe (default false). Slice
-     * 4.0.8 (D4d): production callers should pass a `probeInflightBatch`
-     * function (see below). The legacy `inFlightBatch` boolean
-     * remains as a TEST-ONLY seam — the CLI gates it behind
-     * `process.env.PEAKS_TEST_SEAM === '1'` so a production run
-     * never consults the boolean as truth.
-     */
-    readonly inFlightBatch?: InFlightBatchProbe | undefined;
-    /**
-     * Slice 4.0.8 (D4d): graph-only in-flight probe. When supplied,
-     * the orchestrator calls this function and uses the boolean
-     * result as the production `inFlightBatch` signal. The legacy
-     * boolean parameter is suppressed in production callers — the
-     * CLI's `--in-flight-batch` flag is gated behind
-     * `PEAKS_TEST_SEAM === '1'`. The pure decision function
-     * `evaluateAutoCompactDecision` retains the boolean signature
-     * for the test seam + the red-line override.
-     */
-    readonly probeInflightBatch?: (() => boolean) | undefined;
-    /**
-     * Force execute even when ratio < threshold (test seam). In
-     * production this is always `false` — peaks-loop drives compact
-     * autonomously at 0.85+ with zero human / zero LLM intervention.
-     */
-    readonly force?: boolean | undefined;
-    /**
-     * INERT — nothing reads this. It is threaded from the CLI's
-     * `--bypass-red-line` (a published flag, kept for backward compatibility;
-     * see the option's own note) down to `evaluateAutoCompactDecision`, where the
-     * red-line branch ignores it.
-     *
-     * Why nothing reads it any more: it used to skip a gate that refused to
-     * dispatch below 0.85. That gate was removed (slice
-     * compact a running session, so the refusal could not shorten the wait it
-     * was waiting for, and it deadlocked the runner at the worst moment. With the
-     * gate gone, the red line still ASKS the harness to compact (when it always
-     * did) and no longer needs a bypass. Kept as a field so the published
-     * signature does not change under callers that pass it.
-     */
-    readonly bypassRedLine?: boolean | undefined;
-    /** Current session id (default = resolve via session-id-service). */
-    readonly sessionId?: string | undefined;
-    /** Injectable env for IDE detection (test seam). */
-    readonly env?: NodeJS.ProcessEnv | undefined;
-    /** Injectable clock for mtime checks (test seam). */
-    readonly now?: Date | undefined;
-    /**
-     * the compact should target. Default `'main'` — the orchestrator
-     * (peaks-code body) runs in the main-session Claude Code window and
-     * wants to compress *its* context. Sub-agent shells pass
-     * `'sub-agent'` to preserve the legacy shell-spawn behaviour.
-     */
-    readonly target?: CompactTarget | undefined;
-    /**
-     * `'standard'` (v2.13.0 zero-pause contract, 0.85/0.95). `'partial'`
-     * fires earlier (0.70/0.85) for 24h long-run scenarios. CLI flag
-     * `--mode <mode>` overrides the 24h-mode auto-detection.
-     */
-    readonly mode?: AutoCompactMode | undefined;
-    /**
-     * every lifecycle stage this process actually proved. Telemetry
-     * only — it can neither change the threshold decision nor the
-     * dispatch outcome, and a throwing observer is swallowed.
-     */
-    readonly onLifecycleStage?: ((stage: CompactLifecycleStage, record: CompactLifecycleRecord) => void) | undefined;
-    /**
-     * Test-only injection seams for lifecycle failure paths. NEVER set in
-     * production — these exist so the unit suite can drive the `failed`
-     * transition and the store-outage branch without mocking the SUT.
-     * Each flag toggles a single, well-scoped throw at a documented point:
-     *   - `failPreparing`: throw inside the checkpoint/plan/recovery phase
-     *     (so the record rests at `failedAt: 'preparing'`)
-     *   - `failCompacting`: throw inside the IDE-dispatch phase
-     *     (so the record rests at `failedAt: 'compacting'`)
-     *   - `failLifecycleWrite`: make every lifecycle-store write throw
-     *     (so the compact envelope is proven independent of telemetry)
-     */
-    readonly testHooks?: AutoCompactTestHooks | undefined;
-}
-/**
- * Test-only injection seams. The `boolean` shape (vs. an injected error)
- * is deliberate: tests assert the *transition*, not the thrown value —
- * the value would just be a brittle fingerprint. The real error path
- * is still exercised by `summarizeLifecycleError`'s tests.
- */
-export interface AutoCompactTestHooks {
-    readonly failPreparing?: boolean | undefined;
-    readonly failCompacting?: boolean | undefined;
-    readonly failLifecycleWrite?: boolean | undefined;
-}
-/**
- * Map a context ratio to a `CompactTrigger` action. Pure; the side
- * effects (checkpoint + IDE dispatch) live in `runAutoCompact`. Two
- * tiers (standard mode; partial mode shifts both thresholds):
- *
- *   - ratio < preCompact → 'none' or 'soft-warn'
- *   - ratio ≥ preCompact → 'pre-compact' (async-friendly path)
- *   - ratio ≥ redLine    → 'red-line' (ask the harness; dispatch continues)
- *
- * Default `'standard'` (0.85/0.95). `'partial'` (0.70/0.85) is used
- * when 24h long-run mode is active or `--mode partial` is passed.
- */
-export declare function evaluateCompactTrigger(ratio: number, mode?: AutoCompactMode): CompactTrigger;
-/**
- * Decide whether to run the auto-compact flow. Pure function for the
- * decision; side effects (checkpoint + IDE dispatch) live in
- * `runAutoCompact` below. Zero human / zero LLM intervention:
- *
- *   - ratio < 0.85           → skip (LLM keeps working; no action)
- *   - 0.85 ≤ ratio < 0.95    → pre-compact; if in-flight batch
- *                                present, defer (D6.e); else dispatch
- *                                IDE compact asynchronously.
- *   - ratio ≥ 0.95           → red-line; ask the harness to compact
- *                                regardless of in-flight batch. Nothing is
- *                                gated — dispatch is NOT blocked (slice
- *                                peaks-loop cannot compact a running session,
- *                                so a "block" gated nothing and deadlocked the
- *                                runner).
- */
-export declare function evaluateAutoCompactDecision(input: {
-    ratio: number;
-    /**
-     * Caller-provided in-flight batch signal. Accepts either a plain
-     * boolean (convenience / repro seam) or the full `InFlightBatchProbe`
-     * shape (production callers — graph-probe-backed). When the boolean
-     * form is `true`, the normalized probe carries
-     * `hasInFlightBatch: true`. Slice 4.0.8 hotfix.
-     */
-    inFlightBatch?: boolean | InFlightBatchProbe | undefined;
-    /**
-     * Legacy camelCase alias for `inFlightBatch`. Production repro
-     * inputs use `inflightBatch: true|false`; the orchestrator
-     * normalizes it to the same internal shape. Slice 4.0.8 hotfix.
-     */
-    inflightBatch?: boolean | InFlightBatchProbe | undefined;
-    force?: boolean | undefined;
-    /** Accepted and ignored — see `AutoCompactInput.bypassRedLine`. */
-    bypassRedLine?: boolean | undefined;
-    mode?: AutoCompactMode | undefined;
-    /**
-     * Source tag from `readContextPercent.source`. Optional — when absent, the
-     * function behaves exactly as pre-rid (ratio-only). Slice 2026-07-31-rid-
-     * mac-transcript-estimate-trigger uses this to carry forward an explicit
-     * carve-out for the Mac-only `transcript-estimate` signal.
-     */
-    source?: string | undefined;
-}): {
-    shouldCompact: boolean;
-    reason: 'below-threshold' | 'in-flight-batch' | 'pre-compact' | 'red-line';
-    trigger: CompactTrigger;
-    /** Typed verdict enum (RD §4 24h-mode contract). Slice 4.0.8 hotfix. */
-    action: 'ok' | 'soft-warn' | 'auto-compact-now' | 'red-line' | 'defer';
-};
-/**
- * Build the convergence plan that D7's post-compact-detect will read
- * back. Includes the current plan, open questions, recent decisions,
- * todo state, and recent artifact paths — strictly more than what a
- * raw `/compact` would preserve.
- */
-export declare function buildConvergencePlan(input: {
-    readonly sessionId: string;
-    readonly projectRoot: string;
-    readonly ratio: number;
-    readonly checkpointPath: string;
-    readonly nextActions: readonly string[];
-    readonly redLine?: boolean;
-}): ConvergencePlan;
-/**
- * Execute the auto-compact flow.
- *
- * Steps (orchestration):
- *   1. Resolve session id.
- *   3. Evaluate trigger via `evaluateCompactTrigger`.
- *   4. If trigger.kind === 'none' / 'soft-warn' → return skip.
- *   5. If trigger.kind === 'pre-compact' AND in-flight batch → wait.
- *   6. If trigger.kind === 'pre-compact' → async dispatch (write
- *      checkpoint + IDE compact; orchestrator returns immediately).
- *   7. If trigger.kind === 'red-line' → dispatch the IDE compact, report
- *      that the harness has been asked and that dispatch continues.
- *
- * The caller (CLI or skill body) handles the actual return — D7's
- * post-compact-detect will pick up the checkpoint on the next turn. For
- * red-line, the caller keeps working; it re-probes and, if the ratio is
- * still rising with no compact from the harness, reports that instead of
- * stalling.
- */
-export declare function runAutoCompact(input: AutoCompactInput): Promise<AutoCompactResult>;
-/** Re-export for callers that need to surface the trigger shape. */
+import type { AutoCompactResult, CompactTrigger, ConvergencePlan, InFlightBatchProbe } from '../context/auto-compact-types.js';
+import type { AutoCompactInput } from './auto-compact-run-types.js';
+export type { AutoCompactInput, AutoCompactTestHooks } from './auto-compact-run-types.js';
+export { evaluateCompactTrigger, evaluateAutoCompactDecision, buildConvergencePlan } from './auto-compact-decision.js';
+export type { CompactHistoryEvent } from './auto-compact-history.js';
+export { appendCompactHistoryEvent } from './auto-compact-history.js';
 export type { CompactTrigger, ConvergencePlan, InFlightBatchProbe, AutoCompactResult };
 /**
- * auto-compact dispatch. Appended at the end of `executeAutoCompact`
- * so the new 'peaks compact history' CLI + the
- * 'peaks statusline compact' indicator have a record. One file
- * per session (gitignored under `.peaks/_runtime/<sessionId>/`).
+ * Execute the auto-compact flow. The caller handles the return — the post-compact
+ * detector picks the checkpoint up on the next turn. For the red line the caller keeps
+ * working: it re-probes and, if the ratio is still rising with no compact from the
+ * harness, reports that instead of stalling.
  */
-export interface CompactHistoryEvent {
-    readonly schemaVersion: 1;
-    readonly ts: string;
-    readonly target: 'main' | 'sub-agent' | 'worker';
-    readonly mode: 'standard' | 'partial' | 'aggressive';
-    readonly ide: string;
-    readonly pathway: string;
-    readonly beforeRatio: number;
-    readonly redLine: boolean;
-    readonly ok: boolean;
-    readonly checkpointPath: string;
-    readonly dispatchMessage: string;
-    /**
-     * instrument. `windowTokens` is the denominator peaks-loop divided by
-     * (`probe.capacityTokens`), so `beforeRatio * windowTokens` is the exact
-     * TOKEN POINT peaks-loop asked the harness to compact at. That number is
-     * the deliverable — NOT a hand-picked threshold: this slice could not run a
-     * real Claude Code session, so the real trigger point of
-     * `CLAUDE_CODE_AUTO_COMPACT_WINDOW` (documented as a window, observed to
-     * fire near the window's end) has no measured answer yet. Recording the
-     * intent lets the first real session produce one.
-     */
-    readonly windowTokens?: number | null;
-    /** Which layer produced `windowTokens` (see `ContextWindowSource`). */
-    readonly windowSource?: string | null;
-    /**
-     * `dispatch` (default, and the only kind earlier releases wrote) or
-     * `observed` — a row appended when a later probe MEASURED the ratio after
-     * a dispatched compact, proving one landed. The pair is what yields the
-     * intent-vs-observed delta.
-     */
-    readonly kind?: 'dispatch' | 'observed';
-    /** `observed` rows only: the measured post-compact ratio. */
-    readonly afterRatio?: number;
-}
-export declare function appendCompactHistoryEvent(input: {
-    readonly projectRoot: string;
-    readonly sessionId: string;
-    readonly event: CompactHistoryEvent;
-}): void;
+export declare function runAutoCompact(input: AutoCompactInput): Promise<AutoCompactResult>;