code-context-control 2.28.0__py3-none-any.whl

cli/tools/read.py

@@ -0,0 +1,224 @@
+"""c3_read — Surgical symbol/line extraction from files.
+Supports comma-separated paths with parallel extraction via ThreadPoolExecutor."""
+
+import json
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+from typing import Any
+
+from core import count_tokens
+
+
+def _coerce_list(val: Any) -> list[str] | None:
+    """Coerce symbols from string/JSON to list. MCP clients sometimes serialize lists as strings."""
+    if val is None:
+        return None
+    if isinstance(val, list):
+        return val
+    if isinstance(val, str):
+        val = val.strip()
+        if val.startswith("["):
+            try:
+                parsed = json.loads(val)
+                if isinstance(parsed, list):
+                    return [str(x) for x in parsed]
+            except (json.JSONDecodeError, ValueError):
+                pass
+        if val:
+            return [val]
+    return None
+
+
+def handle_read(file_path: str, symbols: Any = None, lines: Any = None,
+                include_docstrings: bool = True, svc=None, finalize=None) -> str:
+    symbols = _coerce_list(symbols)
+    # Multi-file dispatch (parallel)
+    if "," in file_path:
+        paths = [p.strip() for p in file_path.split(",") if p.strip()]
+        if len(paths) == 1:
+            return handle_read(paths[0], symbols=symbols, lines=lines,
+                               include_docstrings=include_docstrings,
+                               svc=svc, finalize=finalize)
+        # Nested ThreadPoolExecutor workers don't inherit MCP's request_context
+        # contextvar, so calling the real `finalize` inside a worker raises
+        # 'NoneType'.lifespan_context. Use a no-op in workers and run the real
+        # finalize once on the combined result (still on the outer to_thread,
+        # which does propagate contextvars).
+        def _worker_finalize(name, args, resp, summ, **kw):
+            return resp
+
+        results = {}
+        with ThreadPoolExecutor(max_workers=min(len(paths), 4)) as pool:
+            futures = {
+                pool.submit(handle_read, p, symbols, lines,
+                            include_docstrings, svc, _worker_finalize): p
+                for p in paths
+            }
+            for fut in as_completed(futures):
+                p = futures[fut]
+                try:
+                    results[p] = fut.result()
+                except Exception as e:
+                    results[p] = f"[read:error] {p}: {e}"
+        combined = "\n\n".join(results[p] for p in paths)
+        if finalize is None:
+            return combined
+        combined_tokens = count_tokens(combined)
+        return finalize("c3_read",
+                        {"file": file_path, "symbols": symbols},
+                        combined,
+                        f"multi:{len(paths)}files->{combined_tokens}tok",
+                        response_tokens=combined_tokens)
+
+    full = Path(svc.project_path) / file_path
+    if not full.exists():
+        full = Path(file_path)
+    if not full.exists():
+        return f"[read:error] File not found: {file_path}"
+
+    rel_path = str(full.resolve().relative_to(Path(svc.project_path).resolve())).replace("\\", "/")
+
+    # Resolve ranges
+    ranges = []
+    if lines:
+        if isinstance(lines, int):
+            line_specs = [lines]
+        elif isinstance(lines, (list, tuple)) and len(lines) == 2 and all(isinstance(x, int) for x in lines):
+            line_specs = [lines]
+        elif isinstance(lines, (list, tuple)):
+            line_specs = lines
+        else:
+            line_specs = []
+
+        for spec in line_specs:
+            if isinstance(spec, int):
+                ranges.append((spec, spec))
+            elif isinstance(spec, (list, tuple)) and len(spec) >= 2:
+                ranges.append((int(spec[0]), int(spec[1])))
+            elif isinstance(spec, (list, tuple)) and len(spec) == 1:
+                ranges.append((int(spec[0]), int(spec[0])))
+
+    # Ensure file_memory index is fresh.
+    # When the watcher is running, it handles updates in the background —
+    # only force-update if file_memory has no record at all (first access).
+    try:
+        watcher_active = (hasattr(svc, "watcher") and svc.watcher._observer.is_alive())
+        if watcher_active:
+            if not svc.file_memory.get(rel_path):
+                svc.file_memory.update(rel_path)
+        elif svc.file_memory.needs_update(rel_path):
+            svc.file_memory.update(rel_path)
+    except Exception:
+        pass
+
+    raw_text = full.read_text(encoding="utf-8", errors="replace")
+    content_lines = raw_text.splitlines()
+    # Lazy: only count full file tokens when needed for the summary string
+    _full_tok_cache = [None]
+
+    def full_file_tokens():
+        if _full_tok_cache[0] is None:
+            _full_tok_cache[0] = count_tokens(raw_text)
+        return _full_tok_cache[0]
+
+    if symbols:
+        matches = svc.file_memory.get_symbol_ranges(rel_path, symbols, return_matches=True)
+
+        # Check for ambiguity
+        disambiguation_msgs = []
+        for target in symbols:
+            if target.startswith('^') or target in ('<main>', '<globals>', '<imports>'):
+                continue
+            target_matches = [m for m in matches if m["target"] == target.lower() or m["target"] == target]
+            unique_names = set(m["match"] for m in target_matches)
+            if len(unique_names) > 1:
+                exact = [m for m in target_matches if m["match"].lower() == target.lower()]
+                if exact:
+                    matches = [m for m in matches
+                               if m["target"] != target and m["target"] != target.lower()
+                               or m["match"].lower() == target.lower()]
+                else:
+                    options = ", ".join(
+                        f"{m['match']} (L{m['range'][0]}-L{m['range'][1]})" for m in target_matches)
+                    disambiguation_msgs.append(
+                        f"Ambiguous symbol '{target}'. Did you mean: {options}?")
+
+        if disambiguation_msgs:
+            resp = (f"[read:error] Ambiguous symbols found in {file_path}:\n"
+                    + "\n".join(disambiguation_msgs)
+                    + "\nTry using exact regex (e.g., '^symbol_name$') or the specific symbol name.")
+            return finalize("c3_read", {"file": file_path, "symbols": symbols},
+                            resp, f"{full_file_tokens()}->0tok")
+
+        for m in matches:
+            ranges.append(m["range"])
+
+        if '<main>' in symbols or '<globals>' in symbols:
+            record = svc.file_memory.get(rel_path)
+            if record and "sections" in record:
+                covered = set()
+
+                def _mark(secs):
+                    for s in secs:
+                        covered.update(range(s["line_start"], s["line_end"] + 1))
+                        if "children" in s:
+                            _mark(s["children"])
+
+                _mark(record["sections"])
+                main_ranges = []
+                current_start = None
+                for i in range(1, len(content_lines) + 1):
+                    if i not in covered:
+                        if current_start is None:
+                            current_start = i
+                    else:
+                        if current_start is not None:
+                            main_ranges.append((current_start, i - 1))
+                            current_start = None
+                if current_start is not None:
+                    main_ranges.append((current_start, len(content_lines)))
+                ranges.extend(main_ranges)
+
+    if not ranges and symbols:
+        file_map = svc.file_memory.get_or_build_map(rel_path)
+        resp = f"[read:{file_path}] symbols not found: {symbols}. Showing file map:\n{file_map}"
+        return finalize("c3_read", {"file": file_path, "symbols": symbols},
+                        resp, f"{full_file_tokens()}->{count_tokens(file_map)}tok")
+
+    if not ranges:
+        file_map = svc.file_memory.get_or_build_map(rel_path)
+        map_tok = count_tokens(file_map)
+        resp = file_map
+        return finalize("c3_read", {"file": file_path},
+                        resp, f"{full_file_tokens()}->{map_tok}tok")
+    else:
+        # Sort and merge overlapping ranges
+        ranges.sort()
+        merged = []
+        if ranges:
+            curr_start, curr_end = ranges[0]
+            for next_start, next_end in ranges[1:]:
+                if next_start <= curr_end + 1:
+                    curr_end = max(curr_end, next_end)
+                else:
+                    merged.append((curr_start, curr_end))
+                    curr_start, curr_end = next_start, next_end
+            merged.append((curr_start, curr_end))
+        ranges = merged
+        header = f"[read:{file_path}]"
+
+    parts = []
+    for start, end in ranges:
+        s_idx = max(0, start - 1)
+        e_idx = min(len(content_lines), end)
+        chunk = content_lines[s_idx:e_idx]
+        if len(ranges) > 1:
+            parts.append(f"--- L{start}-L{end} ---")
+        parts.extend(chunk)
+
+    final_content = "\n".join(parts)
+    tokens = count_tokens(final_content)
+    summary = f"{full_file_tokens()}->{tokens}tok" if tokens < full_file_tokens() else f"{tokens}tok"
+    resp = f"{final_content}"
+    return finalize("c3_read", {"file": file_path, "symbols": symbols}, resp, summary,
+                    response_tokens=tokens)

cli/tools/search.py

@@ -0,0 +1,337 @@
+"""c3_search — Code, file, and transcript discovery."""
+
+import re
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from pathlib import Path
+
+from core import count_tokens
+
+# Hard cap: responses above this are truncated to avoid filling context.
+_RESPONSE_TOKEN_CAP = 2400
+
+
+def _approx_tokens(text: str) -> int:
+    """Fast token estimate (~4 chars/token). Use for budget checks where exact
+    tiktoken counts are wasted work — the difference is <5% and noise."""
+    return len(text) >> 2
+
+
+def _cap_response(resp: str) -> str:
+    """Truncate response if it exceeds the token cap."""
+    tok = count_tokens(resp)
+    if tok <= _RESPONSE_TOKEN_CAP:
+        return resp
+    # Binary-ish search: cut lines from the end until under budget
+    lines = resp.split("\n")
+    while len(lines) > 1:
+        lines = lines[:len(lines) * 3 // 4]  # drop ~25% each iteration
+        candidate = "\n".join(lines) + "\n[truncated]"
+        if count_tokens(candidate) <= _RESPONSE_TOKEN_CAP:
+            return candidate
+    return "\n".join(lines[:20]) + "\n[truncated]"
+
+
+def handle_search(query: str, action: str, top_k: int, max_tokens: int,
+                  svc, finalize, maybe_facts, prefetch: bool = False) -> str:
+    top_k = max(1, min(int(top_k), 10))
+    max_tokens = min(max(200, int(max_tokens)), _RESPONSE_TOKEN_CAP)
+
+    if action == "exact":
+        return _exact_search(query, top_k, max_tokens, svc, finalize)
+
+    if action == "files":
+        resp = _files_search(query, top_k, svc, finalize)
+        if prefetch:
+            resp = _append_prefetch(resp, query, top_k, svc)
+        return _cap_response(resp)
+
+    if action == "transcript":
+        return _transcript_search(query, top_k, max_tokens, svc, finalize)
+
+    if action == "semantic":
+        return _semantic_search(query, top_k, max_tokens, svc, finalize, maybe_facts)
+
+    # Default: Code Search
+    resp = _code_search(query, top_k, max_tokens, svc, finalize, maybe_facts)
+    if prefetch:
+        resp = _append_prefetch(resp, query, top_k, svc)
+    return _cap_response(resp)
+
+
+def _exact_search(query, top_k, max_tokens, svc, finalize):
+    try:
+        pat = re.compile(query)
+    except Exception as e:
+        return finalize("c3_search", {"action": "exact"},
+                        f"[search:exact:error] Invalid regex: {e}", "error")
+
+    tracked = svc.file_memory.list_tracked()
+
+    def _scan_file(rel):
+        """Scan a single file for regex matches. Returns (rel, matches) or None."""
+        full = Path(svc.project_path) / rel
+        if not full.exists():
+            return None
+        try:
+            lines = full.read_text(encoding="utf-8", errors="replace").splitlines()
+        except Exception:
+            return None
+        file_matches = []
+        for i, line in enumerate(lines):
+            if pat.search(line):
+                start = max(0, i - 1)
+                end = min(len(lines), i + 2)
+                for j in range(start, end):
+                    marker = ">" if j == i else " "
+                    entry = f"{marker}L{j+1}: {lines[j][:200]}"
+                    if entry not in file_matches:
+                        file_matches.append(entry)
+                if file_matches and file_matches[-1] != "---":
+                    file_matches.append("---")
+        return (rel, file_matches) if file_matches else None
+
+    # Parallel file scanning
+    matched_parts = []
+    file_count = 0
+    total_tokens = 0
+    with ThreadPoolExecutor(max_workers=min(len(tracked), 8)) as pool:
+        for result in pool.map(_scan_file, tracked):
+            if result is None:
+                continue
+            rel, file_matches = result
+            chunk = f"--- {rel} ---\n" + "\n".join(file_matches)
+            chunk_tokens = count_tokens(chunk)
+            if total_tokens + chunk_tokens > max_tokens and matched_parts:
+                break
+            file_count += 1
+            total_tokens += chunk_tokens
+            matched_parts.append(chunk)
+            if file_count >= top_k:
+                break
+
+    if not matched_parts:
+        return finalize("c3_search", {"action": "exact"},
+                        f"[search:exact:{query}] 0 results", "0")
+
+    resp = "\n".join(matched_parts)
+    return finalize("c3_search", {"action": "exact"}, resp, f"{file_count}f",
+                    response_tokens=total_tokens)
+
+
+def _files_search(query, top_k, svc, finalize):
+    res = svc.indexer.search(query, top_k=top_k, include_content=False)
+    if not res:
+        return finalize("c3_search", {"action": "files"},
+                        f"[search:files:{query}] 0 results", "0")
+    parts = []
+    _MAP_TOKEN_CAP = 600  # cap inline file map to avoid bloating response
+    for r in res:
+        meta = f"- {r['file']} (L{r['lines']})"
+        if r.get('name'):
+            meta += f" — contains {r['type']} '{r['name']}'"
+        if len(parts) == 0:
+            try:
+                rel = r['file'].replace("\\", "/")
+                watcher_active = (hasattr(svc, "watcher") and svc.watcher._observer.is_alive())
+                if not watcher_active and svc.file_memory.needs_update(rel):
+                    svc.file_memory.update(rel)
+                fmap = svc.file_memory.get_or_build_map(rel)
+                if fmap and count_tokens(fmap) <= _MAP_TOKEN_CAP:
+                    meta += f"\n  {fmap.replace(chr(10), chr(10) + '  ')}"
+                elif fmap:
+                    # Truncate large maps: keep first N lines
+                    fmap_lines = fmap.split("\n")
+                    truncated = []
+                    tok = 0
+                    for fl in fmap_lines:
+                        tok += count_tokens(fl)
+                        if tok > _MAP_TOKEN_CAP:
+                            break
+                        truncated.append(fl)
+                    truncated.append("  [map truncated]")
+                    meta += f"\n  {chr(10).join(truncated).replace(chr(10), chr(10) + '  ')}"
+            except Exception:
+                pass
+        parts.append(meta)
+    return finalize("c3_search", {"action": "files"},
+                    "\n".join(parts),
+                    f"{len(res)}f")
+
+
+def _transcript_search(query, top_k, max_tokens, svc, finalize):
+    sync_result = svc.convo_store.sync(source="all")
+    available = sync_result.get("available_sources", {})
+    available_names = [name for name, present in available.items() if present]
+    if not available_names:
+        resp = ("[transcript:unavailable] No supported transcript sources found for this project. "
+                "Supported sources: Claude Code, Gemini CLI, and imported transcripts under .c3/conversations/imports.")
+        return finalize("c3_search", {"action": "transcript"}, resp, "unavailable")
+
+    results = svc.convo_store.search(query, limit=max(top_k * 3, top_k))
+    if not results:
+        srcs = ",".join(sorted(available_names))
+        return finalize("c3_search", {"action": "transcript"},
+                        f"[transcript:{query}] 0 results sources:{srcs}", "0")
+    parts = []
+    total_tokens = 0
+    emitted = 0
+    for r in results:
+        tokens = int(r.get("tokens", 0) or count_tokens(r.get("text", "")))
+        if total_tokens + tokens > max_tokens and parts:
+            break
+        total_tokens += tokens
+        ts_raw = r.get("ts", 0)
+        try:
+            ts_str = time.strftime("%Y-%m-%d", time.localtime(float(ts_raw))) if ts_raw else ""
+        except Exception:
+            ts_str = ""
+        source = r.get("source") or r.get("turn_source") or "manual"
+        role = r.get("role", "")
+        session_id = r.get("session_id", "")
+        header = f"--- {source}:{session_id} [{ts_str}] role:{role} score:{r['score']}"
+        text = r.get("text", "")
+        parts.extend([header, text])
+        emitted += 1
+        if emitted >= top_k:
+            break
+    resp = f"[transcript:{query}] {emitted}r,{total_tokens}tok\n" + "\n".join(parts)
+    return finalize("c3_search", {"action": "transcript"}, resp, f"{emitted}r")
+
+
+def _semantic_search(query, top_k, max_tokens, svc, finalize, maybe_facts):
+    ei = getattr(svc, "embedding_index", None)
+    if not ei or not ei.ready:
+        # Fallback to TF-IDF code search when embeddings unavailable
+        return _code_search(query, top_k, max_tokens, svc, finalize, maybe_facts)
+
+    results = ei.search(query, top_k=top_k, max_tokens=max_tokens)
+    if not results:
+        return finalize("c3_search", {"query": query, "action": "semantic"},
+                        f"[semantic:{query}] 0 results (falling back to code search)",
+                        "0→fallback")
+
+    lines = []
+    total_tokens = 0
+    for r in results:
+        name = f" {r['name']}" if r.get('name') else ""
+        ref = f"--- {r['file']}:L{r['lines']}{name} ({r['type']})"
+        lines.extend([ref, r['content']] if r.get('content') else [ref])
+        total_tokens += r['tokens']
+
+    resp = "\n".join(lines)
+    resp += maybe_facts(svc, query, top_k=2)
+    return finalize("c3_search", {"query": query, "action": "semantic"}, resp,
+                    f"{len(results)}r,{total_tokens}tok", response_tokens=total_tokens)
+
+
+def _code_search(query, top_k, max_tokens, svc, finalize, maybe_facts):
+    results = svc.indexer.search(query, top_k=max(top_k + 1, top_k * 2),
+                                 max_tokens=max_tokens, include_content=True)
+    if not results:
+        return finalize("c3_search", {"query": query}, f"[search:{query}] 0 results", "0")
+
+    best_score = max((r.get("score", 0.0) for r in results), default=0.0)
+    if best_score > 0:
+        results = [r for r in results if r.get("score", 0.0) >= (best_score * 0.2)]
+
+    deduped = []
+    seen = set()
+    for r in results:
+        key = (r.get("file"), r.get("lines"))
+        if key not in seen:
+            seen.add(key)
+            deduped.append(r)
+            if len(deduped) >= top_k:
+                break
+
+    lines = []
+    total_tokens = 0
+    for r in deduped:
+        name = f" {r['name']}" if r['name'] else ""
+        ref = f"--- {r['file']}:L{r['lines']}{name} ({r['type']})"
+        lines.extend([ref, r['content']] if r.get('content') else [ref])
+        total_tokens += r['tokens']
+
+    resp = "\n".join(lines)
+    resp += maybe_facts(svc, query, top_k=2)
+    full_tokens = sum(r.get("file_tokens", r["tokens"]) for r in deduped)
+    summary = f"{full_tokens}->{total_tokens}tok" if total_tokens < full_tokens else f"{len(deduped)}r"
+    return finalize("c3_search", {"query": query, "top_k": top_k}, resp, summary,
+                    response_tokens=total_tokens)
+
+
+def _append_prefetch(resp: str, query: str, top_k: int, svc) -> str:
+    """Auto-compress top result files in parallel and append structural maps."""
+    # Extract file paths from the response
+    files = []
+    for line in resp.split("\n"):
+        if line.startswith("--- ") and ":L" in line:
+            # Pattern: --- path/file.py:L10-20 name (type,tok,s=0.123)
+            path = line[4:].split(":L")[0].strip()
+            if path and path not in files:
+                files.append(path)
+        elif line.startswith("- ") and " (L" in line:
+            # Pattern: - path/file.py (L123)
+            path = line[2:].split(" (L")[0].strip()
+            if path and path not in files:
+                files.append(path)
+
+    cfg = (svc.hybrid_config or {}).get("agent_workflows", {})
+    max_files = max(1, int(cfg.get("prefetch_max_files", 3)))
+    files = files[:max_files]
+
+    if not files:
+        return resp
+
+    maps = {}
+    uncached = []
+
+    # Fast path: check in-memory + file_memory map cache before spawning threads
+    for fp in files:
+        try:
+            fmap = svc.file_memory.get_map(fp.replace("\\", "/"))
+            if fmap:
+                maps[fp] = fmap
+                continue
+        except Exception:
+            pass
+        uncached.append(fp)
+
+    def compress_one(fp):
+        try:
+            full = str(Path(svc.project_path) / fp)
+            result = svc.compressor.compress_file(full, "map")
+            if isinstance(result, dict) and result.get("compressed"):
+                return fp, result["compressed"]
+        except Exception:
+            pass
+        return fp, None
+
+    if uncached:
+        with ThreadPoolExecutor(max_workers=min(len(uncached), 8)) as pool:
+            futures = {pool.submit(compress_one, f): f for f in uncached}
+            for fut in as_completed(futures):
+                fp, compressed = fut.result()
+                if compressed:
+                    maps[fp] = compressed
+
+    if not maps:
+        return resp
+
+    # Budget: prefetch maps share remaining token headroom. Uses fast approximation —
+    # exact tiktoken cost is wasted work here (we only need an upper-bound check).
+    resp_tokens = _approx_tokens(resp)
+    remaining = max(400, _RESPONSE_TOKEN_CAP - resp_tokens)
+
+    prefetch_parts = [f"\n\n--- prefetched maps ({len(maps)} files) ---"]
+    used = 0
+    for fp in files:
+        if fp in maps:
+            m = maps[fp]
+            m_tok = _approx_tokens(m)
+            if used + m_tok > remaining:
+                break
+            prefetch_parts.append(f"## {fp}\n{m}")
+            used += m_tok
+    return resp + "\n".join(prefetch_parts)

cli/tools/session.py

@@ -0,0 +1,95 @@
+"""c3_session — Session lifecycle, snapshots, and logging."""
+
+import re
+
+
+def handle_session(action: str, data: str, reasoning: str, description: str,
+                   summary: str, event_type: str, svc, finalize) -> str:
+    if action == "start":
+        if svc.session_mgr.current_session:
+            svc.session_mgr.save_session()
+        result = svc.session_mgr.start_session(description, source_system=svc.ide_name)
+        return finalize("c3_session", {"action": action},
+                        f"[session:started] {result['session_id']}", result['session_id'])
+
+    if action == "save":
+        # Auto-memory: flush pending extractions and generate session summary.
+        if hasattr(svc, "auto_memory"):
+            try:
+                svc.auto_memory.on_session_end()
+            except Exception:
+                pass
+        svc.session_mgr._persist_budget()
+        result = svc.session_mgr.save_session(summary)
+        if "error" in result:
+            return f"Error: {result['error']}"
+        return finalize("c3_session", {"action": action},
+                        f"[session:saved] {result['session_id']}", result['session_id'])
+
+    if action == "plan":
+        svc.session_mgr.log_decision(f"PLAN: {data}", reasoning)
+        svc.activity_log.log("plan", {"plan": data, "reasoning": reasoning})
+        svc.memory.remember(f"PLAN: {data}", "plan",
+                            (svc.session_mgr.current_session or {}).get("id", ""))
+        return finalize("c3_session", {"action": action, "data": data[:80]},
+                        "[plan:stored]", "ok")
+
+    if action == "log":
+        etype = event_type
+        if etype == "auto":
+            data_stripped = data.strip()
+            if re.match(r'^[\w./\\-]+\.(py|js|ts|tsx|jsx|rs|go|java|rb|css|html|md|json|yaml|yml|toml)\b',
+                        data_stripped):
+                etype = "file_change"
+            else:
+                etype = "decision"
+        if etype == "file_change":
+            svc.session_mgr.log_file_change(data, "modified", reasoning)
+            svc.activity_log.log("file_change", {"file": data, "summary": reasoning})
+        else:
+            svc.session_mgr.log_decision(data, reasoning)
+            svc.activity_log.log("decision", {"decision": data, "reasoning": reasoning})
+        return finalize("c3_session", {"action": action, "data": data[:80]},
+                        f"[logged:{etype}]", "ok")
+
+    if action == "snapshot":
+        # Auto-memory: flush pending extractions before capturing snapshot.
+        if hasattr(svc, "auto_memory"):
+            try:
+                svc.auto_memory.on_session_end()
+            except Exception:
+                pass
+        # summary = optional comma-separated working files to embed structural maps for
+        files = [f.strip() for f in summary.split(",") if f.strip()] if summary else []
+        compressor = getattr(svc, "compressor", None)
+        res = svc.snapshots.capture(svc.session_mgr, svc.memory, data or "", files, reasoning,
+                                    compressor=compressor)
+        msg = f"✓ snapshot {res['snapshot_id']} ({res['token_count']}tok). Ask user to /clear, then restore."
+        return finalize("c3_session", {"action": action}, msg, res['snapshot_id'])
+
+    if action == "restore":
+        res = svc.snapshots.restore(data or "latest", memory_store=svc.memory)
+        if "error" in res:
+            return f"[restore:error] {res['error']}"
+        svc.session_mgr.reset_budget(initial_tokens=res.get("tokens", 0))
+        briefing = res["briefing"]
+        return finalize("c3_session", {"action": action},
+                        briefing, f"{res['snapshot_id']},{res['tokens']}tok")
+
+    if action == "compact":
+        res = svc.snapshots.capture(svc.session_mgr, svc.memory,
+                                     data or "auto-checkpoint before /clear")
+        if "error" in res:
+            return f"[compact:error] {res['error']}"
+        svc.session_mgr.reset_budget(initial_tokens=0)
+        msg = f"✓ compacted {res['snapshot_id']}. Budget reset. Ask user to /clear, then restore."
+        return finalize("c3_session", {"action": action}, msg, res['snapshot_id'])
+
+    if action == "convo_log":
+        sid = (svc.session_mgr.current_session or {}).get("id", "manual")
+        role = event_type if event_type != "auto" else "user"
+        if svc.convo_store:
+            svc.convo_store.add_turn(sid, role, data)
+        return finalize("c3_session", {"action": action}, "", "logged")
+
+    return f"[session:error] Unknown action: {action}"