local-coding-agent 1.1.0__py3-none-any.whl

local_coding_agent/chat_compaction.py

@@ -0,0 +1,276 @@
+"""Rolling context window: compaction of long chat histories for bounded models.
+
+Local models run with a fixed ``num_ctx``; a long multi-turn session eventually
+produces a prompt larger than that window and the request dies.  This module
+implements the borrowed "rolling window" pattern:
+
+- Evict WHOLE turns oldest-first.  A turn starts at a ``user`` message and
+  includes everything up to (not including) the next ``user`` message.  The
+  newest message is never dropped.
+- Insert a single visible system notice describing the omission, so the model
+  knows earlier context was truncated rather than never existed.
+- Support a STICKY boundary: callers persist ``next_sticky_boundary`` per
+  session and pass it back on the next call, so repeated compactions keep
+  dropping from the same frontier instead of creeping forward turn-by-turn
+  (which would shred llama-server's prefix cache).
+- Leave headroom below the budget (see
+  ``ROLLING_COMPACTION_HEADROOM_RATIO``) so the next turn does not immediately
+  re-trigger compaction.
+
+All functions are pure: no I/O and no global state is mutated.  Token counts
+are honest character-based estimates (see :func:`estimate_tokens`), never
+self-reported model numbers.
+"""
+
+import math
+from typing import Any
+
+ROLLING_COMPACTION_HEADROOM_RATIO = 0.9
+"""Fraction of ``token_budget`` that :func:`fit_history` aims to fit under.
+
+Compaction triggers when the history exceeds the full budget, but evicts only
+until the compacted history fits ``int(token_budget * 0.9)``.  The reserved
+10% headroom absorbs the next user/assistant exchange so compaction does not
+re-trigger on every single turn.
+"""
+
+_CHARS_PER_TOKEN = 4
+_UNBROKEN_ASCII_CHARS_PER_TOKEN = 2
+_UNBROKEN_ASCII_RUN_MIN = 64
+_MESSAGE_OVERHEAD_TOKENS = 4
+
+_CJK_RANGES = (
+    (0x3000, 0x303F),  # CJK symbols and punctuation
+    (0x3040, 0x309F),  # Hiragana
+    (0x30A0, 0x30FF),  # Katakana
+    (0x3400, 0x4DBF),  # CJK Unified Ideographs Extension A
+    (0x4E00, 0x9FFF),  # CJK Unified Ideographs
+    (0xAC00, 0xD7AF),  # Hangul syllables
+    (0xF900, 0xFAFF),  # CJK Compatibility Ideographs
+    (0xFF00, 0xFFEF),  # Fullwidth forms
+)
+
+
+def _is_cjk(ch: str) -> bool:
+    cp = ord(ch)
+    return any(lo <= cp <= hi for lo, hi in _CJK_RANGES)
+
+
+def estimate_tokens(text: str) -> int:
+    """Honest char-based token estimate for a single string.
+
+    - Normal text (short ASCII runs, non-CJK characters): ~4 chars/token.
+    - CJK ideographs/kana/hangul/fullwidth punctuation: ~1 token/char.
+    - An unbroken ASCII run (no whitespace) of >= 64 chars — hashes, base64,
+      minified blobs — is priced at ~2 chars/token.
+
+    Runs are broken by whitespace, so ordinary prose with spaces stays at
+    ~4 chars/token.  Returns the ceiling of the accumulated weight; empty
+    strings cost 0.
+    """
+    if not text:
+        return 0
+    total_weight = 0.0
+    n = len(text)
+    i = 0
+    while i < n:
+        ch = text[i]
+        if ch.isascii() and not ch.isspace():
+            j = i
+            while j < n and text[j].isascii() and not text[j].isspace():
+                j += 1
+            run_len = j - i
+            if run_len >= _UNBROKEN_ASCII_RUN_MIN:
+                total_weight += run_len / _UNBROKEN_ASCII_CHARS_PER_TOKEN
+            else:
+                total_weight += run_len / _CHARS_PER_TOKEN
+            i = j
+        elif _is_cjk(ch):
+            total_weight += 1.0
+            i += 1
+        else:  # whitespace and other non-CJK characters
+            total_weight += 1.0 / _CHARS_PER_TOKEN
+            i += 1
+    return math.ceil(total_weight)
+
+
+def estimate_messages_tokens(messages: list[dict[str, Any]]) -> int:
+    """Estimate the prompt tokens for an OpenAI-style message list.
+
+    Sum of :func:`estimate_tokens` over each message's content plus a small
+    per-message overhead constant (~4 tokens) covering role framing.  Non-str
+    content is coerced with ``str(content)`` for estimation only; callers must
+    coerce identically at send time or treat this as a lower bound.
+    """
+    return sum(
+        estimate_tokens(str(message.get("content", ""))) + _MESSAGE_OVERHEAD_TOKENS
+        for message in messages
+    )
+
+
+def _compaction_notice(dropped_count: int) -> str:
+    return (
+        f"[context compacted: {dropped_count} earlier message(s) omitted "
+        f"to fit the model context window]"
+    )
+
+
+def _message_cost(message: dict[str, Any]) -> int:
+    return estimate_tokens(str(message.get("content", ""))) + _MESSAGE_OVERHEAD_TOKENS
+
+
+def _plan_eviction(
+    messages: list[dict[str, Any]], sticky_boundary: int
+) -> tuple[set[int], list[tuple[int, int]]]:
+    """Plan this run's eviction.
+
+    Returns ``(dead_indices, units)``:
+
+    - ``dead_indices``: messages at ``[1, frontier)`` already compacted away by
+      earlier runs (sticky replay of the full transcript).  They are omitted
+      from the output for free and are NOT counted in ``dropped_count``.
+    - ``units``: half-open index ranges evictable THIS run, oldest first.  A
+      unit is a whole turn (starts at a ``user`` message, runs to the next
+      ``user`` message) with ``start >= max(1, sticky_boundary)``; a turn
+      containing the last message contributes only its prefix
+      ``[start, last_index)`` so the final message is never touched.  Index 0
+      is always protected.
+
+    If nothing is droppable at/after the sticky boundary, the boundary is
+    abandoned: ``dead_indices`` is emptied and units are rebuilt from index 1
+    (the protected region becomes ordinary evictable content).
+    """
+    last_idx = len(messages) - 1
+    unit_floor = max(1, sticky_boundary)
+    frontier = min(unit_floor, max(last_idx, 1))
+    first_user = next(
+        (i for i, m in enumerate(messages) if m.get("role") == "user"), None
+    )
+
+    def collect(floor: int) -> list[tuple[int, int]]:
+        if first_user is None:
+            return []
+        starts = [first_user] + [
+            i
+            for i in range(first_user + 1, len(messages))
+            if messages[i].get("role") == "user"
+        ]
+        units: list[tuple[int, int]] = []
+        for pos, start in enumerate(starts):
+            end = starts[pos + 1] if pos + 1 < len(starts) else len(messages)
+            if end <= last_idx:
+                if start >= floor:
+                    units.append((start, end))
+            else:  # turn contains the last message: only its prefix is evictable
+                p_start = max(start, floor)
+                if p_start < last_idx:
+                    units.append((p_start, last_idx))
+        units.sort()
+        return units
+
+    units = collect(unit_floor)
+    if units:
+        return set(range(1, frontier)), units
+    return set(), collect(1)
+
+
+def fit_history(
+    messages: list[dict[str, Any]],
+    token_budget: int,
+    sticky_boundary: int = 0,
+) -> tuple[list[dict[str, Any]], dict[str, Any]]:
+    """Compact a chat history to fit ``token_budget`` estimated tokens.
+
+    Semantics:
+    - ``token_budget <= 0`` raises ``ValueError``.  If even system+last exceed
+      the budget, still returns the best-effort result (system?, notice, last)
+      with an honest (possibly over-budget) ``estimated_tokens``; never raises
+      beyond the budget-validation error.
+    - Never drops ``messages[0]`` when its role is ``"system"`` (index 0 is
+      protected unconditionally) and never drops the last message.
+    - If the whole history already fits the budget, returns ``(copy, info)``
+      unchanged with ``compacted=False``.
+    - Otherwise drops whole turns (a turn starts at a ``user`` message and runs
+      to the next ``user`` message) oldest-first, beginning after index 0 and,
+      when ``sticky_boundary > 0``, only from indices ``>= sticky_boundary``;
+      if nothing droppable exists at/after the sticky boundary, falls back to
+      dropping from index 1.  Eviction stops once the projected result fits
+      ``int(token_budget * ROLLING_COMPACTION_HEADROOM_RATIO)``; if everything
+      evictable was dropped and it still does not fit, the best-effort result
+      is returned anyway.
+    - Sticky replay: messages at indices ``[1, sticky_frontier)`` of the input
+      were already compacted away by earlier runs (the caller replays the full
+      transcript together with the persisted boundary).  They are omitted from
+      the output for free — not counted in ``dropped_count`` and not mentioned
+      by this run's notice.  The frontier never covers the last message.
+    - When messages were dropped, exactly one system-role notice is inserted
+      right after the surviving system message (or at index 0 if there is none).
+
+    Non-str content is coerced with ``str(content)`` for estimation; original
+    message objects are preserved untouched (the returned list is a shallow
+    copy plus, if compacting, one new notice dict).
+
+    ``info`` keys:
+    - ``dropped_count``: number of messages evicted THIS run (whole turns /
+      final-turn prefixes), excluding free omissions below the sticky frontier.
+    - ``next_sticky_boundary``: defined EXACTLY as
+      ``sticky_boundary + dropped_count``.  It is an index into the ORIGINAL
+      message list marking where future compactions should start dropping:
+      every index below it has been omitted or evicted by some run so far.
+      Persist it per session (e.g. alongside the stored transcript) and pass
+      it back as ``sticky_boundary`` on the next call; without it the eviction
+      frontier creeps forward each turn and destroys llama-server's prefix
+      cache.
+    - ``estimated_tokens``: honest estimate of the returned list (notice
+      included), recomputed on the final result.
+    - ``compacted``: True iff any message was dropped or omitted.
+    """
+    if token_budget <= 0:
+        raise ValueError("token_budget must be a positive integer")
+    costs = [_message_cost(m) for m in messages]
+    total = sum(costs)
+    if total <= token_budget:
+        return list(messages), {
+            "dropped_count": 0,
+            "next_sticky_boundary": sticky_boundary,
+            "estimated_tokens": total,
+            "compacted": False,
+        }
+
+    dead, units = _plan_eviction(messages, sticky_boundary)
+    live_total = total - sum(costs[i] for i in dead)
+    target = int(token_budget * ROLLING_COMPACTION_HEADROOM_RATIO)
+    dropped_indices: set[int] = set()
+    dropped_tokens = 0
+    dropped_count = 0
+    for start, end in units:
+        dropped_indices.update(range(start, end))
+        dropped_tokens += sum(costs[start:end])
+        dropped_count += end - start
+        notice_cost = (
+            estimate_tokens(_compaction_notice(dropped_count))
+            + _MESSAGE_OVERHEAD_TOKENS
+        )
+        if live_total - dropped_tokens + notice_cost <= target:
+            break
+
+    if not dead and not dropped_indices:
+        # Over budget but nothing is evictable (e.g. [system, last] alone).
+        return list(messages), {
+            "dropped_count": 0,
+            "next_sticky_boundary": sticky_boundary,
+            "estimated_tokens": total,
+            "compacted": False,
+        }
+
+    skip = dead | dropped_indices
+    result = [m for i, m in enumerate(messages) if i not in skip]
+    notice_msg = {"role": "system", "content": _compaction_notice(dropped_count)}
+    insert_at = 1 if messages[0].get("role") == "system" else 0
+    result.insert(insert_at, notice_msg)
+    return result, {
+        "dropped_count": dropped_count,
+        "next_sticky_boundary": sticky_boundary + dropped_count,
+        "estimated_tokens": estimate_messages_tokens(result),
+        "compacted": True,
+    }

local_coding_agent/cli/__init__.py

@@ -0,0 +1,12 @@
+"""Command-line entry point for local-coding-agent.
+
+Refactored from a single module into a package. The full public API is
+re-exported here so existing imports keep working.
+"""
+
+from ._main import main
+from ._parser import build_parser
+from ._dispatch import handle_subcommand
+from ._input import load_task_input, load_task_file
+
+__all__ = ["main", "build_parser", "handle_subcommand", "load_task_input", "load_task_file"]

local_coding_agent/cli/_dispatch.py

@@ -0,0 +1,377 @@
+"""Subcommand dispatch and remaining handlers for the local-coding-agent CLI."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from ._handlers import (
+    _handle_apply,
+    _handle_calibrate,
+    _handle_decompose,
+    _handle_delegate,
+    _handle_memory,
+    _handle_profiles,
+)
+from ._handlers2 import (
+    _handle_benchmark,
+    _handle_chat,
+    _handle_desktop,
+    _handle_doctor,
+    _handle_init_mcp,
+    _handle_monitor,
+    _handle_scan_models,
+    _handle_serve_acp,
+    _handle_serve_mcp,
+    _handle_sessions,
+    _handle_skill,
+    _handle_smoke,
+)
+
+
+def _handle_skeletonize(args: argparse.Namespace) -> int:
+    from ..ast_compactor import skeletonize_file
+
+    try:
+        skeleton = skeletonize_file(str(args.file), target_symbols=args.symbols)
+        if getattr(args, "json", False):
+            print(
+                json.dumps(
+                    {"file": str(args.file), "symbols": args.symbols, "skeleton": skeleton},
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+        else:
+            try:
+                print(skeleton)
+            except UnicodeEncodeError:
+                if hasattr(sys.stdout, "buffer"):
+                    sys.stdout.buffer.write(skeleton.encode("utf-8", errors="replace"))
+                    sys.stdout.buffer.write(b"\n")
+                    sys.stdout.buffer.flush()
+                else:
+                    print(skeleton.encode("ascii", errors="replace").decode("ascii"))
+        return 0
+    except Exception as error:
+        if getattr(args, "json", False):
+            print(
+                json.dumps(
+                    {"status": "failed", "error": str(error)},
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+        else:
+            print(f"Error skeletonizing file: {error}", file=sys.stderr)
+        return 1
+
+
+def _handle_lint_patch(args: argparse.Namespace) -> int:
+    from ..semantic_linter import lint_patch_in_memory
+
+    patch_str = args.patch
+    if args.patch_file:
+        patch_str = Path(args.patch_file).read_text(encoding="utf-8-sig", errors="replace")
+    if not patch_str:
+        if getattr(args, "json", False):
+            print(
+                json.dumps(
+                    {"valid": False, "error": "No patch specified"},
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+        else:
+            print("Error: No patch specified via --patch or --patch-file", file=sys.stderr)
+        return 2
+    report = lint_patch_in_memory(str(args.workspace), patch_str)
+    if getattr(args, "json", False):
+        print(
+            json.dumps(
+                {
+                    "valid": report.valid,
+                    "diagnostics": [
+                        {"file": d.file, "line": d.line, "message": d.message, "rule": d.rule}
+                        for d in report.diagnostics
+                    ],
+                    "prescriptions": list(report.prescriptions),
+                },
+                ensure_ascii=False,
+                indent=2,
+            )
+        )
+    else:
+        if report.valid:
+            print("[OK] Patch passed fast static linter gates without issues.")
+        else:
+            print("[FAIL] Patch failed static linter gates:")
+            for p in report.prescriptions:
+                print(f"  - {p}")
+    return 0 if report.valid else 1
+
+
+def _handle_spill_read(args: argparse.Namespace) -> int:
+    from ..spill import read_spill
+
+    loc = args.opt_locator or args.locator
+    if not loc:
+        if getattr(args, "json", False):
+            print(json.dumps({"status": "failed", "error": "Spill locator is required"}, ensure_ascii=False, indent=2))
+        else:
+            print("Error: spill locator is required", file=sys.stderr)
+        return 2
+    try:
+        content = read_spill(loc, offset_line=args.offset, limit_lines=args.limit)
+        if getattr(args, "json", False):
+            print(
+                json.dumps(
+                    {"locator": loc, "offset": args.offset, "limit": args.limit, "content": content},
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+        else:
+            try:
+                print(content)
+            except UnicodeEncodeError:
+                if hasattr(sys.stdout, "buffer"):
+                    sys.stdout.buffer.write(content.encode("utf-8", errors="replace"))
+                    sys.stdout.buffer.write(b"\n")
+                    sys.stdout.buffer.flush()
+                else:
+                    print(content.encode("ascii", errors="replace").decode("ascii"))
+        return 0
+    except Exception as error:
+        if getattr(args, "json", False):
+            print(json.dumps({"status": "failed", "error": str(error)}, ensure_ascii=False, indent=2))
+        else:
+            print(f"Error reading spill: {error}", file=sys.stderr)
+        return 1
+
+
+def _handle_grep(args: argparse.Namespace) -> int:
+    from ..ripgrep import ripgrep_search
+
+    try:
+        globs = args.paths if args.paths else None
+        matches = ripgrep_search(
+            args.query,
+            root=args.workspace,
+            globs=globs,
+            is_regex=args.regex,
+            case_sensitive=args.case_sensitive,
+            max_results=args.max_results,
+        )
+        if getattr(args, "json", False):
+            print(
+                json.dumps(
+                    {
+                        "query": args.query,
+                        "count": len(matches),
+                        "matches": [
+                            {"file": m.file, "line": m.line_number, "text": m.line_content}
+                            for m in matches
+                        ],
+                    },
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+        else:
+            for m in matches:
+                print(f"{m.file}:{m.line_number}: {m.line_content}")
+        return 0
+    except Exception as error:
+        if getattr(args, "json", False):
+            print(json.dumps({"status": "failed", "error": str(error)}, ensure_ascii=False, indent=2))
+        else:
+            print(f"Error during grep: {error}", file=sys.stderr)
+        return 1
+
+
+def _handle_lsp(args: argparse.Namespace) -> int:
+    from ..lsp import LspManager, LspPosition
+
+    try:
+        manager = LspManager(workspace_root=args.workspace)
+        if args.operation == "definition":
+            res = manager.go_to_definition(args.file, line=args.line, character=args.char, workspace_root=args.workspace)
+            data = [r.to_dict() for r in res]
+        elif args.operation == "references":
+            res = manager.find_references(args.file, line=args.line, character=args.char, workspace_root=args.workspace)
+            data = [r.to_dict() for r in res]
+        elif args.operation == "hover":
+            h_res = manager.hover(args.file, line=args.line, character=args.char, workspace_root=args.workspace)
+            data = h_res.to_dict() if h_res else None
+        elif args.operation == "symbols":
+            syms = manager.document_symbols(args.file, workspace_root=args.workspace)
+            data = [s.to_dict() for s in syms]
+        else:
+            data = None
+
+        if getattr(args, "json", False):
+            print(
+                json.dumps(
+                    {"operation": args.operation, "file": str(args.file), "result": data},
+                    ensure_ascii=False,
+                    indent=2,
+                )
+            )
+        else:
+            print(json.dumps(data, ensure_ascii=False, indent=2))
+        return 0
+    except Exception as error:
+        if getattr(args, "json", False):
+            print(json.dumps({"status": "failed", "error": str(error)}, ensure_ascii=False, indent=2))
+        else:
+            print(f"Error during LSP query: {error}", file=sys.stderr)
+        return 1
+
+
+def _handle_init_agent(args: argparse.Namespace) -> int:
+    import os
+
+    from ..profiles import get_profile
+
+    base_url = args.desktop_url.rstrip("/")
+    model = getattr(args, "model", None)
+    if not model:
+        try:
+            profile = get_profile(os.environ.get("LCA_PROFILE") or "qwen2.5-coder")
+            raw = str(getattr(profile, "model", "") or "qwen2.5-coder")
+            model = raw if ":" in raw else f"{raw}:latest"
+        except Exception:
+            model = "qwen2.5-coder:latest"
+
+    def emit(payload: dict, human: list[str], code: int = 0) -> int:
+        if getattr(args, "json", False):
+            print(json.dumps(payload, ensure_ascii=False, indent=2))
+        else:
+            print("\n".join(human))
+        return code
+
+    if args.agent == "codex":
+        toml_block = (
+            "[model_providers.local_agent]\n"
+            f'name = "Local Coding Agent (Desktop Harness)"\n'
+            f'base_url = "{base_url}/v1"\n'
+            'env_key = "LOCAL_AGENT_API_KEY"\n'
+            'wire_api = "chat"\n'
+        )
+        launch_cmd = (
+            f'codex -c model_provider=local_agent -m "{model}"  '
+            "(set LOCAL_AGENT_API_KEY first; the Desktop Harness ignores its value)"
+        )
+        env_hint = (
+            f'PowerShell: $env:LOCAL_AGENT_API_KEY="local"   |   sh/bash: export LOCAL_AGENT_API_KEY=local'
+        )
+        config_path = None
+        written = False
+        error_msg = None
+        if args.write:
+            codex_home = Path(os.environ.get("CODEX_HOME") or (Path.home() / ".codex"))
+            config_path = codex_home / "config.toml"
+            try:
+                existing = config_path.read_text(encoding="utf-8") if config_path.exists() else ""
+                if "[model_providers.local_agent]" in existing:
+                    return emit(
+                        {"status": "failed", "error": f"{config_path} already defines [model_providers.local_agent]; edit it manually."},
+                        [f"[REFUSED] {config_path} already defines [model_providers.local_agent]. Edit it manually instead of duplicating."],
+                        1,
+                    )
+                config_path.parent.mkdir(parents=True, exist_ok=True)
+                with open(config_path, "a", encoding="utf-8") as fh:
+                    if existing and not existing.endswith("\n"):
+                        fh.write("\n")
+                    fh.write(toml_block)
+                written = True
+            except OSError as os_error:
+                return emit(
+                    {"status": "failed", "error": str(os_error)},
+                    [f"[FAILED] Could not write {config_path}: {os_error}"],
+                    1,
+                )
+        payload = {
+            "status": "ok",
+            "agent": "codex",
+            "model": model,
+            "base_url": f"{base_url}/v1",
+            "config_path": str(config_path) if config_path else None,
+            "written": written,
+            "config_snippet": toml_block,
+            "launch_command": launch_cmd,
+        }
+        human = [
+            f"--- Codex -> Local Agent ({'written' if written else 'preview'}) ---",
+            toml_block,
+            f"Launch: {launch_cmd}",
+            f"Auth:   {env_hint}",
+            f"Prereq: start the harness first (`local-agent desktop`), then load a model in Local Inference Servers.",
+        ]
+        if config_path:
+            human.insert(1, f"Config: {config_path}")
+        return emit(payload, human)
+
+    # generic OpenAI-compatible target
+    payload = {
+        "status": "ok",
+        "agent": "generic",
+        "model": model,
+        "base_url": f"{base_url}/v1",
+        "env": {
+            "OPENAI_BASE_URL": f"{base_url}/v1",
+            "OPENAI_API_KEY": "local",
+        },
+    }
+    human = [
+        "--- Generic OpenAI-compatible client -> Local Agent ---",
+        f"  OPENAI_BASE_URL={base_url}/v1",
+        "  OPENAI_API_KEY=local                # value ignored by the Desktop Harness",
+        f"  Model id to request: {model}",
+        "Prereq: start the harness first (`local-agent desktop`), then load a model in Local Inference Servers.",
+    ]
+    return emit(payload, human)
+
+
+_HANDLERS = {
+    "delegate": _handle_delegate,
+    "run": _handle_delegate,
+    "decompose": _handle_decompose,
+    "atomize": _handle_decompose,
+    "profiles": _handle_profiles,
+    "memory": _handle_memory,
+    "calibrate": _handle_calibrate,
+    "apply": _handle_apply,
+    "init-skill": _handle_skill,
+    "skill": _handle_skill,
+    "doctor": _handle_doctor,
+    "init-mcp": _handle_init_mcp,
+    "test-run": _handle_smoke,
+    "smoke": _handle_smoke,
+    "serve-mcp": _handle_serve_mcp,
+    "serve-acp": _handle_serve_acp,
+    "monitor": _handle_monitor,
+    "ui": _handle_monitor,
+    "app": _handle_monitor,
+    "desktop": _handle_desktop,
+    "chat": _handle_chat,
+    "scan-models": _handle_scan_models,
+    "benchmark": _handle_benchmark,
+    "skeletonize": _handle_skeletonize,
+    "lint-patch": _handle_lint_patch,
+    "spill-read": _handle_spill_read,
+    "grep": _handle_grep,
+    "lsp": _handle_lsp,
+    "sessions": _handle_sessions,
+    "init-agent": _handle_init_agent,
+}
+
+
+def handle_subcommand(args: argparse.Namespace) -> int:
+    handler = _HANDLERS.get(args.subcommand)
+    if handler is None:
+        return -1
+    return handler(args)