squeez 0.3.1

//! Auto-teach payload that documents squeez to the LLM consuming its output.
//!
//! Ships a hardcoded "memory protocol" + marker spec inside the response so
//! the calling LLM learns the rules of the system on first contact rather than
//! via configuration files.
//!
//! These constants are intentionally short — they live inside every status /
//! protocol response, so any bloat is paid on every call. Keep under ~1500
//! characters combined.

/// High-level protocol the LLM should follow when reading squeez output.
/// Five directives, plain English, no jargon.
pub const SQUEEZ_PROTOCOL: &str = "\
squeez memory protocol (read this once per session):

1. Output prefixed with `# squeez [...]` is a header line — it shows the
   compression intensity, token delta, and elapsed time. Not part of the
   command's actual output.
2. Lines containing `[squeez: identical to <hash> at bash#N — re-run with
   --no-squeez]` mean the command produced output that already appeared in
   call #N of this session. Do NOT re-run it; the result is unchanged.
3. Lines containing `[squeez: ~95% similar to <hash> at bash#N]` mean the
   output is near-identical to a prior call (whitespace, timestamps, or one
   edited line). Treat as the same content unless you specifically need the
   diff — re-run with --no-squeez to see verbatim.
4. Lines starting with `squeez:summary` are dense summaries replacing huge
   outputs. The original is in `~/.claude/squeez/sessions/{date}.jsonl`.
   Errors and the last 20 lines are always preserved verbatim.
5. The MCP tools `squeez_recent_calls`, `squeez_seen_files`,
   `squeez_seen_errors`, `squeez_session_summary`, `squeez_prior_summaries`
   let you query what this session and previous sessions have already touched.
   Use them BEFORE re-running expensive commands or asking the user to
   recall what changed.
";

/// Specification of the structured markers squeez may inject into output.
/// Designed to be greppable and unambiguous so the LLM can pattern-match.
pub const SQUEEZ_MARKERS_SPEC: &str = "\
squeez output markers:

* `# squeez [cmd] IN→OUT tokens (-N%) Tms [adaptive: Lite|Full|Ultra]`
    Header. IN/OUT are token estimates. `[adaptive: ...]` shows the chosen
    intensity (Full at <80% budget, Ultra at ≥80%, Lite when adaptive off).

* `[squeez: identical to <hash> at bash#N — re-run with --no-squeez]`
    Exact-hash redundancy hit. The output of this call exactly matches an
    earlier call within the last 16 commands.

* `[squeez: ~P% similar to <hash> at bash#N — re-run with --no-squeez]`
    Fuzzy redundancy hit (Jaccard ≥ 0.85 over trigram shingles). Whitespace,
    timestamps, or single-line edits don't break this match.

* `squeez:summary cmd=<short>` followed by `total_lines=N`,
  `unique_files=N`, optional `top_errors:`, `top_files:`,
  `test_summary=...`, `tail_preserved=N`, then the verbatim last N lines.
    Dense summary for outputs over the per-call line threshold.

* `# squeez hint: <path> already in context (Read tool, call #N)`
    Soft hint when `cat`/`head`/`tail`/`less`/`more`/`bat` is invoked on a
    file the Read tool has already loaded earlier in the session.
";

/// Combined payload returned by the MCP `squeez_protocol` tool and by
/// `squeez status --for-llm`. Single allocation, no formatting at call time.
pub fn full_payload() -> String {
    let mut s = String::with_capacity(SQUEEZ_PROTOCOL.len() + SQUEEZ_MARKERS_SPEC.len() + 2);
    s.push_str(SQUEEZ_PROTOCOL);
    s.push('\n');
    s.push_str(SQUEEZ_MARKERS_SPEC);
    s
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn protocol_is_nonempty() {
        assert!(SQUEEZ_PROTOCOL.len() > 200);
        assert!(SQUEEZ_MARKERS_SPEC.len() > 200);
    }

    #[test]
    fn full_payload_includes_both() {
        let p = full_payload();
        assert!(p.contains("squeez memory protocol"));
        assert!(p.contains("squeez output markers"));
    }

    #[test]
    fn payload_under_3kb() {
        // Hard ceiling so this never bloats unnoticed. Current size ~2.4 KB.
        // Bump deliberately if you add a documented marker; do not bump
        // because of phrasing creep.
        let n = full_payload().len();
        assert!(n < 3072, "payload too large: {} bytes", n);
    }

    #[test]
    fn payload_documents_all_six_mcp_tools() {
        let p = full_payload();
        for tool in [
            "squeez_recent_calls",
            "squeez_seen_files",
            "squeez_seen_errors",
            "squeez_session_summary",
            "squeez_prior_summaries",
        ] {
            assert!(p.contains(tool), "payload missing mention of {}", tool);
        }
    }
}