supercode_reduce/engine/

handoff.rs

//! TR-9 (T24): `/handoff` as extreme projection — "Amp retired
//! summarization-compaction for /handoff: spawn a new thread seeded with a
//! drafted objective + curated relevant artifacts, old thread untouched."
//! (TOKEN-REDUCTION-TECHNIQUES.md@ad3f2a4 §T24). In supercode a handoff is
//! NOT a new session lineage — it is a named [`ReductionLog`] snapshot over
//! the SAME sidecar: the projected view collapses to (1) a handoff banner,
//! (2) an objective paragraph, and (3) a curated keep-set, with EVERY OTHER
//! turn covered by one [`ReductionKind::TurnsCleared`] span per contiguous
//! gap between kept turns.
//!
//! # Design: reusing `TurnsCleared`, not inventing a new kind
//!
//! A handoff keep-set is generally scattered (system prompt + some
//! user-named early turns + the last K turns), so the "everything else"
//! complement is generally MULTIPLE disjoint ranges, not one. Rather than a
//! dedicated `HandoffCleared` reduction kind, this reuses
//! [`ReductionKind::TurnsCleared`] verbatim — one record per gap — which
//! required exactly one change to [`super::project_messages`] itself: its
//! reapplication path used to assume "at most one `TurnsCleared` reduction,
//! ever" (true for the auto-compactor, `Agent::maybe_compact`); it now
//! reapplies EVERY existing `TurnsCleared` record it finds, which is a
//! strict, backward-compatible generalization (a log with zero or one such
//! record behaves identically to before). `invert`/`verify_log`/
//! `expand_reduction`/`sidecar_search` already treated `log.reductions` as an
//! unordered bag keyed by `id`/address — those needed NO changes at all.
//!
//! # Banner/objective are view-only, never in the sidecar
//!
//! The banner+objective text is never a [`Reduction`] and never recorded in
//! the [`ReductionLog`] — it is folded into the projected VIEW's leading
//! system-role message only (merged into an existing leading system message
//! if the canonical session has one, else inserted as a new one), exactly
//! like TR-7's [`super::SpanSummary`] audit metadata: view-layer only,
//! `invert`/`verify_log` never look at it, and it structurally cannot reach
//! `supercode-harness`'s session export adapters (which rebuild
//! **only** from the sidecar, never from a projected view).
//!
//! # Fresh projection, not an incremental one
//!
//! [`build_handoff`] deliberately builds its handoff view from a FRESH
//! projection (`ReductionLog::default()`) over the canonical session rather
//! than reapplying whatever reduction log the session already had — a
//! handoff is "one projection event" (SPEC.md C7's own framing), so kept
//! turns show their full, untouched content (never stacked on top of
//! whatever had been truncated/deduped/superseded before), and the emitted
//! [`ReductionLog`] is exactly the set of reductions the handoff itself
//! establishes: the standard lossless per-message passes (A7-A9, TR-2, TR-4,
//! TR-6, TR-10) plus one `TurnsCleared` per non-kept gap.

use std::collections::HashSet;

use super::summarize::SpanSummarizer;
use super::{
    count_roles, format_commas, hash_turns_range, make_id, project_messages, render_span_text,
    set_reduction_id, stub, MessageAddr, Reduction, ReductionKind, ReductionLog, ReductionPolicy,
    SidecarPtr,
};
use crate::Result;
use supercode_interchange::{ChatMessage, Role};

/// One parsed `--keep` token.
#[derive(Debug, Clone, PartialEq, Eq)]
enum KeepToken {
    /// A single canonical message address (e.g. `"12"`).
    Addr(usize),
    /// An inclusive address range (e.g. `"5-9"`).
    Range(usize, usize),
    /// A file path (or substring of one) — every message that reads or
    /// writes a matching path is kept, along with its paired tool call/result.
    Path(String),
}

/// Parse one `--keep` token: a bare integer is an address, `A-B` (both sides
/// integers) is an inclusive range, anything else is a path/substring.
fn parse_token(tok: &str) -> KeepToken {
    let t = tok.trim();
    if let Ok(n) = t.parse::<usize>() {
        return KeepToken::Addr(n);
    }
    if let Some((a, b)) = t.split_once('-') {
        if let (Ok(a), Ok(b)) = (a.trim().parse::<usize>(), b.trim().parse::<usize>()) {
            return KeepToken::Range(a.min(b), a.max(b));
        }
    }
    KeepToken::Path(t.to_string())
}

/// Does `call`'s parsed arguments reference `path` (via a `path` or
/// `file_path` field, substring match)? Covers this crate's own builtins
/// (`path`) and Claude Code's native `Write`/`Read` (`file_path`).
fn call_touches_path(call: &supercode_interchange::ToolCall, path: &str) -> bool {
    let Ok(args) = call.function.parsed_arguments() else {
        return false;
    };
    args.get("path")
        .or_else(|| args.get("file_path"))
        .and_then(|v| v.as_str())
        .is_some_and(|v| v.contains(path))
}

/// The index of the `Role::Tool` result paired (by `tool_call_id`) to `call`,
/// searched forward from `after` — mirrors [`super::detect_tool_inputs`]'s
/// own pairing direction.
fn paired_result_index(msgs: &[ChatMessage], after: usize, call_id: &str) -> Option<usize> {
    msgs[after + 1..]
        .iter()
        .position(|m| m.role == Role::Tool && m.tool_call_id.as_deref() == Some(call_id))
        .map(|off| after + 1 + off)
}

/// The index of the `Role::Assistant` message whose `tool_calls` contains
/// `call_id`, searched backward from (and excluding) `before` — mirrors
/// [`super::detect_reads`]'s own pairing direction.
fn paired_call_index(msgs: &[ChatMessage], before: usize, call_id: &str) -> Option<usize> {
    msgs[..before]
        .iter()
        .rposition(|m| m.role == Role::Assistant && m.tool_calls().iter().any(|c| c.id == call_id))
}

/// Resolve the full keep-set (SPEC.md TR-9 dev/01/dev/03): user-named
/// addresses/paths (`tokens`) PLUS the deterministic always-keeps — the
/// leading system prompt (if any) and the last `keep_last` messages — closed
/// under tool-call/tool-result pairing so a kept call never dangles without
/// its result (or vice versa). Pure function of `msgs` alone; canonical
/// (sidecar) indices throughout.
pub fn resolve_keep_indices(
    msgs: &[ChatMessage],
    tokens: &[String],
    keep_last: usize,
) -> Vec<usize> {
    let len = msgs.len();
    let mut keep: HashSet<usize> = HashSet::new();

    // Always-keep #1: the leading system prompt (SPEC.md dev/03).
    let mut i = 0;
    while i < len && msgs[i].role == Role::System {
        keep.insert(i);
        i += 1;
    }

    // Always-keep #2: the last `keep_last` messages (SPEC.md dev/03),
    // extended backward past a lone leading tool result (never start the
    // kept tail mid-call, mirroring `compute_clear_range`'s own tool-
    // boundary guard for the surviving window).
    if keep_last > 0 && len > 0 {
        let mut start = len.saturating_sub(keep_last);
        while start > 0 && msgs[start].role == Role::Tool {
            start -= 1;
        }
        for idx in start..len {
            keep.insert(idx);
        }
    }

    // User-named tokens.
    for tok in tokens {
        match parse_token(tok) {
            KeepToken::Addr(n) => {
                if n < len {
                    keep.insert(n);
                }
            }
            KeepToken::Range(a, b) => {
                // Clamp the upper bound BEFORE iterating: an unclamped `b`
                // (e.g. `--keep 5-99999999999`) would otherwise loop billions
                // of times just to have every out-of-range `n` immediately
                // discarded by an `n < len` check inside the loop — a
                // plausible hang on any real session. Clamping first bounds
                // the iteration count by `len` itself, with identical
                // behavior for every in-range value (and a no-op when
                // `len == 0` or `a >= len`, matching the old unclamped loop's
                // behavior exactly in both cases).
                if len == 0 {
                    continue;
                }
                let b = b.min(len - 1);
                if a <= b {
                    for n in a..=b {
                        keep.insert(n);
                    }
                }
            }
            KeepToken::Path(p) => {
                for (idx, m) in msgs.iter().enumerate() {
                    if m.role != Role::Assistant {
                        continue;
                    }
                    for call in m.tool_calls() {
                        if call_touches_path(call, &p) {
                            keep.insert(idx);
                            if let Some(ridx) = paired_result_index(msgs, idx, &call.id) {
                                keep.insert(ridx);
                            }
                        }
                    }
                }
            }
        }
    }

    // Tool-call/tool-result pairing closure: one pass suffices (pairing is
    // 1:1, no transitive chains).
    let snapshot: Vec<usize> = keep.iter().copied().collect();
    for idx in snapshot {
        match msgs[idx].role {
            Role::Tool => {
                if let Some(cid) = msgs[idx].tool_call_id.clone() {
                    if let Some(aidx) = paired_call_index(msgs, idx, &cid) {
                        keep.insert(aidx);
                    }
                }
            }
            Role::Assistant => {
                for call in msgs[idx].tool_calls().iter().cloned() {
                    if let Some(ridx) = paired_result_index(msgs, idx, &call.id) {
                        keep.insert(ridx);
                    }
                }
            }
            _ => {}
        }
    }

    let mut out: Vec<usize> = keep.into_iter().collect();
    out.sort_unstable();
    out
}

/// Maximal contiguous runs of `0..len` NOT in `keep` — the spanning-clear
/// candidates, one [`ReductionKind::TurnsCleared`] per run.
fn compute_gaps(len: usize, keep: &HashSet<usize>) -> Vec<(usize, usize)> {
    let mut gaps = Vec::new();
    let mut i = 0;
    while i < len {
        if keep.contains(&i) {
            i += 1;
            continue;
        }
        let start = i;
        while i < len && !keep.contains(&i) {
            i += 1;
        }
        gaps.push((start, i - 1));
    }
    gaps
}

/// Where the objective paragraph came from — [`build_handoff`]'s dev/05
/// contract: user text always wins when given; otherwise, drafting is
/// attempted only when `draft_objective` is on AND a summarizer is injected,
/// and any failure (no summarizer, an `Err`, or a blank result) falls back to
/// the plain banner with no objective line at all.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ObjectiveSource {
    /// `--objective "<text>"` was given verbatim (trimmed).
    UserSupplied,
    /// Drafted via the injected [`SpanSummarizer`] (TR-7 plumbing reuse).
    Drafted,
    /// No objective at all: `--draft-objective` off (the default), no
    /// summarizer injected, or the side-call errored/returned blank.
    Fallback,
}

/// TR-9's reuse of TR-7's injectable side-call plumbing (SPEC.md TR-9 dev/05):
/// user-supplied text always wins outright (no side-call attempted); when
/// none is given AND `draft_objective` is on AND a summarizer is injected,
/// draft one paragraph from a rendering of the whole session — any error or
/// blank result falls back to no objective (the plain banner), exactly like
/// [`super::prepare_cleared_turns_summary`]'s own failure-fallback contract.
/// Off by default: a caller must both pass `draft_objective: true` AND inject
/// a summarizer for drafting to ever be attempted at all.
fn resolve_objective(
    msgs: &[ChatMessage],
    objective: Option<&str>,
    draft_objective: bool,
    summarizer: Option<&dyn SpanSummarizer>,
) -> (Option<String>, ObjectiveSource) {
    if let Some(text) = objective {
        let t = text.trim();
        if !t.is_empty() {
            return (Some(t.to_string()), ObjectiveSource::UserSupplied);
        }
    }
    if draft_objective {
        if let Some(s) = summarizer {
            let span_text = render_span_text(msgs);
            if let Ok(t) = s.summarize(&span_text) {
                let t = t.trim();
                if !t.is_empty() {
                    return (Some(t.to_string()), ObjectiveSource::Drafted);
                }
            }
        }
    }
    (None, ObjectiveSource::Fallback)
}

/// Render the handoff banner: a fixed honesty header naming every gap's
/// reduction id (so `expand_reduction("<id>")`/`/expand <id>` are spelled
/// out, mirroring TR-7's own placeholder banner), plus the objective
/// paragraph when one was resolved.
fn format_banner(objective: Option<&str>, gap_ids: &[String], total_cleared: usize) -> String {
    let mut s = String::from("=== HANDOFF ===\n");
    if gap_ids.is_empty() {
        s.push_str(
            "This is a curated continuation of a prior session. Nothing was cleared — the \
             full session is already in view.",
        );
    } else {
        s.push_str(&format!(
            "This is a curated continuation of a prior session. {} earlier turn(s) were \
             cleared into {} spanning reduction(s) and remain fully recoverable — call \
             expand_reduction(\"<id>\") (or `/expand <id>`) for any of: {}. The full session \
             is unchanged in its sidecar.",
            format_commas(total_cleared),
            gap_ids.len(),
            gap_ids.join(", "),
        ));
    }
    if let Some(obj) = objective {
        s.push_str("\n\nOBJECTIVE: ");
        s.push_str(obj);
    }
    s
}

/// The complete output of [`build_handoff`].
#[derive(Debug, Clone)]
pub struct HandoffResult {
    /// The projected view: banner+objective folded into the leading
    /// system-role message, followed by every kept message (in original
    /// order, with the standard lossless per-message reductions already
    /// applied) and one placeholder per cleared gap.
    pub view: Vec<ChatMessage>,
    /// The fresh reduction log this handoff establishes (SPEC.md: "a named
    /// `ReductionLog` snapshot") — the standard per-message passes plus one
    /// `TurnsCleared` per gap. Never contains the banner/objective text.
    pub log: ReductionLog,
    /// Canonical (sidecar) indices in the keep-set, sorted ascending.
    pub kept_indices: Vec<usize>,
    /// The ids of the `TurnsCleared` reductions minted, one per gap, in
    /// chronological (address) order.
    pub gap_ids: Vec<String>,
    /// Where the objective paragraph came from.
    pub objective_source: ObjectiveSource,
    /// The resolved objective text, if any (also folded into `view[0]`, kept
    /// here separately for callers/tests that want it without re-parsing).
    pub objective_text: Option<String>,
}

/// The base projection policy [`build_handoff`] runs its first (standard,
/// per-message) pass under: every lossless SPEC.md default lever (A7-A9,
/// TR-2, TR-4, TR-6, TR-10) stays on, but A10 (`clear_turns_older_than`) is
/// forced off — the handoff's own multi-gap spanning clear (below) replaces
/// it entirely, so the single-range auto-compactor pass must never also fire
/// in the same call.
fn base_policy() -> ReductionPolicy {
    ReductionPolicy {
        clear_turns_older_than: None,
        ..ReductionPolicy::default()
    }
}

/// Build a handoff projection over `msgs` (the canonical, full-fidelity
/// session messages — e.g. `sidecar.messages`). SPEC.md TR-9: produces a new
/// PROJECTED continuation — banner + objective + curated keep-set, with
/// every other turn covered by one `TurnsCleared` span per gap between kept
/// turns — over the SAME sidecar (this function never touches a sidecar or
/// disk at all; persisting `HandoffResult::log`/`view` is the caller's job,
/// e.g. `supercode handoff`'s CLI handler).
///
/// `keep_tokens` are `--keep` selectors (addresses, address ranges, or file
/// paths/substrings); `keep_last` is the deterministic always-keep tail
/// length (SPEC.md dev/03, alongside the always-kept leading system prompt).
/// `objective`/`draft_objective`/`summarizer` implement SPEC.md dev/05 (see
/// `resolve_objective`).
pub fn build_handoff(
    msgs: &[ChatMessage],
    keep_tokens: &[String],
    keep_last: usize,
    objective: Option<&str>,
    draft_objective: bool,
    summarizer: Option<&dyn SpanSummarizer>,
) -> Result<HandoffResult> {
    let kept_indices = resolve_keep_indices(msgs, keep_tokens, keep_last);
    let keep: HashSet<usize> = kept_indices.iter().copied().collect();

    // Step 1: the standard lossless per-message passes over the WHOLE
    // canonical session, fresh (SPEC.md: "one projection event") — A10
    // stays off; the multi-gap spanning clear below is this function's own
    // A10 analog. `view`/`log` stay index-parallel to `msgs` here (no
    // cardinality-changing pass has run yet), which every splice below
    // depends on.
    let (mut view, mut log) = project_messages(msgs, &base_policy(), &ReductionLog::default());
    debug_assert_eq!(view.len(), msgs.len());

    let gaps = compute_gaps(msgs.len(), &keep);
    let mut new_ids: Vec<String> = Vec::with_capacity(gaps.len());
    let mut ordinal = log.reductions.len();

    // Mint one `TurnsCleared` per gap, splicing from the LAST gap to the
    // FIRST so an earlier splice's cardinality shrink never invalidates a
    // later (still `msgs`-indexed) one.
    // ordinal is offset from log.reductions.len() (not 0-based), so a plain
    // enumerate() over gaps would produce the wrong ids — explicit counter is correct here.
    #[allow(clippy::explicit_counter_loop)]
    for &(first, last) in gaps.iter().rev() {
        let range = &msgs[first..=last];
        let (hash, range_bytes) = hash_turns_range(range)?;
        let (user, assistant, tool) = count_roles(range);
        let id = make_id(ordinal, &hash);
        ordinal += 1;
        let summary = format!(
            "turns {first}..{} cleared by handoff ({} messages: {user} user, {assistant} \
             assistant, {tool} tool; {}B) — full turns in session sidecar",
            last + 1,
            format_commas(range.len()),
            format_commas(range_bytes),
        );
        let placeholder = stub::format(stub::Kind::TurnsCleared, &id, &summary);

        // Any per-message reduction step 1 minted inside this gap is now
        // subsumed by the single spanning placeholder (mirrors the existing
        // A10 pass's own subsumption rule) — `invert` restores the WHOLE
        // range straight from the sidecar regardless.
        log.reductions
            .retain(|r| !(r.ptr.addr.index >= first && r.ptr.addr.index <= last));

        let reduction = Reduction {
            id: id.clone(),
            kind: ReductionKind::TurnsCleared {
                first,
                last,
                summary: None,
            },
            ptr: SidecarPtr {
                addr: MessageAddr {
                    index: first,
                    role: range[0].role,
                },
                span: None,
                content_hash: hash,
            },
            placeholder,
        };

        let mut stub_msg = ChatMessage::system(reduction.placeholder.clone());
        set_reduction_id(&mut stub_msg, &reduction.id);
        view.splice(first..=last, std::iter::once(stub_msg));

        log.reductions.push(reduction);
        new_ids.push(id);
    }
    new_ids.reverse(); // restore chronological (address) order

    let total_cleared: usize = gaps.iter().map(|&(f, l)| l - f + 1).sum();
    let (objective_text, objective_source) =
        resolve_objective(msgs, objective, draft_objective, summarizer);
    let banner = format_banner(objective_text.as_deref(), &new_ids, total_cleared);

    // Banner/objective: view-only, folded into the leading system-role
    // message (merged if the CANONICAL session genuinely starts with one —
    // checked against `msgs`, never `view`, since `view[0]` could otherwise
    // be a `TurnsCleared` gap placeholder that also happens to be
    // system-role and must never be contaminated with banner text) — NEVER
    // recorded as a `Reduction`, so it can never reach the sidecar or an
    // export (both rebuild only from sidecar bytes, never from this view).
    // Index 0 being genuinely system-role in `msgs` also means index 0 is
    // unconditionally in the keep-set (the always-keep loop above), so
    // `view[0]` really is that same, unreduced message here.
    if msgs.first().map(|m| m.role) == Some(Role::System) {
        let existing = view[0].content.clone().unwrap_or_default();
        view[0].content = Some(if existing.is_empty() {
            banner
        } else {
            format!("{banner}\n\n{existing}")
        });
    } else {
        view.insert(0, ChatMessage::system(banner));
    }

    Ok(HandoffResult {
        view,
        log,
        kept_indices,
        gap_ids: new_ids,
        objective_source,
        objective_text,
    })
}