agentledger-cli 0.1.0__py3-none-any.whl

agentledger/agents/gemini.py

@@ -0,0 +1,251 @@
+"""Gemini CLI sessions, hooked from ~/.gemini/settings.json (AfterAgent and SessionEnd).
+
+The session is ~/.gemini/tmp/<project>/chats/session-<start>-<id>.jsonl (older releases wrote one
+.json file); $GEMINI_CLI_HOME moves ~/.gemini. Gemini CLI appends records to it: the session's
+metadata, each message (written again under the same id when it changes), "$set" updates and
+"$rewindTo". A "$set" with "messages" replaces the conversation after compression and "$rewindTo"
+drops a rewound tail, but those model calls still ran, so the loader keeps every message it has
+seen, each at its latest version; messages that first appear in such a checkpoint (summaries,
+Gemini CLI's session context) are context rather than activity and are left out.
+
+Each gemini message is one of the app's model calls, with its model and token counts; it's
+written when the response finishes, so a call runs from the message before it to its own
+timestamp. A prompt the developer typed starts a turn (step 0); tool results come back as user
+messages, and Gemini CLI's own context and slash commands aren't prompts. Subagents keep their
+conversations in chats/<session id>/ and aren't loaded. Tool names are mapped to the ones the
+trace's file cards understand, read_file results are numbered in Cortex Code's "12... text" form,
+and replace results get Cortex Code's "Edit location" line. Thoughts are not loaded. The session is
+attributed to the git repository its tool calls touched most, else to the folder it ran in, and to
+the branches the repository's reflog shows checked out while it ran.
+"""
+import json
+import os
+import re
+from datetime import datetime, timezone
+from pathlib import Path
+
+from .. import hooks
+from ..repo import PATH_ARGS, git_reports, repo_of_paths
+from ..trace import RESULT_CHARS, clip, clip_args, request
+
+ID, NAME = "gemini", "Gemini CLI"
+HOME = Path(os.environ.get("GEMINI_CLI_HOME") or Path.home()).expanduser() / ".gemini"
+SETTINGS = HOME / "settings.json"
+TMP = HOME / "tmp"
+EVENTS = ("AfterAgent", "SessionEnd")
+
+TOOL_NAMES = {"read_file": "read", "write_file": "write", "replace": "edit", "run_shell_command": "bash",
+              "grep_search": "grep", "search_file_content": "grep", "glob": "glob", "web_fetch": "web_fetch",
+              "google_web_search": "web_search", "write_todos": "todo_write", "invoke_agent": "task",
+              "activate_skill": "skill", "ask_user": "ask_user_question"}
+# Older releases named read_file's path absolute_path.
+ARG_RENAMES = {"absolute_path": "file_path"}
+READ_LINES = 400
+# Gemini CLI's isIgnoredUserContent: slash commands, help, and the context it adds itself.
+NOT_PROMPTS = ("/", "?", "<session_context>", "<hook_context>")
+# read_file's header when it returns part of a file.
+TRUNCATED = re.compile(r"Showing lines (\d+)-\d+ of \d+ total lines\..*?--- FILE CONTENT \(truncated\) ---\n", re.S)
+# The tags Gemini CLI wraps shell output in.
+UNTRUSTED = re.compile(r"</?untrusted_context>")
+
+
+def detected():
+    return HOME.is_dir()
+
+
+def hooked():
+    return hooks.present(SETTINGS, nested=True)
+
+
+def install(command, config):
+    if hooks.install(SETTINGS, EVENTS, command, nested=True):
+        return f"hook added to {SETTINGS}"
+    return None
+
+
+def uninstall(config):
+    return hooks.remove(SETTINGS, nested=True)
+
+
+def job(hook):
+    """The session an AfterAgent / SessionEnd hook is about, or None. Only main sessions, in
+    ~/.gemini/tmp/<project>/chats (a subagent's sit a folder deeper)."""
+    transcript = Path(hook.get("transcript_path") or "").expanduser().resolve()
+    chats = transcript.parent
+    if (transcript.suffix not in (".jsonl", ".json") or chats.name != "chats"
+            or chats.parent.parent != TMP.resolve() or not transcript.is_file()):
+        return None
+    cwd = hook.get("cwd") if isinstance(hook.get("cwd"), str) else None
+    return {"path": str(transcript), "label": transcript.stem, "folders": [cwd] if cwd else [], "folder": cwd}
+
+
+def newest():
+    sessions = [p for pattern in ("*/chats/*.jsonl", "*/chats/*.json") for p in TMP.glob(pattern)]
+    return max(sessions, key=lambda p: p.stat().st_mtime, default=None)
+
+
+def _utc(value):
+    """A session timestamp (2026-10-12T00:27:01.735Z) as a naive UTC datetime."""
+    return datetime.fromisoformat(value.replace("Z", "+00:00")).astimezone(timezone.utc).replace(tzinfo=None)
+
+
+def _ts(value):
+    """Session timestamps as the naive UTC text Snowflake parses."""
+    return _utc(value).strftime("%Y-%m-%d %H:%M:%S.%f")[:-3]
+
+
+def load(path):
+    """The session's metadata and its messages in order, each at its latest version, with
+    `_checkpoint` set on those first seen in a "$set" messages checkpoint."""
+    text = Path(path).read_text()
+    if Path(path).suffix == ".json":
+        record = json.loads(text)
+        return record, [m for m in record.get("messages") or [] if isinstance(m, dict) and m.get("id")]
+    meta, messages = {}, {}
+    for line in text.splitlines():
+        try:
+            record = json.loads(line)
+        except ValueError:
+            continue  # a line cut short by a crash
+        if not isinstance(record, dict) or "$rewindTo" in record:
+            continue
+        if isinstance(record.get("id"), str):
+            messages[record["id"]] = {**record, "_checkpoint": messages.get(record["id"], {}).get("_checkpoint")}
+        elif isinstance(record.get("$set"), dict):
+            update = record["$set"]
+            checkpoint = update.get("messages")
+            for m in checkpoint if isinstance(checkpoint, list) else []:
+                if isinstance(m, dict) and isinstance(m.get("id"), str):
+                    seen = messages.get(m["id"])
+                    messages[m["id"]] = {**m, "_checkpoint": True if seen is None else seen.get("_checkpoint")}
+            meta.update({k: v for k, v in update.items() if k != "messages"})
+        elif "sessionId" in record:
+            meta.update(record)
+    return meta, list(messages.values())
+
+
+def _parts(content):
+    if isinstance(content, str):
+        return [{"text": content}]
+    return [p for p in content if isinstance(p, dict)] if isinstance(content, list) else []
+
+
+def _text(content):
+    return "".join(p.get("text", "") for p in _parts(content) if isinstance(p.get("text"), str))
+
+
+def prompt_of(message):
+    """The prompt a user message carries (as the developer typed it), or None when it isn't one."""
+    if message.get("type") != "user" or message.get("_checkpoint"):
+        return None
+    if any("functionResponse" in p for p in _parts(message.get("content"))):
+        return None
+    text = _text(message.get("displayContent") or message.get("content")).strip()
+    return None if not text or text.startswith(NOT_PROMPTS) else text
+
+
+def edit_location(display, new_string):
+    """Where a replace's new text landed, in the words Cortex Code's edit results use ("Edit
+    location: lines 12-16"), from the file after the edit that Gemini CLI keeps beside the result."""
+    after = display.get("newContent") if isinstance(display, dict) else None
+    if not isinstance(after, str) or not new_string or (at := after.find(new_string)) < 0:
+        return None
+    start = after.count("\n", 0, at) + 1
+    return f"Edit location: lines {start}-{start + new_string.count(chr(10))}"
+
+
+def _result(name, call, args):
+    responses = [p["functionResponse"].get("response") for p in _parts(call.get("result"))
+                 if isinstance(p.get("functionResponse"), dict)]
+    texts = []
+    for r in responses:
+        value = r.get("output", r.get("error")) if isinstance(r, dict) else r
+        texts.append(value if isinstance(value, str) else json.dumps(value))
+    text = UNTRUSTED.sub("", "\n".join(texts)).strip("\n")
+    if name == "read" and call.get("status") == "success":
+        start = int(args.get("start_line") or args.get("offset") or 0) + (0 if args.get("start_line") else 1)
+        if m := TRUNCATED.search(text):
+            start, text = int(m[1]), text[m.end():]
+        text = "\n".join(f"{start + i}... {line}" for i, line in enumerate(text.splitlines()[:READ_LINES]))
+    elif name == "edit" and (where := edit_location(call.get("resultDisplay"), args.get("new_string"))):
+        text = f"{text}\n{where}"
+    # The trace marks a tool call failed when its result reads as an error.
+    if call.get("status") in ("error", "cancelled") and not text.lstrip().lower().startswith("error"):
+        text = f"Error: {text or call['status']}"
+    return clip(text, RESULT_CHARS)
+
+
+def model_calls(messages):
+    """One dict per gemini message, in order: prompt (for turn starts), step, model, tokens,
+    response text, tool calls, start (when its input was sent) and end."""
+    calls, last_input, step, pending_prompt = [], None, 0, None
+    for m in messages:
+        if not m.get("timestamp") or m.get("_checkpoint"):
+            continue
+        if m.get("type") == "user":
+            last_input = m["timestamp"]
+            if (prompt := prompt_of(m)) is not None:
+                # Prompts sent before the agent answered open one turn together.
+                pending_prompt = prompt if pending_prompt is None else f"{pending_prompt}\n\n{prompt}"
+                step = 0
+        elif m.get("type") == "gemini":
+            tools = []
+            for call in m.get("toolCalls") or []:
+                name = TOOL_NAMES.get(call.get("name"), call.get("name") or "tool")
+                args = clip_args(call.get("args") if isinstance(call.get("args"), dict) else {}, ARG_RENAMES)
+                tools.append({"id": call.get("id"), "name": name, "args": args, "result": _result(name, call, args)})
+            calls.append({"prompt": pending_prompt, "step": step, "model": m.get("model"),
+                          "tokens": m.get("tokens") or {}, "text": _text(m.get("content")).strip() or None,
+                          "tools": tools, "start": last_input or m["timestamp"], "end": m["timestamp"]})
+            pending_prompt, step, last_input = None, step + 1, m["timestamp"]
+    return calls
+
+
+def to_requests(calls, session_id):
+    requests = []
+    for i, call in enumerate(calls):
+        t = call["tokens"]
+        requests.append(request(
+            f"gemini-{session_id[:8]}-{i}", call["step"], _ts(call["start"]), _ts(max(call["end"], call["start"])),
+            call["prompt"] if call["step"] == 0 else None, call["text"], call["tools"],
+            model=call["model"],
+            # Gemini's input count already includes cached input, as Snowflake's telemetry does;
+            # thinking is billed as output.
+            input_tokens=(t.get("input") or 0) + (t.get("tool") or 0),
+            output_tokens=(t.get("output") or 0) + (t.get("thoughts") or 0),
+            cache_read_tokens=t.get("cached") or 0,
+            cache_write_tokens=0))
+    return requests
+
+
+def project_root(path):
+    """The folder a session ran in, from the .project_root Gemini CLI keeps beside its chats."""
+    try:
+        return (Path(path).parent.parent / ".project_root").read_text().strip() or None
+    except OSError:
+        return None
+
+
+def payload(path, repo_dir=None, folder=None):
+    """The session for core.ingest_external_session. `repo_dir` pins its repository; `folder`
+    (where it ran) is used when its tool calls name none, else the project Gemini CLI recorded."""
+    meta, messages = load(path)
+    calls = model_calls(messages)
+    models = [c["model"] for c in calls if c["model"]]
+    folder = repo_dir or repo_of_paths(
+        tool["args"].get(key) for c in calls for tool in c["tools"] for key in PATH_ARGS) or folder or project_root(path)
+    session_id = meta.get("sessionId") or Path(path).stem
+    stamps = [m["timestamp"] for m in messages if m.get("timestamp") and not m.get("_checkpoint")]
+    started = min(stamps) if stamps else meta.get("startTime")
+    prompts = sorted(_utc(m["timestamp"]) for m in messages if m.get("timestamp") and prompt_of(m) is not None)
+    reports = git_reports(folder, _utc(started), prompts) if folder else []
+    return {
+        "session_id": session_id,
+        "agent": "gemini-cli",
+        "agent_name": NAME,
+        "model": max(set(models), key=models.count) if models else None,
+        "started_at": _ts(started),
+        **({"git_reports": reports} if reports else {}),
+        "prompts": sum(1 for c in calls if c["step"] == 0 and c["prompt"]),
+        "requests": to_requests(calls, session_id),
+    }

agentledger/app.py

@@ -0,0 +1,45 @@
+"""Calls into the installed AgentLedger app over the developer's own Snowflake connection, so
+every session is stored as the user who ran it."""
+import json
+
+from .git_context import IDENTIFIER
+
+
+def connection_name(config):
+    from snowflake.connector.config_manager import CONFIG_MANAGER
+
+    return config["connection"] or CONFIG_MANAGER["default_connection_name"]
+
+
+def connect(config):
+    import snowflake.connector
+
+    snowflake.connector.paramstyle = "qmark"  # bind payloads server-side; they're too big for the statement text
+    options = {"connection_name": connection_name(config), "login_timeout": 60, "network_timeout": 600}
+    if config["role"]:
+        options["role"] = config["role"]
+    return snowflake.connector.connect(**options)
+
+
+def _ingest(config):
+    if not IDENTIFIER.match(config["app"]):
+        raise ValueError(f"invalid app name: {config['app']!r}")
+    return f"CALL {config['app']}.core.ingest_external_session(PARSE_JSON(?))"
+
+
+def check(conn, config):
+    """(user, role) when this connection may report sessions to the app; raises when it may not."""
+    cur = conn.cursor()
+    user, role = cur.execute("SELECT CURRENT_USER(), CURRENT_ROLE()").fetchone()
+    cur.execute(_ingest(config), ["{}"])
+    return user, role
+
+
+def ingest(conn, config, body):
+    """Loads one session; the app's answer ({"status": "ok", "requests": n, ...})."""
+    cur = conn.cursor()
+    # Agents outside Snowflake have no role of their own; a session shows the role it was reported
+    # with, as Cortex Code sessions show the role they ran under.
+    role = cur.execute("SELECT CURRENT_ROLE()").fetchone()[0]
+    cur.execute(_ingest(config), [json.dumps({**body, "role_name": role})])
+    return json.loads(cur.fetchone()[0])

agentledger/cli.py

@@ -0,0 +1,232 @@
+"""agentledger: report Claude Code, Cursor, Gemini CLI and Cortex Code sessions to the AgentLedger Snowflake app.
+
+    agentledger install     set up every agent on this machine (once)
+    agentledger status      what's set up, and each agent's latest report
+    agentledger upload      report sessions now, such as ones from before the install
+    agentledger uninstall   remove the hooks and the Cortex Code plugin
+"""
+import argparse
+import json
+import os
+import shlex
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from . import __version__, app, runner
+from . import config as settings
+from .agents import AGENTS, REPORTERS
+
+INSTALL_FIRST = "Install agentledger first: uv tool install agentledger-cli (or pipx install agentledger-cli)."
+
+
+def show(mark, label, text):
+    print(f"  {mark} {label:<12} {text}")
+
+
+def first_line(error):
+    return (str(error).strip().splitlines() or [repr(error)])[0]
+
+
+def executable():
+    """The agentledger command the hooks run, from a lasting installation (uv tool, pipx, a venv).
+    Run through uvx, whose environment is temporary, it installs itself with uv first."""
+    prefix = Path(sys.prefix)
+    if any(part.startswith(("archive-v", "builds-v")) for part in prefix.parts):
+        if not (uv := shutil.which("uv")):
+            raise SystemExit(INSTALL_FIRST)
+        print(f"Installing agentledger {__version__} with uv, so the hooks outlive this command…")
+        subprocess.run([uv, "tool", "install", f"agentledger-cli=={__version__}"], check=True)
+        bin_dir = subprocess.run([uv, "tool", "dir", "--bin"], capture_output=True, text=True, check=True).stdout
+        return str(Path(bin_dir.strip()) / "agentledger")
+    if (exe := prefix / "bin" / "agentledger").exists():
+        return str(exe)
+    if exe := shutil.which("agentledger"):
+        return exe
+    raise SystemExit(INSTALL_FIRST)
+
+
+def scope(config):
+    return "sessions in " + ", ".join(config["paths"]) if config["paths"] else "sessions in every folder"
+
+
+def check(config):
+    """Prints whether this machine can report to the app; True when it can."""
+    try:
+        with app.connect(config) as conn:
+            user, role = app.check(conn, config)
+    except Exception as e:  # noqa: BLE001 - any failure here means the same fix
+        show("✗", "Snowflake", first_line(e))
+        print(f"\n  The role needs the app's reporter role. An admin grants it with:\n"
+              f"    GRANT APPLICATION ROLE {config['app']}.APP_REPORTER TO ROLE <role>;\n"
+              f"  Pick the connection and role with --connection and --role.")
+        return False
+    show("✓", "Snowflake", f"{user} as {role} can report to {config['app']}")
+    return True
+
+
+def cmd_install(args):
+    config = settings.load()
+    config.update({k: getattr(args, k) for k in ("app", "connection", "role") if getattr(args, k)})
+    if args.only:
+        config["paths"] = [str(Path(p).expanduser().resolve()) for p in args.only]
+    elif args.all_folders:
+        config["paths"] = []
+    agents = [AGENTS[a] for a in args.agent] if args.agent else [a for a in AGENTS.values() if a.detected()]
+    if not agents:
+        print(f"No supported agent on this machine ({', '.join(a.NAME for a in AGENTS.values())}).")
+        return 1
+    exe = executable()
+    print(f"Setting up agentledger {__version__} for {config['app']} over the "
+          f"{app.connection_name(config)} connection")
+    if not check(config):
+        return 1
+    settings.save(config)
+    show("✓", "Settings", f"{settings.PATH} · {scope(config)}")
+    failed = False
+    for agent in agents:
+        try:
+            done = agent.install(f"{shlex.quote(exe)} hook {agent.ID}", config)
+            show("✓", agent.NAME, done or "already set up")
+        except Exception as e:  # noqa: BLE001 - one agent failing shouldn't stop the others
+            failed = True
+            show("!", agent.NAME, first_line(e))
+    print("\nSessions are reported in the background after each turn; `agentledger status` shows the latest.")
+    return 1 if failed else 0
+
+
+def last_report(agent):
+    try:
+        lines = runner.log_path(agent).read_text().splitlines()
+    except OSError:
+        return None
+    return next((line for line in reversed(lines) if line[20:].startswith(("ok ", "ignored ", "failed "))), None)
+
+
+def cmd_status(args):
+    config = settings.load()
+    print(f"agentledger {__version__} · {config['app']} · {app.connection_name(config)} connection · "
+          f"role {config['role'] or 'from the connection'} · {scope(config)}")
+    ready = check(config)
+    for agent in AGENTS.values():
+        if not agent.detected():
+            show("·", agent.NAME, "not on this machine")
+        elif not agent.hooked():
+            ready = False
+            show("✗", agent.NAME, "not set up; run agentledger install")
+        else:
+            last = last_report(agent.ID) if agent.ID in REPORTERS else None
+            show("✓", agent.NAME, f"set up · last report {last}" if last else "set up")
+    return 0 if ready else 1
+
+
+def cmd_uninstall(args):
+    config = settings.load()
+    for agent in AGENTS.values():
+        if agent.detected():
+            show("✓", agent.NAME, "removed" if agent.uninstall(config) else "nothing to remove")
+    print(f"\nSettings stay in {settings.PATH}.")
+    return 0
+
+
+def cmd_upload(args):
+    agent = REPORTERS[args.agent]
+    paths = args.sessions or [agent.newest()]
+    if paths == [None]:
+        print(f"No {agent.NAME} sessions on this machine.")
+        return 1
+    config = settings.load()
+    conn = None if args.dry_run else app.connect(config)
+    failed = False
+    for path in paths:
+        try:
+            body = agent.payload(path, repo_dir=args.repo_dir)
+            summary = (f"{body['session_id']}: {body['prompts']} prompts, {len(body['requests'])} model calls, "
+                       f"{len(json.dumps(body)) / 1e6:.1f} MB")
+            if args.dry_run:
+                out = settings.STATE / f"{agent.ID}-{body['session_id']}.json"
+                settings.write_json(out, body)
+                print(f"{summary} → {out}")
+                continue
+            result = app.ingest(conn, config, body)
+            print(f"{summary} → {result['status']}" + (f" ({result['reason']})" if result.get("reason") else ""))
+            failed |= result["status"] != "ok"
+        except Exception as e:  # noqa: BLE001 - report the rest
+            failed = True
+            print(f"{path}: {first_line(e)}")
+    if conn:
+        conn.close()
+    return 1 if failed else 0
+
+
+def report(agent, config, jobs):
+    with app.connect(config) as conn:
+        for job in jobs:
+            try:
+                result = app.ingest(conn, config, agent.payload(job["path"], folder=job.get("folder")))
+                detail = f"{result['requests']} model calls" if result["status"] == "ok" else result.get("reason")
+                runner.log(agent.ID, f"{result['status']} {job['label']}: {detail}")
+            except Exception as e:  # noqa: BLE001 - log it and go on with the next session
+                runner.log(agent.ID, f"failed {job['label']}: {first_line(e)}")
+
+
+def cmd_hook(args):
+    """Run by the agent after each turn. Returns at once and never fails the agent."""
+    agent = REPORTERS[args.agent]
+    try:
+        try:
+            hook = json.loads(sys.stdin.read() or "{}")
+        except ValueError:
+            hook = {}
+        sys.stdout.write("{}\n")
+        sys.stdout.flush()
+        config = settings.load()
+        job = agent.job(hook) if isinstance(hook, dict) else None
+        if job is None or not settings.in_scope(config, job["folders"]):
+            return 0
+        runner.enqueue(agent.ID, job)
+        if not runner.detach(agent.ID):
+            return 0
+    except Exception as e:  # noqa: BLE001
+        runner.log(agent.ID, f"failed hook: {e!r}")
+        return 0
+    try:
+        runner.drain(agent.ID, lambda jobs: report(agent, config, jobs))
+    except Exception as e:  # noqa: BLE001
+        runner.log(agent.ID, f"failed: {first_line(e)}")
+    finally:
+        os._exit(0)
+
+
+def main(argv=None):
+    parser = argparse.ArgumentParser(prog="agentledger", description=__doc__.splitlines()[0].split(": ", 1)[1])
+    parser.add_argument("--version", action="version", version=f"agentledger {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True, metavar="command")
+
+    p = sub.add_parser("install", help="set up every agent on this machine")
+    p.add_argument("--app", help="the installed app's name (default AGENTLEDGER)")
+    p.add_argument("-c", "--connection", help="Snowflake connection (default: your default connection)")
+    p.add_argument("--role", help="role holding the app's APP_REPORTER role (default: the connection's)")
+    p.add_argument("--only", nargs="+", metavar="FOLDER", help="report only sessions that ran in these folders")
+    p.add_argument("--all-folders", action="store_true", help="report sessions from every folder again")
+    p.add_argument("--agent", action="append", choices=AGENTS, help="set up only this agent (repeatable)")
+    p.set_defaults(run=cmd_install)
+
+    sub.add_parser("status", help="what's set up, and each agent's latest report").set_defaults(run=cmd_status)
+    sub.add_parser("uninstall", help="remove the hooks and the Cortex Code plugin").set_defaults(run=cmd_uninstall)
+
+    p = sub.add_parser("upload", help="report sessions now (default: the agent's newest)")
+    p.add_argument("agent", choices=REPORTERS)
+    p.add_argument("sessions", nargs="*", help="session files: Claude Code .jsonl transcripts, Cursor store.db "
+                                                    "files, Gemini CLI chats/session-*.jsonl files")
+    p.add_argument("--repo-dir", help="attribute the sessions to this repository")
+    p.add_argument("--dry-run", action="store_true", help=f"write the payloads under {settings.STATE} instead")
+    p.set_defaults(run=cmd_upload)
+
+    p = sub.add_parser("hook")  # run by the agents; without help, it stays out of the list
+    p.add_argument("agent", choices=REPORTERS)
+    p.set_defaults(run=cmd_hook)
+
+    args = parser.parse_args(argv)
+    sys.exit(args.run(args))

agentledger/config.py

@@ -0,0 +1,66 @@
+"""The developer's settings, in the file the Cortex Code plugin's git hook also reads:
+
+    ~/.snowflake/agentledger.json   {"app": "AGENTLEDGER", "connection": "my_conn", "role": "DEVELOPER",
+                                     "paths": ["~/work"]}
+
+`paths` limits which sessions are reported to the ones that ran in those folders (empty: all).
+AGENTLEDGER_APP / AGENTLEDGER_CONNECTION / AGENTLEDGER_ROLE override the file.
+"""
+import json
+import os
+import tempfile
+from pathlib import Path
+
+PATH = Path.home() / ".snowflake" / "agentledger.json"
+STATE = Path.home() / ".cache" / "agentledger"
+DEFAULTS = {"app": "AGENTLEDGER", "connection": None, "role": None, "paths": []}
+
+
+def read_json(path):
+    """A JSON object from a file; {} when it's missing. Anything else is an error, so a settings
+    file someone wrote by hand is never overwritten."""
+    try:
+        text = Path(path).read_text()
+    except FileNotFoundError:
+        return {}
+    data = json.loads(text) if text.strip() else {}
+    if not isinstance(data, dict):
+        raise ValueError(f"{path} doesn't hold a JSON object")
+    return data
+
+
+def write_json(path, data):
+    path = Path(path)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd, tmp = tempfile.mkstemp(dir=path.parent, prefix=f".{path.name}.")
+    with os.fdopen(fd, "w") as f:
+        json.dump(data, f, indent=2)
+        f.write("\n")
+    if path.exists():
+        os.chmod(tmp, path.stat().st_mode & 0o777)
+    os.replace(tmp, path)
+
+
+def load():
+    saved = read_json(PATH)
+    config = {**DEFAULTS, **{k: v for k, v in saved.items() if k in DEFAULTS and v}}
+    for key in ("app", "connection", "role"):
+        config[key] = os.environ.get(f"AGENTLEDGER_{key.upper()}") or config[key]
+    return config
+
+
+def save(config):
+    """Writes the settings, keeping any keys this version doesn't know."""
+    saved = read_json(PATH)
+    saved.update({k: config[k] for k in DEFAULTS})
+    write_json(PATH, {k: v for k, v in saved.items() if v})
+
+
+def in_scope(config, folders):
+    """True when a session that ran in these folders should be reported. A session that names no
+    folder is reported."""
+    folders = [Path(f).expanduser().resolve() for f in folders if f]
+    if not config["paths"] or not folders:
+        return True
+    roots = [Path(p).expanduser().resolve() for p in config["paths"]]
+    return any(f == r or r in f.parents for f in folders for r in roots)