zai-cli 0.1.8__tar.gz → 0.1.9__tar.gz

{zai_cli-0.1.8 → zai_cli-0.1.9}/CHANGELOG.md

@@ -5,6 +5,26 @@ All notable changes to this project are documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and the project uses [Semantic Versioning](https://semver.org/).
 
+## [0.1.9] - 2026-06-30
+
+### Added
+
+- Added provider-neutral token estimation helpers and context usage reporting.
+- Added `zai context tokens`, `zai context summary`, interactive
+  `/context tokens`, and interactive `/context summary`.
+- Added interactive `/compact` to summarize older session history.
+- Added `zai session compact <name-or-id>` for saved sessions.
+- Added compacted-summary metadata to saved session payloads.
+
+### Changed
+
+- Automatic context compaction now uses configurable thresholds and prints a
+  transparent message when older history is summarized.
+- Context status now shows estimated token usage, estimated context limit,
+  remaining tokens, and compacted-summary availability.
+- Long-session summaries redact obvious API keys, bearer tokens, passwords, and
+  secret values before storage/display.
+
 ## [0.1.8] - 2026-06-29
 
 ### Added

{zai_cli-0.1.8/zai_cli.egg-info → zai_cli-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: zai-cli
-Version: 0.1.8
+Version: 0.1.9
 Summary: Your personal AI CLI — free, fast, and smart
 License-Expression: MIT
 Project-URL: Homepage, https://github.com/HumaizaNaz/zai_cli
@@ -506,6 +506,20 @@ Use `zai context` or `/context` to inspect the current folder, whether project
 memory exists, whether a repo-map cache is available, and how many conversation
 messages are loaded in the current interactive session.
 
+For token/context usage:
+
+```text
+zai context tokens
+zai context summary
+/context tokens
+/context summary
+/compact
+```
+
+`zai context tokens` and `/context tokens` show an approximate provider-neutral
+token estimate, the configured context limit, remaining tokens, and whether the
+session is approaching the compaction threshold.
+
 Project memory is separate from current model context. It is a small
 `.zai/project_memory.json` summary created with `zai memory refresh` or
 `/memory refresh`.
@@ -514,7 +528,10 @@ Repo maps are summaries/indexes used on demand for repository questions. They
 are not full source files loaded into every model call. If a file has not been
 read or indexed for the current task, treat it as not loaded yet.
 
-Token tracking and automatic long-session compaction are planned for `0.1.9`.
+For long interactive sessions, `/compact` summarizes older conversation and
+tool history so the active session can continue with less context pressure. The
+summary preserves the goal, decisions, recent work, commands/results where
+visible, and pending context in a compact form.
 
 All chat, workflow, utility, and agent requests use a model-aware context
 pipeline:
@@ -528,8 +545,9 @@ pipeline:
 - context usage uses a conservative shared token estimate, while provider
   response usage is retained where the SDK reports it.
 
-This keeps requests bounded, but it is not a replacement for future
-long-session token tracking and automatic compaction.
+This keeps requests bounded. Compaction is still approximate, so save important
+stable project facts explicitly with `/remember <fact>` or `zai memory remember
+<fact>`.
 
 ## Providers and fallback
 

{zai_cli-0.1.8 → zai_cli-0.1.9}/README.md

@@ -449,6 +449,20 @@ Use `zai context` or `/context` to inspect the current folder, whether project
 memory exists, whether a repo-map cache is available, and how many conversation
 messages are loaded in the current interactive session.
 
+For token/context usage:
+
+```text
+zai context tokens
+zai context summary
+/context tokens
+/context summary
+/compact
+```
+
+`zai context tokens` and `/context tokens` show an approximate provider-neutral
+token estimate, the configured context limit, remaining tokens, and whether the
+session is approaching the compaction threshold.
+
 Project memory is separate from current model context. It is a small
 `.zai/project_memory.json` summary created with `zai memory refresh` or
 `/memory refresh`.
@@ -457,7 +471,10 @@ Repo maps are summaries/indexes used on demand for repository questions. They
 are not full source files loaded into every model call. If a file has not been
 read or indexed for the current task, treat it as not loaded yet.
 
-Token tracking and automatic long-session compaction are planned for `0.1.9`.
+For long interactive sessions, `/compact` summarizes older conversation and
+tool history so the active session can continue with less context pressure. The
+summary preserves the goal, decisions, recent work, commands/results where
+visible, and pending context in a compact form.
 
 All chat, workflow, utility, and agent requests use a model-aware context
 pipeline:
@@ -471,8 +488,9 @@ pipeline:
 - context usage uses a conservative shared token estimate, while provider
   response usage is retained where the SDK reports it.
 
-This keeps requests bounded, but it is not a replacement for future
-long-session token tracking and automatic compaction.
+This keeps requests bounded. Compaction is still approximate, so save important
+stable project facts explicitly with `/remember <fact>` or `zai memory remember
+<fact>`.
 
 ## Providers and fallback
 

{zai_cli-0.1.8 → zai_cli-0.1.9}/tests/test_interactive.py

@@ -249,7 +249,13 @@ def test_interactive_context_and_providers_do_not_call_ai(tmp_path, monkeypatch,
                     with patch("zai.cli.interactive._connect_mcp_servers"):
                         with patch(
                             "zai.cli.interactive.InteractiveInput.prompt",
-                            side_effect=["/providers", "/context", EOFError()],
+                            side_effect=[
+                                "/providers",
+                                "/context",
+                                "/context tokens",
+                                "/context summary",
+                                EOFError(),
+                            ],
                         ):
                             with patch("zai.cli.interactive.run_agent") as run_agent:
                                 run_interactive("groq")
@@ -258,10 +264,57 @@ def test_interactive_context_and_providers_do_not_call_ai(tmp_path, monkeypatch,
     assert "Provider status" in output
     assert "Project context" in output
     assert "unread files are not loaded" in output
+    assert "Estimated tokens used" in output
+    assert "No compacted summary" in output
     assert "app.py is loaded" not in output
     run_agent.assert_not_called()
 
 
+def test_interactive_manual_compact_summarizes_history(tmp_path, monkeypatch, capsys):
+    monkeypatch.chdir(tmp_path)
+    prompts = [
+        "task one",
+        "task two",
+        "task three",
+        "task four",
+        "task five",
+        "/compact",
+        "/context summary",
+        EOFError(),
+    ]
+    with patch("zai.cli.interactive.has_available_provider", return_value=True):
+        with patch("zai.cli.interactive.fire_hook", return_value=True):
+            with patch("zai.cli.interactive.plugin_loader.load_all", return_value={}):
+                with patch("zai.cli.interactive.plugin_loader.get_errors", return_value={}):
+                    with patch("zai.cli.interactive._connect_mcp_servers"):
+                        with patch(
+                            "zai.cli.interactive.InteractiveInput.prompt",
+                            side_effect=prompts,
+                        ):
+                            with (
+                                patch(
+                                    "zai.cli.interactive.run_agent",
+                                    side_effect=[
+                                        "answer one",
+                                        "answer two",
+                                        "answer three",
+                                        "answer four",
+                                        "answer five",
+                                    ],
+                                ),
+                                patch(
+                                    "zai.cli.interactive.Confirm.ask",
+                                    return_value=False,
+                                ),
+                            ):
+                                run_interactive("groq")
+
+    output = capsys.readouterr().out
+    assert "Context compacted" in output
+    assert "Current compacted summary" in output
+    assert "task one" in output
+
+
 def test_interactive_offers_project_memory_after_agent_task(tmp_path, monkeypatch, capsys):
     from zai.core.project_memory import load_project_memory
 

{zai_cli-0.1.8 → zai_cli-0.1.9}/tests/test_settings_cli.py

@@ -149,9 +149,26 @@ def test_context_command_is_honest_about_unloaded_files(tmp_path, monkeypatch):
     assert "Project memory: missing" in result.output
     assert "Repo map/index: not loaded yet" in result.output
     assert "unread files are not loaded" in result.output
+    assert "Estimated tokens used" in result.output
     assert "app.py is loaded" not in result.output
 
 
+def test_context_tokens_and_summary_commands(tmp_path, monkeypatch):
+    app = settings_app()
+    monkeypatch.chdir(tmp_path)
+
+    tokens = CliRunner().invoke(app, ["context", "tokens"])
+    summary = CliRunner().invoke(app, ["context", "summary"])
+    bad = CliRunner().invoke(app, ["context", "bad"])
+
+    assert tokens.exit_code == 0
+    assert "Estimated tokens used" in tokens.output
+    assert "Compacted summary" in tokens.output
+    assert summary.exit_code == 0
+    assert "No compacted summary" in summary.output
+    assert "Usage: zai context" in bad.output
+
+
 def test_model_check_reports_valid_and_invalid_configuration():
     app = settings_app()
     runner = CliRunner()
@@ -408,6 +425,27 @@ def test_session_rename_delete_and_export():
     assert "Export failed" in export_failed.output
 
 
+def test_session_compact_routes_history():
+    from zai.providers.base import Message
+
+    app = settings_app()
+    history = [
+        Message(role="user", content=f"message {index}")
+        for index in range(12)
+    ]
+    info = {"name": "auth", "project_path": "project"}
+    with (
+        patch("zai.cli.settings.load_history", return_value=history),
+        patch("zai.cli.settings.get_session_info", return_value=info),
+        patch("zai.cli.settings.save_history") as save,
+    ):
+        result = CliRunner().invoke(app, ["session", "compact", "auth"])
+
+    assert result.exit_code == 0
+    assert "Session compacted" in result.output
+    save.assert_called_once()
+
+
 def test_undo_list_empty_and_populated():
     app = settings_app()
     runner = CliRunner()

zai_cli-0.1.9/tests/test_tokens.py

@@ -0,0 +1,57 @@
+from zai.core.compaction import manual_compact_messages
+from zai.core.tokens import (
+    compacted_summaries,
+    context_usage,
+    estimate_messages_tokens,
+    estimate_tokens,
+    redact_secrets,
+)
+from zai.providers.base import Message
+
+
+def test_estimate_tokens_is_stable_and_nonzero():
+    assert estimate_tokens("") == 0
+    assert estimate_tokens("hello world") >= 2
+    assert estimate_tokens("x" * 120) >= 40
+
+
+def test_context_usage_reports_thresholds():
+    messages = [Message(role="user", content="x" * 900)]
+    usage = context_usage(messages, context_limit=100)
+
+    assert usage.tokens_used == estimate_messages_tokens(messages)
+    assert usage.tokens_remaining == 0
+    assert usage.should_warn is True
+    assert usage.should_compact is True
+
+
+def test_secret_redaction_covers_common_patterns():
+    text = (
+        "OPENAI_API_KEY=sk-abcdefghijklmnopqrstuvwxyz "
+        "Authorization: Bearer abcdefghijklmnopqrstuvwxyz "
+        "password=hunter2"
+    )
+    redacted = redact_secrets(text)
+
+    assert "sk-abcdefghijklmnopqrstuvwxyz" not in redacted
+    assert "abcdefghijklmnopqrstuvwxyz" not in redacted
+    assert "hunter2" not in redacted
+    assert "[REDACTED_SECRET]" in redacted
+
+
+def test_manual_compaction_creates_summary_and_keeps_recent_messages():
+    messages = [
+        Message(role="user", content="initial goal"),
+        Message(role="assistant", content="decision made"),
+        Message(role="tool", content="api_key=sk-secretsecretsecret", tool_name="run"),
+    ]
+    messages.extend(Message(role="user", content=f"step {index}") for index in range(12))
+
+    compacted, summary = manual_compact_messages(messages, max_tokens=128_000, keep_recent=4)
+
+    assert summary is not None
+    assert "initial goal" in summary.content
+    assert "decision made" in summary.content
+    assert "sk-secretsecretsecret" not in summary.content
+    assert compacted[-1].content == "step 11"
+    assert compacted_summaries(compacted)

zai_cli-0.1.9/zai/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.9"

{zai_cli-0.1.8 → zai_cli-0.1.9}/zai/cli/interactive.py

@@ -19,6 +19,7 @@ from ..core.auth import (
 )
 from ..core.agent import plan_agent, run_agent, undo_last
 from ..core.commands import get_command_prompt, list_commands, load_commands
+from ..core.compaction import manual_compact_messages
 from ..core.hooks import fire as fire_hook
 from ..core.fallback import has_available_provider
 from ..core.context import ContextManager
@@ -56,7 +57,7 @@ console = Console()
 CORE_COMMANDS = {
     "help", "clear", "files", "diff", "undo", "plan", "test",
     "watch", "commit", "review", "fix", "explain", "feature",
-    "session", "resume", "model", "providers", "context", "memory", "remember",
+    "session", "resume", "model", "providers", "context", "compact", "memory", "remember",
     "forget", "commands", "auth", "setup", "exit", "quit",
 }
 
@@ -68,6 +69,9 @@ INTERACTIVE_COMMANDS = [
     ("/auth login <provider>", "Connect a provider"),
     ("/providers", "Show provider connection status"),
     ("/context", "Show loaded project context"),
+    ("/context tokens", "Show estimated context token usage"),
+    ("/context summary", "Show compacted context summary"),
+    ("/compact", "Summarize older session history now"),
     ("/exit", "Exit interactive mode"),
     ("/quit", "Exit interactive mode"),
     ("/clear", "Clear the terminal"),
@@ -187,6 +191,9 @@ def _show_commands() -> None:
         ("Setup", "/model <name>", "Switch model"),
         ("Setup", "/exit", "Exit interactive mode"),
         ("Project", "/context", "Show loaded project context"),
+        ("Project", "/context tokens", "Show estimated context token usage"),
+        ("Project", "/context summary", "Show compacted context summary"),
+        ("Project", "/compact", "Summarize older session history now"),
         ("Project", "/files", "List files in the current folder"),
         ("Project", "/diff", "Show git diff"),
         ("Project", "/review", "Review code"),
@@ -479,7 +486,8 @@ def run_interactive(model: str = None) -> None:
         border_style="cyan",
     ))
 
-    preferred = model or load_config()["default_model"]
+    config = load_config()
+    preferred = model or config["default_model"]
     add_project(Path(cwd).name, cwd)
     fire_hook("SessionStart", {"cwd": cwd, "files": visible})
     project_memory = load_project_memory(cwd)
@@ -552,8 +560,14 @@ def run_interactive(model: str = None) -> None:
     def remember_turn(user_content: str, assistant_content: str) -> None:
         session_context.add("user", user_content)
         session_context.add("assistant", assistant_content)
-        if session_context.is_near_limit():
+        if config.get("auto_compact", True) and session_context.is_near_limit(
+            float(config.get("compact_trigger_threshold", 0.85))
+        ):
             session_context.compress(preferred)
+            console.print(
+                "[yellow]Context compacted: older history summarized to keep "
+                "the session usable. Run /context summary to inspect it.[/yellow]"
+            )
         save_auto_history(history, cwd)
         append_recent_task(cwd, user_content[:200])
 
@@ -605,13 +619,35 @@ def run_interactive(model: str = None) -> None:
                 _run_auth_command(stripped)
             elif stripped == "/providers":
                 _show_auth_status()
-            elif stripped == "/context":
+            elif stripped in {"/context", "/context tokens", "/context summary"}:
                 messages = session_context.get_messages()
+                detail = "summary" if stripped == "/context summary" else "overview"
                 console.print(context_panel(
                     cwd,
                     message_count=len(messages),
                     pinned_count=sum(1 for item in messages if item.pinned),
+                    messages=messages,
+                    context_limit=session_context.max_tokens,
+                    detail=detail,
                 ))
+            elif stripped == "/compact":
+                before = len(history)
+                compacted, summary = manual_compact_messages(
+                    history,
+                    max_tokens=session_context.max_tokens,
+                )
+                session_context.replace_messages(compacted)
+                save_auto_history(history, cwd)
+                if summary:
+                    console.print(
+                        "[green]Context compacted:[/green] older history was "
+                        "summarized to keep the session usable. Run "
+                        "[cyan]/context summary[/cyan] to inspect it."
+                    )
+                else:
+                    console.print(
+                        f"[dim]Context already compact enough ({before} messages).[/dim]"
+                    )
             elif stripped in {"/exit", "/quit"}:
                 fire_hook("SessionEnd", {"cwd": cwd, "messages": len(history)})
                 console.print("\n[dim]Goodbye![/dim]")

{zai_cli-0.1.8 → zai_cli-0.1.9}/zai/cli/settings.py

@@ -40,10 +40,13 @@ from ..core.session import (
     delete_session,
     export_session,
     get_session_info,
+    load_history,
     list_sessions,
     rename_session,
+    save_history,
     search_sessions,
 )
+from ..core.compaction import manual_compact_messages
 from ..core.undo import (
     clear_actions,
     get_action,
@@ -431,9 +434,15 @@ def memory(
         )
 
 
-def context():
+def context(
+    action: str = typer.Argument("show", help="show, tokens, or summary"),
+):
     """Show what project context is currently visible to zai."""
-    console.print("\n".join(context_lines(".")), soft_wrap=True)
+    if action in {"show", "tokens", "summary"}:
+        detail = "summary" if action == "summary" else "overview"
+        console.print("\n".join(context_lines(".", detail=detail)), soft_wrap=True)
+    else:
+        console.print("[red]Usage: zai context [show|tokens|summary][/red]")
 
 
 def session(
@@ -507,6 +516,28 @@ def session(
                 console.print(f"[green]Session deleted:[/green] {name}")
             else:
                 console.print("[red]Session not found or identifier is ambiguous.[/red]")
+    elif action == "compact" and name:
+        history = load_history(name)
+        info = get_session_info(name)
+        if not history or not info:
+            console.print("[red]Session not found or identifier is ambiguous.[/red]")
+            return
+        compacted, summary = manual_compact_messages(
+            history,
+            max_tokens=128_000,
+        )
+        save_history(
+            compacted,
+            info["name"],
+            project_path=info.get("project_path"),
+        )
+        if summary:
+            console.print(
+                f"[green]Session compacted:[/green] {info['name']} "
+                f"({len(history)} -> {len(compacted)} messages)"
+            )
+        else:
+            console.print(f"[dim]Session already compact enough: {info['name']}[/dim]")
     elif action == "export" and name:
         exported = export_session(
             name,
@@ -525,6 +556,7 @@ def session(
         console.print(
             "[red]Usage: zai session list | show <name-or-id> | "
             "search <query> | rename <old> <new> | delete <name-or-id> | "
+            "compact <name-or-id> | "
             "export <name-or-id> --format md|json [--out path][/red]"
         )
 

{zai_cli-0.1.8 → zai_cli-0.1.9}/zai/cli/status.py

@@ -11,6 +11,11 @@ from ..config import get_api_key, get_model_config, get_models, load_config
 from ..core.auth import auth_status, get_auth_provider
 from ..core.project_memory import load_project_memory
 from ..core.repomap import _cache_path
+from ..core.tokens import (
+    compacted_summaries,
+    context_usage,
+    format_usage_lines,
+)
 
 LOCAL_PROVIDERS = {"ollama"}
 BEGINNER_PROVIDERS = {
@@ -140,12 +145,18 @@ def context_lines(
     *,
     message_count: int = 0,
     pinned_count: int = 0,
+    messages: list | None = None,
+    context_limit: int | None = None,
     recent_files: list[str] | None = None,
+    detail: str = "overview",
 ) -> list[str]:
     root = Path(cwd).resolve()
     memory = load_project_memory(root)
     repo_cache = _cache_path(root)
     recent_files = recent_files or []
+    messages = messages or []
+    usage = context_usage(messages, context_limit) if messages else None
+    summaries = compacted_summaries(messages)
     lines = [
         f"Folder: {root}",
         (
@@ -174,12 +185,39 @@ def context_lines(
             else "Recently touched files: not tracked yet"
         ),
         "Manually pinned files: not supported yet",
+    ]
+    if usage:
+        lines.extend(format_usage_lines(usage))
+        lines.append(
+            "Compacted summary: available"
+            if summaries
+            else "Compacted summary: none yet"
+        )
+        if usage.should_compact:
+            lines.append("Context status: compaction recommended")
+        elif usage.should_warn:
+            lines.append("Context status: approaching context limit")
+        else:
+            lines.append("Context status: OK")
+    else:
+        lines.append("Estimated tokens used: 0")
+        lines.append("Compacted summary: none yet")
+    if detail == "summary":
+        if summaries:
+            lines.append("")
+            lines.append("Current compacted summary:")
+            lines.append(summaries[-1])
+        else:
+            lines.append("No compacted summary has been created yet.")
+    lines.extend([
         (
             "Large repos are summarized/indexed on demand; unread files are "
             "not loaded into model context."
         ),
-        "Token tracking and automatic compaction are planned for 0.1.9.",
+        "Use /context tokens to inspect estimated context usage.",
+        "Use /compact to summarize older session history when a session gets long.",
     ]
+    )
     return lines
 
 
@@ -188,14 +226,20 @@ def context_panel(
     *,
     message_count: int = 0,
     pinned_count: int = 0,
+    messages: list | None = None,
+    context_limit: int | None = None,
     recent_files: list[str] | None = None,
+    detail: str = "overview",
 ) -> Panel:
     return Panel(
         "\n".join(context_lines(
             cwd,
             message_count=message_count,
             pinned_count=pinned_count,
+            messages=messages,
+            context_limit=context_limit,
             recent_files=recent_files,
+            detail=detail,
         )),
         title="[cyan]Project context[/cyan]",
         border_style="cyan",

{zai_cli-0.1.8 → zai_cli-0.1.9}/zai/config.py

@@ -22,6 +22,9 @@ DEFAULT_CONFIG = {
     "auth_credentials_store": "env",
     "show_token_count": True,
     "auto_fallback": True,
+    "auto_compact": True,
+    "compact_warning_threshold": 0.70,
+    "compact_trigger_threshold": 0.85,
 }
 
 MODELS = {

zai_cli-0.1.9/zai/core/compaction.py

@@ -0,0 +1,83 @@
+"""Manual session compaction helpers."""
+from __future__ import annotations
+
+from dataclasses import replace
+from datetime import datetime
+
+from ..providers.base import Message
+from .context import compact_messages
+from .tokens import COMPACTED_MARKER, redact_secrets
+
+SUMMARY_MAX_ITEMS = 28
+
+
+def _label(message: Message) -> str:
+    if message.role == "tool":
+        return f"TOOL {message.tool_name or 'result'}"
+    return message.role.upper()
+
+
+def build_compaction_summary(messages: list[Message]) -> Message:
+    """Create a deterministic, secret-redacted summary of older session state."""
+    lines = [
+        COMPACTED_MARKER,
+        f"Created: {datetime.now().isoformat(timespec='seconds')}",
+        "Retained session facts:",
+    ]
+    for message in messages[:SUMMARY_MAX_ITEMS]:
+        content = " ".join(redact_secrets(message.content).split())
+        if not content and message.tool_calls:
+            content = "Requested tools: " + ", ".join(
+                call.name for call in message.tool_calls
+            )
+        if not content:
+            continue
+        lines.append(f"- {_label(message)}: {content[:700]}")
+    return Message(role="user", content="\n".join(lines), pinned=True)
+
+
+def manual_compact_messages(
+    messages: list[Message],
+    *,
+    max_tokens: int,
+    keep_recent: int = 8,
+) -> tuple[list[Message], Message | None]:
+    """Summarize older messages now, keeping pinned and recent context."""
+    if len(messages) <= keep_recent:
+        return messages, None
+    pinned = [message for message in messages if message.pinned]
+    recent = messages[-keep_recent:]
+    recent_ids = {id(message) for message in recent}
+    pinned_ids = {id(message) for message in pinned}
+    older = [
+        message
+        for message in messages
+        if id(message) not in recent_ids and id(message) not in pinned_ids
+    ]
+    if not older:
+        return compact_messages(messages, max_tokens), None
+    summary = build_compaction_summary(older)
+    result = []
+    seen = set()
+    for message in [*pinned, summary, *recent]:
+        key = id(message)
+        if key not in seen:
+            result.append(message)
+            seen.add(key)
+    return compact_messages(result, max_tokens), summary
+
+
+def compacted_metadata_from_messages(messages: list[Message]) -> list[dict]:
+    metadata = []
+    for message in messages:
+        if COMPACTED_MARKER in message.content:
+            metadata.append({
+                "created_at": datetime.now().isoformat(timespec="seconds"),
+                "summary": redact_secrets(message.content),
+            })
+    return metadata
+
+
+def redact_message(message: Message) -> Message:
+    return replace(message, content=redact_secrets(message.content))
+