euron-code 0.1.0__py3-none-any.whl

euron_code/cli.py

@@ -0,0 +1,351 @@
+"""Command-line entry point: `euron`.
+
+Exit codes:
+  0 success | 1 error | 2 bad usage | 3 no Euron Plus / Super 30 access | 4 not logged in / key rejected
+  5 daily token allowance used | 6 --max-turns reached | 130 interrupted
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from pathlib import Path
+from typing import List, Optional
+
+from euron_code import __version__, api, auth, config, credentials, sessions
+from euron_code.ui import UI, QuietUI
+
+EXIT_OK, EXIT_ERROR, EXIT_USAGE, EXIT_NO_PLUS, EXIT_AUTH, EXIT_QUOTA, EXIT_MAX_TURNS, EXIT_INT = 0, 1, 2, 3, 4, 5, 6, 130
+SUBCOMMANDS = ("login", "logout", "whoami", "usage", "doctor", "config")
+
+
+def _fix_windows_console() -> None:
+    """Make sure UTF-8 output does not crash on legacy Windows code pages."""
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            if stream and hasattr(stream, "reconfigure") and (stream.encoding or "").lower() not in ("utf-8", "utf8"):
+                stream.reconfigure(errors="replace")
+        except Exception:
+            pass
+
+
+def main_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="euron",
+        description="Euron Code: an AI coding agent in your terminal (Euron Plus and Super 30).",
+        epilog="Commands: euron login | logout | whoami | usage | doctor | config get|set|unset|list. "
+               "Run `euron` with no arguments for an interactive session.",
+    )
+    p.add_argument("prompt", nargs="?", help="Initial prompt (with -p: the one-shot prompt).")
+    p.add_argument("-p", "--print", dest="print_mode", action="store_true",
+                   help="Non-interactive: run the prompt, print the result, exit.")
+    p.add_argument("--output-format", choices=["text", "json"], default="text", help="With -p: text or json.")
+    p.add_argument("--max-turns", type=int, default=None, help="Maximum model steps for this run.")
+    p.add_argument("--model", default=None, help="Model id (default: your account's default model).")
+    p.add_argument("-c", "--continue", dest="cont", action="store_true", help="Continue the latest session in this folder.")
+    p.add_argument("-r", "--resume", nargs="?", const="", default=None, metavar="ID",
+                   help="Resume a session (pick from a list, or give an id).")
+    p.add_argument("--yolo", "--dangerously-skip-permissions", dest="yolo", action="store_true",
+                   help="Do not ask before edits or commands. Only use in a throwaway folder or container.")
+    p.add_argument("--permission-mode", choices=["default", "acceptEdits", "yolo"], default=None)
+    p.add_argument("--allowed-tools", default=None,
+                   help="Comma-separated allow rules for this run, e.g. \"Edit,Bash(pytest:*)\".")
+    p.add_argument("--verbose", action="store_true", help="With -p: show progress on stderr.")
+    p.add_argument("--version", action="version", version=f"euron-code {__version__}")
+    return p
+
+
+def sub_parser(cmd: str) -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog=f"euron {cmd}")
+    if cmd == "login":
+        p.add_argument("--no-browser", action="store_true", help="Print the link instead of opening a browser.")
+    if cmd == "usage":
+        p.add_argument("--json", action="store_true")
+        p.add_argument("--days", type=int, default=30)
+    if cmd == "whoami":
+        p.add_argument("--json", action="store_true")
+    if cmd == "config":
+        p.add_argument("action", choices=["get", "set", "unset", "list", "path"])
+        p.add_argument("key", nargs="?")
+        p.add_argument("value", nargs="?")
+        p.add_argument("--project", action="store_true", help="Write .euron/settings.json in this folder.")
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    _fix_windows_console()
+    argv = list(sys.argv[1:] if argv is None else argv)
+    try:
+        if argv and argv[0] in SUBCOMMANDS:
+            return run_subcommand(argv[0], sub_parser(argv[0]).parse_args(argv[1:]))
+        args = main_parser().parse_args(argv)
+        return run_main(args)
+    except KeyboardInterrupt:
+        print("\nInterrupted.", file=sys.stderr)
+        return EXIT_INT
+
+
+# ---------------------------------------------------------------- helpers
+
+def _need_client(ui) -> api.Client:
+    url = config.base_url()
+    cred = credentials.load(url)
+    if cred is None:
+        raise api.AuthError("You are not logged in. Run `euron login` first.", status=401, code="missing_api_key")
+    return api.Client(api_key=cred.api_key, base_url=url)
+
+
+def _report(ui, e: api.EuronError) -> int:
+    if isinstance(e, api.NotEntitledError):
+        ui.exact(api.NO_PLUS_MESSAGE)
+        return EXIT_NO_PLUS
+    if isinstance(e, api.AuthError):
+        msg = e.message if "euron login" in e.message else f"{e.message}. Run `euron login` to sign in again."
+        ui.error(msg)
+        return EXIT_AUTH
+    if isinstance(e, api.QuotaExceededError):
+        ui.error(e.message)
+        return EXIT_QUOTA
+    ui.error(e.message)
+    return EXIT_ERROR
+
+
+def _check_entitled(me) -> None:
+    if not (me.get("access") or {}).get("entitled"):
+        raise api.NotEntitledError(api.NO_PLUS_MESSAGE, status=403, code="no_plus_access")
+
+
+# ---------------------------------------------------------------- subcommands
+
+def run_subcommand(cmd: str, args) -> int:
+    ui = UI()
+    try:
+        if cmd == "login":
+            auth.login(ui, open_browser=not args.no_browser)
+            return EXIT_OK
+        if cmd == "logout":
+            auth.logout(ui)
+            return EXIT_OK
+        if cmd == "doctor":
+            from euron_code.doctor import doctor
+            return doctor(ui)
+        if cmd == "config":
+            return run_config(ui, args)
+        client = _need_client(ui)
+        try:
+            me = client.me(use_cache=(cmd != "usage"))
+            if cmd == "whoami":
+                if args.json:
+                    print(json.dumps(me, indent=2))
+                else:
+                    from euron_code.usage_view import render_account
+                    render_account(ui, me)
+                    ui.dim(f"Key {credentials.mask_key(client.api_key)} ({credentials.where(client.base_url)}), "
+                           f"API {client.base_url}")
+                _check_entitled(me)
+                return EXIT_OK
+            if cmd == "usage":
+                _check_entitled(me)
+                usage = client.usage(args.days)
+                if args.json:
+                    print(json.dumps({"me": me, "usage": usage}, indent=2))
+                else:
+                    from euron_code.usage_view import render_usage
+                    render_usage(ui, me, usage)
+                return EXIT_OK
+        finally:
+            client.close()
+    except api.EuronError as e:
+        return _report(ui, e)
+    return EXIT_USAGE
+
+
+def run_config(ui, args) -> int:
+    root = Path.cwd() if args.project else None
+    if args.action == "path":
+        ui.plain(str(config.project_settings_path(Path.cwd()) if args.project else config.user_settings_path()))
+        return EXIT_OK
+    if args.action == "list":
+        print(json.dumps(config.load_settings(Path.cwd()), indent=2, sort_keys=True))
+        return EXIT_OK
+    if not args.key:
+        ui.error("A key is required, e.g. `euron config get model`.")
+        return EXIT_USAGE
+    if args.action == "get":
+        val = config.get_path(config.load_settings(Path.cwd()), args.key)
+        if args.key.startswith("db.connections") and isinstance(val, (str, dict)):
+            from euron_code.tools.db import mask_dsn
+            val = mask_dsn(val) if isinstance(val, str) else {k: mask_dsn(str(v)) for k, v in val.items()}
+        print(json.dumps(val) if not isinstance(val, str) else val)
+        return EXIT_OK
+    if args.action == "set":
+        if args.value is None:
+            ui.error("A value is required, e.g. `euron config set reasoning show`.")
+            return EXIT_USAGE
+        path = config.config_set(args.key, args.value, root)
+        ui.dim(f"Saved {args.key} in {path}")
+        return EXIT_OK
+    if args.action == "unset":
+        path = config.config_unset(args.key, root)
+        ui.dim(f"Removed {args.key} from {path}")
+        return EXIT_OK
+    return EXIT_USAGE
+
+
+# ---------------------------------------------------------------- main session
+
+def run_main(args) -> int:
+    from euron_code.agent import Agent
+    from euron_code.permissions import Permissions
+
+    root = config.find_project_root()
+    settings = config.load_settings(root)
+    if args.print_mode:
+        ui = QuietUI(verbose=args.verbose)
+    else:
+        ui = UI(reasoning=str(settings.get("reasoning") or "collapse"))
+
+    prompt = args.prompt
+    if args.print_mode:
+        piped = ""
+        if not sys.stdin.isatty():
+            try:
+                piped = sys.stdin.read()
+            except (OSError, ValueError):
+                piped = ""
+        if piped.strip():
+            prompt = (prompt + "\n\n" if prompt else "") + piped
+        if not prompt or not prompt.strip():
+            ui.error("-p needs a prompt: euron -p \"explain this repo\"")
+            return EXIT_USAGE
+
+    # credentials + entitlement
+    url = config.base_url()
+    cred = credentials.load(url)
+    if cred is None:
+        if args.print_mode or not sys.stdin.isatty():
+            ui.error("You are not logged in. Run `euron login` first.")
+            return EXIT_AUTH
+        ui.info("You are not logged in yet.")
+        try:
+            auth.login(ui)
+        except api.EuronError as e:
+            return _report(ui, e)
+        cred = credentials.load(url)
+        if cred is None:
+            return EXIT_AUTH
+    client = api.Client(api_key=cred.api_key, base_url=url)
+    try:
+        try:
+            me = client.me()
+            _check_entitled(me)
+        except api.EuronError as e:
+            return _report(ui, e)
+
+        model = args.model or settings.get("model") or me.get("defaultModel") or "euron-coder"
+        perms_cfg = settings.get("permissions") or {}
+        mode = "yolo" if args.yolo else (args.permission_mode or perms_cfg.get("defaultMode") or "default")
+        allow = list(perms_cfg.get("allow") or [])
+        if args.allowed_tools:
+            allow += [r.strip() for r in args.allowed_tools.split(",") if r.strip()]
+        permissions = Permissions(root, allow=allow, deny=list(perms_cfg.get("deny") or []), mode=mode)
+
+        # session
+        loaded = None
+        if args.cont:
+            info = sessions.latest(root)
+            if info is None:
+                ui.warn("No previous session in this folder; starting a new one.")
+            else:
+                loaded = sessions.load_session(info.path)
+        elif args.resume is not None:
+            if args.resume:
+                info = sessions.find(root, args.resume)
+                if info is None:
+                    ui.error(f"No session {args.resume!r} for this folder.")
+                    return EXIT_USAGE
+            elif args.print_mode:
+                info = sessions.latest(root)
+            else:
+                from euron_code.repl import pick_session
+                info = pick_session(root, ui)
+            if info is not None:
+                loaded = sessions.load_session(info.path)
+        session = sessions.SessionWriter(root, session_id=loaded.id if loaded else None, model=model)
+        agent = Agent(client, ui, root, settings, permissions, model, session=session, max_turns=args.max_turns)
+        if loaded:
+            agent.load_history(loaded.messages, loaded.todos)
+            if not args.print_mode:
+                ui.dim(f"Resumed session {loaded.id} ({len(loaded.messages)} messages).")
+
+        if args.print_mode:
+            return run_print(agent, ui, client, prompt, args, session)
+        from euron_code.repl import Repl
+        return Repl(agent, client, ui, me, session).run(initial=prompt)
+    finally:
+        client.close()
+
+
+def run_print(agent, ui, client, prompt: str, args, session) -> int:
+    res = agent.run_turn(prompt)
+    code = EXIT_OK
+    err = res.error
+    message = None
+    if err is not None:
+        if isinstance(err, api.QuotaExceededError):
+            try:
+                from euron_code.usage_view import local_time
+                me = client.me(use_cache=False)
+                message = (f"You have used today's Euron Code token allowance. It resets at "
+                           f"{local_time((me.get('quota') or {}).get('resetsAt'))}.")
+            except api.EuronError:
+                message = err.message
+            err.message = message
+        code = _report(ui, err)  # message on stderr in both formats
+        message = err.message
+    elif res.stop_reason == "max_turns":
+        code = EXIT_MAX_TURNS
+        message = f"Stopped after --max-turns {args.max_turns}."
+        if args.output_format == "text":
+            ui.warn(message)
+    elif res.stop_reason == "interrupted":
+        code = EXIT_INT
+    t = agent.tokens
+    if args.output_format == "json":
+        out = {
+            "type": "result",
+            "subtype": "success" if code == 0 else ("error_max_turns" if code == EXIT_MAX_TURNS else "error"),
+            "is_error": code != 0,
+            "result": res.text,
+            "stop_reason": res.stop_reason,
+            "num_turns": res.turns,
+            "session_id": session.id,
+            "model": agent.model,
+            "usage": {"prompt_tokens": t.session_prompt, "completion_tokens": t.session_completion,
+                      "total_tokens": t.session_total, "requests": t.requests},
+            "exit_code": code,
+        }
+        if err is not None:
+            out["error"] = {"code": err.code, "status": err.status, "message": message}
+        sys.stdout.write(json.dumps(out, ensure_ascii=False) + "\n")
+    else:
+        if res.text:
+            sys.stdout.write(res.text.rstrip() + "\n")
+    sys.stdout.flush()
+    return code
+
+
+def _code_for(e: api.EuronError) -> int:
+    if isinstance(e, api.NotEntitledError):
+        return EXIT_NO_PLUS
+    if isinstance(e, api.AuthError):
+        return EXIT_AUTH
+    if isinstance(e, api.QuotaExceededError):
+        return EXIT_QUOTA
+    return EXIT_ERROR
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

euron_code/config.py

@@ -0,0 +1,207 @@
+"""Paths, settings files and the `euron config` command.
+
+Settings are merged in this order (later wins):
+  built-in defaults < ~/.euron/settings.json < <project>/.euron/settings.json
+  < <project>/.euron/settings.local.json
+Permission allow/deny lists are concatenated rather than replaced.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import os
+import subprocess
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+DEFAULT_BASE_URL = "https://api.euron.one/api/v1/code-agent"
+
+#: Context window and output cap of the default model (Qwen3.6-27B, see BENCHMARK_RESULTS.md).
+DEFAULT_CONTEXT_WINDOW = 32768
+DEFAULT_MAX_OUTPUT = 8192
+
+DEFAULTS: Dict[str, Any] = {
+    "model": None,  # None -> use defaultModel from /v1/me
+    "reasoning": "collapse",  # show | collapse | hide
+    "contextWindow": DEFAULT_CONTEXT_WINDOW,
+    "maxOutputTokens": DEFAULT_MAX_OUTPUT,
+    "autoCompact": True,
+    "compactThreshold": 0.75,
+    "toolOutputMaxChars": 12000,
+    "bashTimeout": 120,
+    "shell": None,  # None -> auto (PowerShell/cmd on Windows, bash/sh elsewhere)
+    "webFetch": True,
+    "credentialStore": "auto",  # auto | keyring | file
+    "permissions": {"defaultMode": "default", "allow": [], "deny": []},
+    "db": {"connections": {}, "allowWrites": False, "maxRows": 200},
+}
+
+
+def euron_home() -> Path:
+    """~/.euron, overridable with EURON_HOME (used by tests)."""
+    env = os.environ.get("EURON_HOME")
+    p = Path(env).expanduser() if env else Path.home() / ".euron"
+    return p
+
+
+def ensure_home() -> Path:
+    home = euron_home()
+    home.mkdir(parents=True, exist_ok=True)
+    return home
+
+
+def base_url() -> str:
+    url = os.environ.get("EURON_CODE_API") or load_user_settings().get("apiBaseUrl") or DEFAULT_BASE_URL
+    return url.rstrip("/")
+
+
+def user_settings_path() -> Path:
+    return euron_home() / "settings.json"
+
+
+def project_settings_path(root: Path) -> Path:
+    return root / ".euron" / "settings.json"
+
+
+def project_local_settings_path(root: Path) -> Path:
+    return root / ".euron" / "settings.local.json"
+
+
+def _read_json(path: Path) -> Dict[str, Any]:
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+        return data if isinstance(data, dict) else {}
+    except FileNotFoundError:
+        return {}
+    except (OSError, ValueError):
+        return {}
+
+
+def write_json(path: Path, data: Dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_suffix(path.suffix + ".tmp")
+    with open(tmp, "w", encoding="utf-8") as f:
+        json.dump(data, f, indent=2, sort_keys=True)
+        f.write("\n")
+    os.replace(tmp, path)
+
+
+def load_user_settings() -> Dict[str, Any]:
+    return _read_json(user_settings_path())
+
+
+def _merge(base: Dict[str, Any], over: Dict[str, Any]) -> Dict[str, Any]:
+    out = copy.deepcopy(base)
+    for k, v in over.items():
+        if k == "permissions" and isinstance(v, dict):
+            cur = out.setdefault("permissions", {"allow": [], "deny": []})
+            for lk in ("allow", "deny"):
+                if isinstance(v.get(lk), list):
+                    cur[lk] = list(cur.get(lk, [])) + [str(x) for x in v[lk]]
+            if v.get("defaultMode"):
+                cur["defaultMode"] = v["defaultMode"]
+        elif isinstance(v, dict) and isinstance(out.get(k), dict):
+            out[k] = _merge(out[k], v)
+        else:
+            out[k] = copy.deepcopy(v)
+    return out
+
+
+def load_settings(root: Optional[Path] = None) -> Dict[str, Any]:
+    s = _merge(DEFAULTS, load_user_settings())
+    if root is not None:
+        s = _merge(s, _read_json(project_settings_path(root)))
+        s = _merge(s, _read_json(project_local_settings_path(root)))
+    return s
+
+
+def find_project_root(start: Optional[Path] = None) -> Path:
+    """The project root is the current directory.
+
+    Claude Code treats the launch directory as the workspace; we do the same so that a
+    student who opens a sub-folder in VS Code gets exactly that folder.
+    """
+    return (start or Path.cwd()).resolve()
+
+
+def find_git_root(start: Path) -> Optional[Path]:
+    cur = start.resolve()
+    for p in [cur, *cur.parents]:
+        if (p / ".git").exists():
+            return p
+    return None
+
+
+def git_branch(root: Path) -> Optional[str]:
+    try:
+        out = subprocess.run(
+            ["git", "rev-parse", "--abbrev-ref", "HEAD"],
+            cwd=str(root), capture_output=True, text=True, timeout=3,
+        )
+        if out.returncode == 0:
+            return out.stdout.strip() or None
+    except (OSError, subprocess.SubprocessError):
+        pass
+    return None
+
+
+# ---------------------------------------------------------------- euron config get/set
+
+def _parse_value(raw: str) -> Any:
+    try:
+        return json.loads(raw)
+    except ValueError:
+        return raw
+
+
+def get_path(data: Dict[str, Any], dotted: str) -> Any:
+    cur: Any = data
+    for part in dotted.split("."):
+        if not isinstance(cur, dict) or part not in cur:
+            return None
+        cur = cur[part]
+    return cur
+
+
+def set_path(data: Dict[str, Any], dotted: str, value: Any) -> None:
+    parts = dotted.split(".")
+    cur = data
+    for part in parts[:-1]:
+        nxt = cur.get(part)
+        if not isinstance(nxt, dict):
+            nxt = {}
+            cur[part] = nxt
+        cur = nxt
+    if value is None:
+        cur.pop(parts[-1], None)
+    else:
+        cur[parts[-1]] = value
+
+
+def config_set(key: str, raw_value: str, project: Optional[Path] = None) -> Path:
+    path = project_settings_path(project) if project else user_settings_path()
+    data = _read_json(path)
+    set_path(data, key, _parse_value(raw_value))
+    write_json(path, data)
+    return path
+
+
+def config_unset(key: str, project: Optional[Path] = None) -> Path:
+    path = project_settings_path(project) if project else user_settings_path()
+    data = _read_json(path)
+    set_path(data, key, None)
+    write_json(path, data)
+    return path
+
+
+def add_permission_rule(root: Path, kind: str, rule: str, local: bool = True) -> Path:
+    path = project_local_settings_path(root) if local else project_settings_path(root)
+    data = _read_json(path)
+    perms = data.setdefault("permissions", {})
+    lst: List[str] = perms.setdefault(kind, [])
+    if rule not in lst:
+        lst.append(rule)
+    write_json(path, data)
+    return path

euron_code/context.py

@@ -0,0 +1,131 @@
+"""Context-window bookkeeping and compaction helpers.
+
+The default model has a 32k window and up to 8k output. Prompt size comes from the API's
+`usage.prompt_tokens` when available; between calls we add a cheap estimate (~3.5 chars per token)
+for messages appended since, calibrated against the last real count.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any, Dict, List, Optional, Tuple
+
+CHARS_PER_TOKEN = 3.5
+MSG_OVERHEAD = 6
+ELIDED = "[old tool output removed to save context; re-run the tool if you need it again]"
+
+
+def _msg_chars(m: Dict[str, Any]) -> int:
+    n = len(str(m.get("content") or ""))
+    for tc in m.get("tool_calls") or []:
+        fn = tc.get("function") or {}
+        n += len(fn.get("name") or "") + len(fn.get("arguments") or "")
+    return n
+
+
+def estimate_tokens(messages: List[Dict[str, Any]], tools: Optional[List[Dict[str, Any]]] = None) -> int:
+    chars = sum(_msg_chars(m) for m in messages)
+    if tools:
+        chars += len(json.dumps(tools))
+    return int(chars / CHARS_PER_TOKEN) + MSG_OVERHEAD * len(messages)
+
+
+class TokenTracker:
+    """Tracks prompt size and session totals."""
+
+    def __init__(self) -> None:
+        self.ratio = 1.0  # real / estimated, from the last response
+        self.last_prompt_tokens: Optional[int] = None
+        self.session_prompt = 0
+        self.session_completion = 0
+        self.session_cached = 0
+        self.requests = 0
+
+    def record(self, usage: Optional[Dict[str, Any]], estimated_prompt: int) -> None:
+        self.requests += 1
+        if not usage:
+            return
+        pt = int(usage.get("prompt_tokens") or 0)
+        ct = int(usage.get("completion_tokens") or 0)
+        self.session_prompt += pt
+        self.session_completion += ct
+        details = usage.get("prompt_tokens_details") or {}
+        if isinstance(details, dict):
+            self.session_cached += int(details.get("cached_tokens") or 0)
+        if pt > 0 and estimated_prompt > 0:
+            self.ratio = max(0.5, min(2.0, pt / estimated_prompt))
+            self.last_prompt_tokens = pt
+
+    @property
+    def session_total(self) -> int:
+        return self.session_prompt + self.session_completion
+
+    def prompt_estimate(self, messages, tools) -> int:
+        return int(estimate_tokens(messages, tools) * self.ratio)
+
+
+def _is_boundary(m: Dict[str, Any]) -> bool:
+    # cutting before a user or assistant message never separates tool results from their call
+    return m.get("role") in ("user", "assistant")
+
+
+def split_for_compaction(messages: List[Dict[str, Any]], keep_tokens: int) -> Tuple[int, int]:
+    """Given messages (index 0 = system), return (start, cut): messages[1:cut] are summarised,
+    messages[cut:] are kept. `cut` lands on a user or assistant message, so an assistant tool call
+    always stays together with its results, and the kept tail is about `keep_tokens` long.
+    Returns cut == 1 when nothing can be split off."""
+    n = len(messages)
+    kept = 0
+    candidate = None
+    i = n - 1
+    while i >= 2:
+        kept += estimate_tokens([messages[i]])
+        if _is_boundary(messages[i]):
+            candidate = i
+            if kept >= keep_tokens:
+                break
+        i -= 1
+    if candidate is None:
+        return 1, 1
+    # keep at least the last exchange: never summarise the final message
+    if candidate >= n:
+        return 1, 1
+    return 1, candidate
+
+
+def elide_old_tool_outputs(messages: List[Dict[str, Any]], keep_last: int = 4, min_chars: int = 600) -> int:
+    """Stage-1 compaction: replace large old tool results with a stub. Returns chars saved."""
+    tool_idx = [i for i, m in enumerate(messages) if m.get("role") == "tool"]
+    saved = 0
+    for i in tool_idx[:-keep_last] if keep_last else tool_idx:
+        c = str(messages[i].get("content") or "")
+        if len(c) > min_chars and c != ELIDED:
+            first = c.splitlines()[0][:160] if c else ""
+            stub = f"{first}\n{ELIDED}"
+            saved += len(c) - len(stub)
+            messages[i] = dict(messages[i], content=stub)
+    return saved
+
+
+def render_transcript(messages: List[Dict[str, Any]], per_message_chars: int = 1500) -> str:
+    out = []
+    for m in messages:
+        role = m.get("role")
+        content = str(m.get("content") or "")
+        if len(content) > per_message_chars:
+            content = content[: per_message_chars // 2] + "\n[...]\n" + content[-per_message_chars // 2:]
+        if role == "assistant":
+            calls = []
+            for tc in m.get("tool_calls") or []:
+                fn = tc.get("function") or {}
+                args = fn.get("arguments") or ""
+                calls.append(f"{fn.get('name')}({args[:400]})")
+            line = "ASSISTANT: " + content
+            if calls:
+                line += "\n  tool calls: " + "; ".join(calls)
+            out.append(line)
+        elif role == "tool":
+            out.append(f"TOOL RESULT ({m.get('name', '')}): {content}")
+        elif role == "user":
+            out.append("USER: " + content)
+    return "\n\n".join(out)