venice-cli 0.83.44__tar.gz → 0.83.45__tar.gz

{venice_cli-0.83.44 → venice_cli-0.83.45}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: venice-cli
-Version: 0.83.44
+Version: 0.83.45
 Summary: A stdlib-only Python CLI for the Venice.ai API: audio, video, images, chat, and embeddings.
 Project-URL: Homepage, https://github.com/gobha-me/venice-cli
 Project-URL: Repository, https://github.com/gobha-me/venice-cli
@@ -679,6 +679,8 @@ catalog), `/models` (list the available models, marking the current and the
 default), `/auto` and `/manual` (toggle auto-accepting paid/side-effecting tool
 calls for following turns), `/compact [N]` (summarize older history into one
 message, keeping the last `N` turns verbatim),
+`/context list [CURSOR]` (list archived evidence metadata) and
+`/context read ID [OFFSET]` (read up to 32 KiB of an exact archived message),
 `/cost` (this session's estimated spend so far, with the active model's
 current-run cache hit rate on the same line; `--session-max-spend` adds a
 cap), `/usage` (a token + cost breakdown for the session, keeping the
@@ -717,9 +719,19 @@ older prefix into one synthetic message once the prompt crosses
 the last `--compact-keep-turns` turns (default 10) verbatim. The trigger uses
 the server-reported `usage.prompt_tokens` when a turn provides it (falling
 back to a chars-per-token estimate otherwise), so it fires on the real prompt
-size rather than a guess. Compaction is best-effort — a failed summarization
-call leaves the history untouched — and never orphans a tool result from its
-assistant turn. It's off by default because it costs a summarization call.
+size rather than a guess. `--compact-loss-policy aggressive|evidence` controls
+what happens to the summarized prefix. Chat defaults to `aggressive`, preserving
+the original behavior. Code defaults to `evidence`: every removed user message,
+assistant tool call (including arguments), and tool result is copied exactly into
+the private session envelope before the live history is replaced. The model gets
+a bounded index plus the read-only `venice_context_archive` tool; operators can use
+the `/context` commands above even in a plain REPL. The archive is capped at 512
+entries and 8 MiB. If the next compaction would cross either cap, it is refused
+before the summary API call and both history and archive remain unchanged. Reads
+are paged at 32 KiB and list pages at 50 entries. Compaction is otherwise
+best-effort — a failed or empty summarization leaves both stores untouched — and
+never orphans a tool result from its assistant turn. It's off by default because
+it costs a summarization call.
 
 #### Sessions
 
@@ -728,7 +740,11 @@ each turn to `~/.config/venice/sessions/<id>.json` (mode 0600;
 `$VENICE_SESSIONS_DIR` overrides the location). Unlike a bare `/save` transcript,
 a session travels with its **settings** — model, system prompt, generation
 parameters, `max-tool-calls`, the `venice code` sandbox root, and the running
-token/cost usage — so resuming restores the whole context, not just the messages.
+token/cost usage — plus any bounded exact context archive — so resuming restores
+the whole context, not just the messages. Session envelope v2 adds
+`context_archive` plus the structural count of authoritative leading system
+messages; v1 envelopes remain readable, conservatively preserve their complete
+leading system prefix, and resume with an empty archive.
 The API key is never written to a session.
 
 `venice code` also assigns each session an opaque `prompt_cache_key`, sent as an
@@ -1598,6 +1614,7 @@ jq '.usage.billed_total' ~/.config/venice/sessions/<id>.json
 | `venice_scout` | delegate a read-only investigation to a disposable subagent with a fresh context; returns a structured report so exploration doesn't pollute the main context — **opt-in with `--scout`** (see [Scout subagent](#scout-subagent---scout)) | no |
 | `venice_web_search` | search the web to **discover** documentation you don't have a URL for; returns a short answer + cited URLs (billed, but bounded by the tool-call budget) — **opt-in with `--web-search`** (see [Web search](#web-search---web-search)) | no |
 | `venice_review` | hand the current diff to a **cold-context reviewer** — a disposable subagent with a fresh context, read-only tools and (where the catalog allows) a different model — and get back defects with `file:line` + a repro. Findings only: it approves and certifies nothing — **opt-in with `--review`** (see [Reviewer rail](#reviewer-rail---review)) | no |
+| `venice_context_archive` | list bounded metadata or page through exact messages removed by evidence-preserving compaction; current session only, with no filesystem, network, or process access | no |
 
 **Safety.** Every filesystem path is resolved and confined to the **writable roots** —
 the startup root (default: cwd, or `--root` / `$VENICE_CODE_ROOT`) plus any added with
@@ -1659,6 +1676,7 @@ external diff helpers. Use the confirmed `run` tool for other Git forms.
 | `--review-model MODEL` | model for `--review` (default: a function-calling model from a **different family** than the coding model; falls back to the coding model with a warning); config `defaults.code.review_model` |
 | `--review-rounds N` | passes `venice_review` makes over the same diff (default **1**, max 3); config `defaults.code.review_rounds` |
 | `--auto-compact` | summarize older history once the prompt crosses `--compact-threshold` tokens (default 100 000), keeping the last `--compact-keep-turns` turns (default 10); long runs stay in-context |
+| `--compact-loss-policy aggressive\|evidence` | discard summarized messages or retain their exact JSON in the bounded private session archive; default **evidence** for code and **aggressive** for chat; config `defaults.code.compact_loss_policy` / `defaults.chat.compact_loss_policy` |
 | `--cache-guard off\|warn\|stop` | react when a cache-priced model explicitly reports zero cached tokens after the cold first API call and a 2,000-token prompt; default **warn**, config `defaults.code.cache_guard` |
 | `-i`, `--json`, `--model`, `--system` | interactive REPL · JSON envelope · model · extra system instructions |
 | `--persona NAME` | load `~/.config/venice/personas/NAME.md` as the system prompt at launch (`/persona` in the REPL) |
@@ -1677,7 +1695,8 @@ model and a sane `--max-tool-calls` when running unattended.
 
 Per-flag config defaults live under `defaults.code.*` (e.g. `model`, `root`, `auto`,
 `assets`, `scout`, `spawn`, `spawn_max_spend`, `subagent_max_tokens`, `planner`,
-`max_tool_calls`, `review`, `review_model`, `review_rounds`, `cache_guard`).
+`max_tool_calls`, `review`, `review_model`, `review_rounds`, `cache_guard`,
+`compact_loss_policy`).
 
 #### Scout subagent (`--scout`)
 

{venice_cli-0.83.44 → venice_cli-0.83.45}/README.md

@@ -638,6 +638,8 @@ catalog), `/models` (list the available models, marking the current and the
 default), `/auto` and `/manual` (toggle auto-accepting paid/side-effecting tool
 calls for following turns), `/compact [N]` (summarize older history into one
 message, keeping the last `N` turns verbatim),
+`/context list [CURSOR]` (list archived evidence metadata) and
+`/context read ID [OFFSET]` (read up to 32 KiB of an exact archived message),
 `/cost` (this session's estimated spend so far, with the active model's
 current-run cache hit rate on the same line; `--session-max-spend` adds a
 cap), `/usage` (a token + cost breakdown for the session, keeping the
@@ -676,9 +678,19 @@ older prefix into one synthetic message once the prompt crosses
 the last `--compact-keep-turns` turns (default 10) verbatim. The trigger uses
 the server-reported `usage.prompt_tokens` when a turn provides it (falling
 back to a chars-per-token estimate otherwise), so it fires on the real prompt
-size rather than a guess. Compaction is best-effort — a failed summarization
-call leaves the history untouched — and never orphans a tool result from its
-assistant turn. It's off by default because it costs a summarization call.
+size rather than a guess. `--compact-loss-policy aggressive|evidence` controls
+what happens to the summarized prefix. Chat defaults to `aggressive`, preserving
+the original behavior. Code defaults to `evidence`: every removed user message,
+assistant tool call (including arguments), and tool result is copied exactly into
+the private session envelope before the live history is replaced. The model gets
+a bounded index plus the read-only `venice_context_archive` tool; operators can use
+the `/context` commands above even in a plain REPL. The archive is capped at 512
+entries and 8 MiB. If the next compaction would cross either cap, it is refused
+before the summary API call and both history and archive remain unchanged. Reads
+are paged at 32 KiB and list pages at 50 entries. Compaction is otherwise
+best-effort — a failed or empty summarization leaves both stores untouched — and
+never orphans a tool result from its assistant turn. It's off by default because
+it costs a summarization call.
 
 #### Sessions
 
@@ -687,7 +699,11 @@ each turn to `~/.config/venice/sessions/<id>.json` (mode 0600;
 `$VENICE_SESSIONS_DIR` overrides the location). Unlike a bare `/save` transcript,
 a session travels with its **settings** — model, system prompt, generation
 parameters, `max-tool-calls`, the `venice code` sandbox root, and the running
-token/cost usage — so resuming restores the whole context, not just the messages.
+token/cost usage — plus any bounded exact context archive — so resuming restores
+the whole context, not just the messages. Session envelope v2 adds
+`context_archive` plus the structural count of authoritative leading system
+messages; v1 envelopes remain readable, conservatively preserve their complete
+leading system prefix, and resume with an empty archive.
 The API key is never written to a session.
 
 `venice code` also assigns each session an opaque `prompt_cache_key`, sent as an
@@ -1557,6 +1573,7 @@ jq '.usage.billed_total' ~/.config/venice/sessions/<id>.json
 | `venice_scout` | delegate a read-only investigation to a disposable subagent with a fresh context; returns a structured report so exploration doesn't pollute the main context — **opt-in with `--scout`** (see [Scout subagent](#scout-subagent---scout)) | no |
 | `venice_web_search` | search the web to **discover** documentation you don't have a URL for; returns a short answer + cited URLs (billed, but bounded by the tool-call budget) — **opt-in with `--web-search`** (see [Web search](#web-search---web-search)) | no |
 | `venice_review` | hand the current diff to a **cold-context reviewer** — a disposable subagent with a fresh context, read-only tools and (where the catalog allows) a different model — and get back defects with `file:line` + a repro. Findings only: it approves and certifies nothing — **opt-in with `--review`** (see [Reviewer rail](#reviewer-rail---review)) | no |
+| `venice_context_archive` | list bounded metadata or page through exact messages removed by evidence-preserving compaction; current session only, with no filesystem, network, or process access | no |
 
 **Safety.** Every filesystem path is resolved and confined to the **writable roots** —
 the startup root (default: cwd, or `--root` / `$VENICE_CODE_ROOT`) plus any added with
@@ -1618,6 +1635,7 @@ external diff helpers. Use the confirmed `run` tool for other Git forms.
 | `--review-model MODEL` | model for `--review` (default: a function-calling model from a **different family** than the coding model; falls back to the coding model with a warning); config `defaults.code.review_model` |
 | `--review-rounds N` | passes `venice_review` makes over the same diff (default **1**, max 3); config `defaults.code.review_rounds` |
 | `--auto-compact` | summarize older history once the prompt crosses `--compact-threshold` tokens (default 100 000), keeping the last `--compact-keep-turns` turns (default 10); long runs stay in-context |
+| `--compact-loss-policy aggressive\|evidence` | discard summarized messages or retain their exact JSON in the bounded private session archive; default **evidence** for code and **aggressive** for chat; config `defaults.code.compact_loss_policy` / `defaults.chat.compact_loss_policy` |
 | `--cache-guard off\|warn\|stop` | react when a cache-priced model explicitly reports zero cached tokens after the cold first API call and a 2,000-token prompt; default **warn**, config `defaults.code.cache_guard` |
 | `-i`, `--json`, `--model`, `--system` | interactive REPL · JSON envelope · model · extra system instructions |
 | `--persona NAME` | load `~/.config/venice/personas/NAME.md` as the system prompt at launch (`/persona` in the REPL) |
@@ -1636,7 +1654,8 @@ model and a sane `--max-tool-calls` when running unattended.
 
 Per-flag config defaults live under `defaults.code.*` (e.g. `model`, `root`, `auto`,
 `assets`, `scout`, `spawn`, `spawn_max_spend`, `subagent_max_tokens`, `planner`,
-`max_tool_calls`, `review`, `review_model`, `review_rounds`, `cache_guard`).
+`max_tool_calls`, `review`, `review_model`, `review_rounds`, `cache_guard`,
+`compact_loss_policy`).
 
 #### Scout subagent (`--scout`)
 

venice_cli-0.83.45/src/venice/__init__.py

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

{venice_cli-0.83.44 → venice_cli-0.83.45}/src/venice/commands/_agent.py

@@ -3779,6 +3779,8 @@ def run_loop(
     oai_tools = to_openai_tools(tools)
     dispatch = dispatch_map(tools)
     runtime = _ToolRuntime(model=model, models=models)
+    if budget is not None and budget.protected_system_messages is None:
+        budget.protected_system_messages = _compact.leading_system_count(messages)
     calls_made = 0
     gate = {"auto": bool(yes)}  # mutable so an `a`/`all` confirm flips the run to auto
     # #82: the per-tool timing sink, bound ONCE so both dispatch paths -- and every pool
@@ -3860,6 +3862,9 @@ def run_loop(
             on_compact=lambda b, a: _progress(
                 f"(auto-compacted history: {b} -> {a} messages)", enabled=show,
             ),
+            on_blocked=lambda reason: print(
+                f"auto-compaction refused: {reason}", file=sys.stderr,
+            ),
             ledger=ledger,  # #99: log the event; #101: and bill the summary call
         )
         _t0 = time.monotonic()
@@ -3960,6 +3965,9 @@ def run_loop(
                 on_compact=lambda b, a: _progress(
                     f"(auto-compacted history: {b} -> {a} messages)", enabled=show,
                 ),
+                on_blocked=lambda reason: print(
+                    f"auto-compaction refused: {reason}", file=sys.stderr,
+                ),
                 ledger=ledger,  # #99
             )
             return _force_final(

{venice_cli-0.83.44 → venice_cli-0.83.45}/src/venice/commands/_compact.py

@@ -50,7 +50,7 @@ import time
 from dataclasses import dataclass
 from typing import List, Optional, Tuple
 
-from . import _openai
+from . import _context_archive, _openai
 
 # Rough chars-per-token for English/code text. Deliberately conservative
 # (overestimate tokens) so the fallback triggers compaction a little early
@@ -64,6 +64,7 @@ SUMMARY_MAX_TOKENS = 1024
 
 DEFAULT_THRESHOLD_TOKENS = 100_000
 DEFAULT_KEEP_TURNS = 10
+LOSS_POLICY_CHOICES = ("aggressive", "evidence")
 
 _SUMMARY_PREFIX = "[Summary of earlier conversation]"
 _INSTRUCT = (
@@ -124,6 +125,9 @@ class Budget:
     threshold_tokens: int = DEFAULT_THRESHOLD_TOKENS
     keep_turns: int = DEFAULT_KEEP_TURNS
     last_prompt_tokens: Optional[int] = None
+    loss_policy: str = "aggressive"
+    archive: Optional[_context_archive.ContextArchive] = None
+    protected_system_messages: Optional[int] = None
 
     def observe(self, usage) -> None:
         """Record prompt tokens from a response's `usage` (dict or SDK obj)."""
@@ -150,7 +154,7 @@ class Budget:
         return estimate_tokens(messages) >= self.threshold_tokens
 
 
-def budget_from_args(args) -> Optional["Budget"]:
+def budget_from_args(args, archive=None) -> Optional["Budget"]:
     """The auto-compact Budget for a parsed-args namespace, or None when it
     isn't opted into (#48).
 
@@ -168,6 +172,8 @@ def budget_from_args(args) -> Optional["Budget"]:
         keep_turns=(
             getattr(args, "compact_keep_turns", None) or DEFAULT_KEEP_TURNS
         ),
+        loss_policy=getattr(args, "compact_loss_policy", None) or "aggressive",
+        archive=archive,
     )
 
 
@@ -212,8 +218,16 @@ def _groups(messages: List[dict]) -> List[List[dict]]:
     return groups
 
 
+def leading_system_count(messages: List[dict]) -> int:
+    """Count the contiguous authoritative/generated system prefix."""
+    count = 0
+    while count < len(messages) and messages[count].get("role") == "system":
+        count += 1
+    return count
+
+
 def split_for_compaction(
-    messages: List[dict], keep_turns: int
+    messages: List[dict], keep_turns: int, protected_system_messages: Optional[int] = None
 ) -> Optional[Tuple[List[dict], List[dict]]]:
     """Split history into (prefix to summarize, tail to keep verbatim).
 
@@ -224,14 +238,21 @@ def split_for_compaction(
     """
     if keep_turns < 1:
         keep_turns = 1
-    sys_end = 0
-    while sys_end < len(messages) and messages[sys_end].get("role") == "system":
-        sys_end += 1
-    tail_groups = _groups(messages[sys_end:])
+    leading_systems = leading_system_count(messages)
+    # None is the conservative compatibility path: every leading system
+    # message is authoritative. Session-aware callers persist the exact count,
+    # which lets later generated summary/index messages be replaced without
+    # classifying authority from forgeable content text.
+    if protected_system_messages is None:
+        sys_end = leading_systems
+    else:
+        sys_end = min(max(0, protected_system_messages), leading_systems)
+    generated_end = leading_systems
+    tail_groups = _groups(messages[generated_end:])
     if len(tail_groups) <= keep_turns:
         return None
     cut = len(tail_groups) - keep_turns
-    prefix: List[dict] = []
+    prefix: List[dict] = list(messages[sys_end:generated_end])
     for g in tail_groups[:cut]:
         prefix.extend(g)
     tail: List[dict] = []
@@ -283,6 +304,9 @@ def compact_messages(
     ledger=None,
     budget: Optional[Budget] = None,
     trigger: str = "auto",
+    loss_policy: str = "aggressive",
+    archive: Optional[_context_archive.ContextArchive] = None,
+    protected_system_messages: Optional[int] = None,
 ) -> bool:
     """Summarize the older prefix in place; keep system + last `keep_turns`.
 
@@ -311,12 +335,28 @@ def compact_messages(
     history it now describes -- i.e. re-firing compaction immediately, a sawtooth #99's
     trace would show and nothing would prevent.
     """
-    split = split_for_compaction(messages, keep_turns)
+    split = split_for_compaction(
+        messages, keep_turns, protected_system_messages=protected_system_messages
+    )
     if split is None:
         return False
     prefix, tail = split
     sys_msgs = messages[: len(messages) - len(prefix) - len(tail)]
 
+    # Evidence mode refuses before spending a summarization call if the exact
+    # removed messages cannot fit. Staging is side-effect-free; commit happens
+    # only after a usable summary exists, alongside the live-history rewrite.
+    staged = []
+    if loss_policy == "evidence":
+        if archive is None:
+            return False
+        archive.last_error = None
+        try:
+            staged = archive.stage(prefix)
+        except _context_archive.ArchiveError as e:
+            archive.last_error = str(e)
+            return False
+
     # #128: compaction is a deliberately fresh summarization conversation. Reusing
     # the parent session's routing identity would mix unrelated prefixes on one cache
     # affinity key; preserve all other generation/Venice parameters while stripping it.
@@ -366,7 +406,11 @@ def compact_messages(
     # lie in the artifact that exists to stop one.
     est_before = estimate_tokens(messages)
     msgs_before = len(messages)
-    messages[:] = sys_msgs + [synthetic_message(summary)] + tail
+    replacement = sys_msgs + [synthetic_message(summary)]
+    if loss_policy == "evidence":
+        archive.commit(staged)
+        replacement.append(archive.live_index_message())
+    messages[:] = replacement + tail
     if ledger is not None:
         ledger.record_compaction({
             "trigger": trigger,
@@ -411,7 +455,7 @@ def compact_messages(
 
 def maybe_compact(oai, model: str, messages: List[dict],
                   budget: Optional[Budget], base_kwargs: Optional[dict] = None,
-                  on_compact=None, ledger=None) -> bool:
+                  on_compact=None, on_blocked=None, ledger=None) -> bool:
     """Compact `messages` in place when `budget` says they're over budget.
 
     The shared gate for every compaction site (`run_loop`'s per-turn check, its
@@ -433,7 +477,12 @@ def maybe_compact(oai, model: str, messages: List[dict],
         oai, model, messages,
         keep_turns=budget.keep_turns, base_kwargs=base_kwargs,
         ledger=ledger, budget=budget, trigger="auto",
+        loss_policy=budget.loss_policy, archive=budget.archive,
+        protected_system_messages=budget.protected_system_messages,
     ):
+        if (on_blocked is not None and budget.archive is not None
+                and budget.archive.last_error):
+            on_blocked(budget.archive.last_error)
         return False
     if on_compact is not None:
         on_compact(before, len(messages))

venice_cli-0.83.45/src/venice/commands/_context_archive.py

@@ -0,0 +1,283 @@
+"""Bounded, lossless local archive for evidence-preserving compaction (#74)."""
+from __future__ import annotations
+
+import copy
+import hashlib
+import json
+from dataclasses import dataclass, field
+from typing import List, Optional
+
+
+MAX_ARCHIVE_BYTES = 8 * 1024 * 1024
+MAX_ARCHIVE_ENTRIES = 512
+MAX_LIST_ENTRIES = 50
+MAX_READ_BYTES = 32 * 1024
+LIVE_INDEX_ENTRIES = 32
+EXCERPT_CHARS = 160
+
+
+class ArchiveError(ValueError):
+    """An archive envelope is malformed or a capacity boundary was crossed."""
+
+
+def _canonical(message: dict) -> str:
+    try:
+        return json.dumps(
+            message, ensure_ascii=False, sort_keys=True, separators=(",", ":"),
+            allow_nan=False,
+        )
+    except (TypeError, ValueError) as e:
+        raise ArchiveError(f"archived message is not finite JSON: {e}") from None
+
+
+def _digest(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _excerpt(text: str, *, tail: bool = False) -> str:
+    value = text[-EXCERPT_CHARS:] if tail else text[:EXCERPT_CHARS]
+    return value.replace("\n", "\\n")
+
+
+def _metadata(entry: dict) -> dict:
+    result = {
+        "id": entry["id"],
+        "role": entry["role"],
+        "chars": entry["chars"],
+        "sha256": entry["sha256"],
+        "head": entry["head"],
+        "tail": entry["tail"],
+    }
+    if entry.get("name"):
+        result["name"] = entry["name"]
+    return result
+
+
+def _bounded_utf8_slice(text: str, offset: int) -> str:
+    """Return the longest char-aligned slice no larger than MAX_READ_BYTES."""
+    lo, hi = offset, len(text)
+    while lo < hi:
+        mid = (lo + hi + 1) // 2
+        if len(text[offset:mid].encode("utf-8")) <= MAX_READ_BYTES:
+            lo = mid
+        else:
+            hi = mid - 1
+    return text[offset:lo]
+
+
+@dataclass
+class ContextArchive:
+    """A bounded collection of exact, canonicalized archived messages."""
+
+    entries: List[dict] = field(default_factory=list)
+    last_error: Optional[str] = None
+
+    @classmethod
+    def from_envelope(cls, raw) -> "ContextArchive":
+        if raw is None:
+            return cls()
+        if not isinstance(raw, list):
+            raise ArchiveError("context_archive must be a JSON list")
+        if len(raw) > MAX_ARCHIVE_ENTRIES:
+            raise ArchiveError(
+                f"context_archive exceeds {MAX_ARCHIVE_ENTRIES} entries"
+            )
+        validated = []
+        seen = set()
+        for index, item in enumerate(raw, 1):
+            if not isinstance(item, dict) or not isinstance(item.get("message"), dict):
+                raise ArchiveError(f"context_archive entry {index} is malformed")
+            message = item["message"]
+            if not isinstance(message.get("role"), str):
+                raise ArchiveError(f"context_archive entry {index} has no role")
+            text = _canonical(message)
+            entry_id = item.get("id")
+            expected_id = f"ctx-{index:06d}"
+            if entry_id != expected_id:
+                raise ArchiveError(f"context_archive entry {index} has an invalid id")
+            if entry_id in seen:
+                raise ArchiveError(f"context_archive entry {index} repeats id {entry_id}")
+            seen.add(entry_id)
+            expected = cls._entry(entry_id, message, text)
+            for key in ("sha256", "chars", "role", "head", "tail"):
+                if item.get(key) != expected[key]:
+                    raise ArchiveError(
+                        f"context_archive entry {entry_id} has invalid {key}"
+                    )
+            if item.get("name") != expected.get("name"):
+                raise ArchiveError(
+                    f"context_archive entry {entry_id} has invalid name"
+                )
+            validated.append(expected)
+        total = len(_canonical(validated).encode("utf-8"))
+        if total > MAX_ARCHIVE_BYTES:
+            raise ArchiveError(f"context_archive exceeds {MAX_ARCHIVE_BYTES} bytes")
+        return cls(validated)
+
+    @staticmethod
+    def _entry(entry_id: str, message: dict, text: Optional[str] = None) -> dict:
+        text = _canonical(message) if text is None else text
+        entry = {
+            "id": entry_id,
+            "role": message["role"],
+            "chars": len(text),
+            "sha256": _digest(text),
+            "head": _excerpt(text),
+            "tail": _excerpt(text, tail=True),
+            "message": copy.deepcopy(message),
+        }
+        name = message.get("name")
+        if isinstance(name, str) and name:
+            entry["name"] = name
+        elif message.get("role") == "assistant":
+            calls = message.get("tool_calls")
+            if isinstance(calls, list):
+                names = []
+                for call in calls:
+                    fn = call.get("function") if isinstance(call, dict) else None
+                    if isinstance(fn, dict) and isinstance(fn.get("name"), str):
+                        names.append(fn["name"])
+                if names:
+                    entry["name"] = ",".join(names)
+        return entry
+
+    @property
+    def bytes_used(self) -> int:
+        return len(_canonical(self.entries).encode("utf-8"))
+
+    def stage(self, messages: List[dict]) -> List[dict]:
+        """Build entries and enforce both caps without changing the archive."""
+        staged = []
+        for message in messages:
+            if not isinstance(message, dict) or not isinstance(message.get("role"), str):
+                raise ArchiveError("message selected for archival is malformed")
+            text = _canonical(message)
+            entry_id = f"ctx-{len(self.entries) + len(staged) + 1:06d}"
+            staged.append(self._entry(entry_id, message, text))
+        count = len(self.entries) + len(staged)
+        if count > MAX_ARCHIVE_ENTRIES:
+            raise ArchiveError(
+                f"evidence archive full: compaction needs {count} entries "
+                f"(limit {MAX_ARCHIVE_ENTRIES})"
+            )
+        used = len(_canonical(self.entries + staged).encode("utf-8"))
+        if used > MAX_ARCHIVE_BYTES:
+            raise ArchiveError(
+                f"evidence archive full: compaction needs {used} bytes "
+                f"(limit {MAX_ARCHIVE_BYTES})"
+            )
+        return staged
+
+    def commit(self, staged: List[dict]) -> None:
+        self.entries.extend(staged)
+        self.last_error = None
+
+    def clear(self) -> None:
+        self.entries.clear()
+        self.last_error = None
+
+    def to_envelope(self) -> list:
+        return copy.deepcopy(self.entries)
+
+    def list_page(self, cursor: int = 0, limit: int = MAX_LIST_ENTRIES) -> dict:
+        if not isinstance(cursor, int) or isinstance(cursor, bool) or cursor < 0:
+            raise ArchiveError("cursor must be a non-negative integer")
+        if not isinstance(limit, int) or isinstance(limit, bool) or not 1 <= limit <= MAX_LIST_ENTRIES:
+            raise ArchiveError(f"limit must be between 1 and {MAX_LIST_ENTRIES}")
+        page = self.entries[cursor:cursor + limit]
+        end = cursor + len(page)
+        return {
+            "entries": [_metadata(e) for e in page],
+            "cursor": cursor,
+            "next_cursor": end if end < len(self.entries) else None,
+            "total": len(self.entries),
+            "bytes": self.bytes_used,
+        }
+
+    def read(self, entry_id: str, offset: int = 0) -> dict:
+        if not isinstance(entry_id, str):
+            raise ArchiveError("entry_id must be a string")
+        if not isinstance(offset, int) or isinstance(offset, bool) or offset < 0:
+            raise ArchiveError("offset must be a non-negative integer")
+        entry = next((e for e in self.entries if e["id"] == entry_id), None)
+        if entry is None:
+            raise ArchiveError(f"unknown archive entry {entry_id!r}")
+        text = _canonical(entry["message"])
+        if offset > len(text):
+            raise ArchiveError(f"offset {offset} exceeds entry length {len(text)}")
+        content = _bounded_utf8_slice(text, offset)
+        end = offset + len(content)
+        return {
+            "id": entry_id,
+            "sha256": entry["sha256"],
+            "offset": offset,
+            "content": content,
+            "next_offset": end if end < len(text) else None,
+            "complete": end >= len(text),
+            "chars": len(text),
+        }
+
+    def live_index_message(self) -> dict:
+        newest = self.entries[-LIVE_INDEX_ENTRIES:]
+        lines = [
+            "[Archived context evidence index]",
+            f"{len(self.entries)} exact message(s), {self.bytes_used} byte(s). "
+            "Use venice_context_archive to list metadata or read exact content.",
+        ]
+        older = len(self.entries) - len(newest)
+        if older:
+            lines.append(f"{older} older entry/entries are discoverable with list pagination.")
+        for entry in newest:
+            label = entry["role"]
+            if entry.get("name"):
+                label += f"/{entry['name']}"
+            lines.append(
+                f"{entry['id']} {label} {entry['chars']} chars "
+                f"sha256={entry['sha256']} head={entry['head']!r} tail={entry['tail']!r}"
+            )
+        return {"role": "system", "content": "\n".join(lines)}
+
+
+def archive_tool(archive: ContextArchive):
+    """Build the current-session, read-only archive lookup tool."""
+    from . import _agent
+
+    def invoke(args, *, confirm=False):
+        del confirm
+        try:
+            action = args.get("action")
+            if action == "list":
+                return {"status": "ok", **archive.list_page(
+                    args.get("cursor", 0), args.get("limit", MAX_LIST_ENTRIES)
+                )}
+            if action == "read":
+                return {"status": "ok", **archive.read(
+                    args.get("entry_id"), args.get("offset", 0)
+                )}
+            return {"status": "error", "message": "action must be list or read"}
+        except ArchiveError as e:
+            return {"status": "error", "message": str(e)}
+
+    return _agent.Tool(
+        name="venice_context_archive",
+        description=(
+            "Read evidence archived from earlier context compactions in this session. "
+            "List bounded metadata pages, then read exact canonical message JSON by id."
+        ),
+        parameters={
+            "type": "object",
+            "properties": {
+                "action": {"type": "string", "enum": ["list", "read"]},
+                "entry_id": {"type": "string"},
+                "cursor": {"type": "integer", "minimum": 0},
+                "offset": {"type": "integer", "minimum": 0},
+                "limit": {"type": "integer", "minimum": 1, "maximum": MAX_LIST_ENTRIES},
+            },
+            "required": ["action"],
+            "additionalProperties": False,
+        },
+        invoke=invoke,
+        paid=False,
+        category="context",
+        tags=("read",),
+    )