ayder-cli 2.2.8__tar.gz → 2.3.0__tar.gz

{ayder_cli-2.2.8 → ayder_cli-2.3.0}/.gitignore

@@ -24,7 +24,6 @@ htmlcov/
 .venv
 TODO
 .env
-uv.lock
 
 # Project Spesific
 .ayder

{ayder_cli-2.2.8 → ayder_cli-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ayder-cli
-Version: 2.2.8
+Version: 2.3.0
 Summary: AI agent for any LLMs
 Project-URL: Homepage, https://github.com/ayder/ayder-cli
 Project-URL: Repository, https://github.com/ayder/ayder-cli.git
@@ -15,7 +15,7 @@ Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.12
 Requires-Dist: httpx
-Requires-Dist: loguru
+Requires-Dist: loguru<0.8,>=0.7
 Requires-Dist: ollama>=0.6.2
 Requires-Dist: openai
 Requires-Dist: python-dotenv>=1.0.0
@@ -209,10 +209,23 @@ tool_tags = ["core", "metadata"]  # Enabled tool tags (see /plugin)
 agent_timeout = 300           # Seconds before a background agent is cancelled
 
 [logging]
-file_enabled = true
-file_path = ".ayder/log/ayder.log"
-rotation = "10 MB"
-retention = "7 days"
+file_enabled  = true                     # master switch for ALL file logging
+file_path     = ".ayder/log/ayder.log"
+error_path    = ".ayder/log/errors.log"  # always written unless file_enabled = false
+trace_enabled = false
+trace_path    = ".ayder/log/trace.jsonl"
+rotation      = "10 MB"
+retention     = "7 days"
+# level = "INFO"   # optional; omitted entirely when unset, which means NONE.
+                   # NONE, ERROR, WARNING, INFO, DEBUG, TRACE
+
+[logging.channels]
+# Per-channel level overrides. Unlisted channels inherit the global level.
+# Channels: llm, tool, agent, context, plugin, ui, core, external
+#   llm      = "TRACE"     # verbose LLM traffic
+#   plugin   = "WARNING"   # quiet plugin discovery
+#   external = "ERROR"     # throttle third-party libraries
+#   ui       = "NONE"      # disable this channel entirely
 
 [context_manager]
 enabled = true
@@ -389,7 +402,7 @@ You can also manually manage context with the `context` tool and its slash-comma
 | `/notes` | Browse and edit markdown notes |
 | `/skill` | Activate a domain skill from `.ayder/skills/` via the shared `skill` tool backend |
 | `/verbose` | Toggle verbose mode |
-| `/logging` | Set log level for current session (NONE, ERROR, WARNING, INFO, DEBUG) |
+| `/logging` | Set log level for current session (NONE, ERROR, WARNING, INFO, DEBUG, TRACE) |
 | `/compact` | Summarize conversation, save a context snapshot, clear, and reload |
 | `/save-context` | Summarize conversation and save it to a named context slot (no clear) |
 | `/load-context` | Load a saved context slot and restore it |
@@ -406,9 +419,20 @@ You can also manually manage context with the `context` tool and its slash-comma
 The LLM can also call `skill(action="list" | "load" | "unload")`
 automatically when a request clearly matches an available project skill.
 
-- Default: when logging is enabled, logs go to `.ayder/log/ayder.log` (not shown on screen).
+- Errors are always captured to `.ayder/log/errors.log`, even when
+  `logging_level` is `NONE`. Set `file_enabled = false` under `[logging]` to
+  turn off all file logging including errors.
+- Unhandled exceptions, SIGTERM and SIGINT are captured to
+  `.ayder/log/errors.log`. Records in flight are lost on `SIGKILL` (`kill -9`),
+  which no process can intercept.
+- Narrative logs go to `.ayder/log/ayder.log` when a level is set.
+- `--trace` writes structured events to `.ayder/log/trace.jsonl`. It is not a
+  log level.
+- `--log-channel llm,tool` limits console and narrative output to those
+  subsystems. It never filters the error log.
 - TUI `/logging` changes are session-only and do not modify `config.toml`.
-- CLI `--verbose [LEVEL]` enables stdout logging for that run.
+- CLI `--verbose` enables stdout logging for that run; it does not narrow
+  channels.
 
 ### Keyboard Shortcuts
 

{ayder_cli-2.2.8 → ayder_cli-2.3.0}/README.md

@@ -166,10 +166,23 @@ tool_tags = ["core", "metadata"]  # Enabled tool tags (see /plugin)
 agent_timeout = 300           # Seconds before a background agent is cancelled
 
 [logging]
-file_enabled = true
-file_path = ".ayder/log/ayder.log"
-rotation = "10 MB"
-retention = "7 days"
+file_enabled  = true                     # master switch for ALL file logging
+file_path     = ".ayder/log/ayder.log"
+error_path    = ".ayder/log/errors.log"  # always written unless file_enabled = false
+trace_enabled = false
+trace_path    = ".ayder/log/trace.jsonl"
+rotation      = "10 MB"
+retention     = "7 days"
+# level = "INFO"   # optional; omitted entirely when unset, which means NONE.
+                   # NONE, ERROR, WARNING, INFO, DEBUG, TRACE
+
+[logging.channels]
+# Per-channel level overrides. Unlisted channels inherit the global level.
+# Channels: llm, tool, agent, context, plugin, ui, core, external
+#   llm      = "TRACE"     # verbose LLM traffic
+#   plugin   = "WARNING"   # quiet plugin discovery
+#   external = "ERROR"     # throttle third-party libraries
+#   ui       = "NONE"      # disable this channel entirely
 
 [context_manager]
 enabled = true
@@ -346,7 +359,7 @@ You can also manually manage context with the `context` tool and its slash-comma
 | `/notes` | Browse and edit markdown notes |
 | `/skill` | Activate a domain skill from `.ayder/skills/` via the shared `skill` tool backend |
 | `/verbose` | Toggle verbose mode |
-| `/logging` | Set log level for current session (NONE, ERROR, WARNING, INFO, DEBUG) |
+| `/logging` | Set log level for current session (NONE, ERROR, WARNING, INFO, DEBUG, TRACE) |
 | `/compact` | Summarize conversation, save a context snapshot, clear, and reload |
 | `/save-context` | Summarize conversation and save it to a named context slot (no clear) |
 | `/load-context` | Load a saved context slot and restore it |
@@ -363,9 +376,20 @@ You can also manually manage context with the `context` tool and its slash-comma
 The LLM can also call `skill(action="list" | "load" | "unload")`
 automatically when a request clearly matches an available project skill.
 
-- Default: when logging is enabled, logs go to `.ayder/log/ayder.log` (not shown on screen).
+- Errors are always captured to `.ayder/log/errors.log`, even when
+  `logging_level` is `NONE`. Set `file_enabled = false` under `[logging]` to
+  turn off all file logging including errors.
+- Unhandled exceptions, SIGTERM and SIGINT are captured to
+  `.ayder/log/errors.log`. Records in flight are lost on `SIGKILL` (`kill -9`),
+  which no process can intercept.
+- Narrative logs go to `.ayder/log/ayder.log` when a level is set.
+- `--trace` writes structured events to `.ayder/log/trace.jsonl`. It is not a
+  log level.
+- `--log-channel llm,tool` limits console and narrative output to those
+  subsystems. It never filters the error log.
 - TUI `/logging` changes are session-only and do not modify `config.toml`.
-- CLI `--verbose [LEVEL]` enables stdout logging for that run.
+- CLI `--verbose` enables stdout logging for that run; it does not narrow
+  channels.
 
 ### Keyboard Shortcuts
 

{ayder_cli-2.2.8 → ayder_cli-2.3.0}/docs/PROJECT_STRUCTURE.md

@@ -160,7 +160,8 @@ cli.py:main()
 | `core/context_manager_factory.py` | Registry-based factory (OCP) | `ContextManagerFactory`, `context_manager_factory` |
 | `core/cache_monitor.py` | Timing-based KV-cache hit detection | `CacheMonitor`, `CacheStatus`, `CacheSample` |
 | `console.py` | Rich console singleton | `console` |
-| `logging_config.py` | Logger setup (loguru + stdlib bridge) | `setup_logging()` |
+| `log.py` | Channel-scoped loguru facade; leaf module so `logging_config.py` and `core/config.py` can both depend on it | `get_logger()`, `LOG_LEVELS`, `CHANNELS`, `level_no()`, `flush()` |
+| `logging_config.py` | Logger setup (loguru + stdlib bridge) | `setup_logging()`, `LoggingSettings` |
 | `version.py` | Package version constant | `__version__` |
 
 ### Root-Level Application Modules

{ayder_cli-2.2.8 → ayder_cli-2.3.0}/docs/config.toml.example

@@ -117,10 +117,23 @@ theme = "ayder"
 palette = "auto"
 
 [logging]
-file_enabled = true
-file_path = ".ayder/log/ayder.log"
-rotation = "10 MB"
-retention = "7 days"
+file_enabled  = true                     # master switch for ALL file logging
+file_path     = ".ayder/log/ayder.log"
+error_path    = ".ayder/log/errors.log"  # always written unless file_enabled = false
+trace_enabled = false
+trace_path    = ".ayder/log/trace.jsonl"
+rotation      = "10 MB"
+retention     = "7 days"
+# level = "INFO"   # optional; omitted entirely when unset, which means NONE.
+                   # NONE, ERROR, WARNING, INFO, DEBUG, TRACE
+
+[logging.channels]
+# Per-channel level overrides. Unlisted channels inherit the global level.
+# Channels: llm, tool, agent, context, plugin, ui, core, external
+#   llm      = "TRACE"     # verbose LLM traffic
+#   plugin   = "WARNING"   # quiet plugin discovery
+#   external = "ERROR"     # throttle third-party libraries
+#   ui       = "NONE"      # disable this channel entirely
 
 [context_manager]
 enabled = true

{ayder_cli-2.2.8 → ayder_cli-2.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "ayder-cli"
-version = "2.2.8"
+version = "2.3.0"
 description = "AI agent for any LLMs"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -22,7 +22,9 @@ classifiers = [
 dependencies = [
     "openai",
     "ollama>=0.6.2",
-    "loguru",
+    # Bounded deliberately: the masking sinks wrap Loguru's private FileSink /
+    # Message / StreamSink shapes (§F5-R6), guarded by `_shape_guard()`.
+    "loguru>=0.7,<0.8",
     "httpx",
     "rich>=13.0.0",
     # Pinned exactly to match the runtime: 8.2.5+ replaced the single
@@ -85,7 +87,16 @@ lint = "ruff check src/"
 lint-fix = "ruff check src/ --fix"
 typecheck = "mypy src/"
 format = "ruff format src/"
-check-all = ["lint", "typecheck", "test"]
+check-all = ["lint", "typecheck", "gates", "test"]
+
+[tool.poe.tasks.gates]
+help = "Run the logging AST gates"
+sequence = [
+    { cmd = "python scripts/find_percent_logging.py" },
+    { cmd = "python scripts/check_logging_imports.py" },
+    { cmd = "python scripts/check_exception_handlers.py" },
+    { cmd = "python scripts/check_log_arguments.py" },
+]
 
 [tool.poe.tasks.clean]
 help = "Deep clean cache and build artifacts"
@@ -113,3 +124,11 @@ ignore_missing_imports = false
 [[tool.mypy.overrides]]
 module = ["zhipuai", "dashscope"]
 ignore_missing_imports = true
+
+[tool.ruff.lint]
+# Explicit rule set: ruff 0.16 widened its defaults from 59 to 413 rules,
+# so an implicit default + extend-select drifts with the installed version.
+select = ["E4", "E7", "E9", "F", "TRY400", "TRY401", "BLE001", "LOG", "G"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = ["BLE001", "G004"]

ayder_cli-2.3.0/scripts/check_exception_handlers.py

@@ -0,0 +1,269 @@
+#!/usr/bin/env python3
+"""Gate: every broad exception handler must satisfy the logging policy.
+
+Verdicts:
+  PASS    - a reachable satisfying statement was found
+  FAIL    - swallows silently, or exits without satisfying
+  REPORT  - branches before satisfying; needs a human
+"""
+from __future__ import annotations
+
+import argparse
+import ast
+import pathlib
+import sys
+
+LEVELS = {"trace", "debug", "info", "success", "warning", "error",
+          "exception", "critical"}
+BROAD = {"Exception", "BaseException"}
+
+# Resolved from this file, not the cwd: scripts/<this>.py -> repo root.
+REPO = pathlib.Path(__file__).resolve().parent.parent
+SRC_ROOT = REPO / "src" / "ayder_cli"
+DEFAULT_BASELINE = REPO / "scripts" / "exception_baseline.txt"
+
+# Frozen census (§C10). A different number means the gate is looking at the
+# wrong tree, or the census moved without the plan being updated.
+EXPECTED_BROAD = 131
+BRANCHING = (ast.If, ast.Try, ast.For, ast.While, ast.With, ast.Match)
+TERMINAL = (ast.Return, ast.Break, ast.Continue, ast.Pass)
+
+
+def _is_broad(handler: ast.ExceptHandler) -> bool:
+    """Bare `except:` is NOT in scope — see CONTRACTS C10."""
+    t = handler.type
+    if t is None:
+        return False
+    if isinstance(t, ast.Name):
+        return t.id in BROAD
+    if isinstance(t, ast.Tuple):
+        return any(isinstance(e, ast.Name) and e.id in BROAD for e in t.elts)
+    return False
+
+
+LOGGERS = {"logger", "llm_log", "tool_log"}
+
+
+def _approved_receiver(node: ast.expr) -> bool:
+    """Only the §C8 bindings satisfy the policy.
+
+    Without this, any object's `.exception()`/`.opt()` would pass — a Future's
+    `.exception()` being the obvious trap.
+    """
+    return isinstance(node, ast.Name) and node.id in LOGGERS
+
+
+def _is_exception_log(node: ast.stmt) -> bool:
+    """Either logger.opt(exception=True).<level>(...) or logger.exception(...)."""
+    if not isinstance(node, ast.Expr) or not isinstance(node.value, ast.Call):
+        return False
+    call = node.value
+    if not isinstance(call.func, ast.Attribute):
+        return False
+
+    # Form 2: logger.exception(...) — loguru shorthand, carries the exception.
+    # ruff TRY400 actively pushes code toward this, so it MUST be accepted —
+    # but only on a real logger. `future.exception()` must not satisfy policy.
+    if call.func.attr == "exception":
+        return _approved_receiver(call.func.value)
+
+    # Form 1: logger.opt(exception=True).<level>(...)
+    if call.func.attr not in LEVELS:
+        return False
+    recv = call.func.value
+    if not (isinstance(recv, ast.Call) and isinstance(recv.func, ast.Attribute)
+            and recv.func.attr == "opt"
+            and _approved_receiver(recv.func.value)):
+        return False
+    return any(kw.arg == "exception" and getattr(kw.value, "value", None) is True
+               for kw in recv.keywords)
+
+
+def _is_failure_return(node: ast.stmt) -> bool:
+    """ToolError(...) or ExecutionResult(success=False, ...) — nothing else."""
+    if not isinstance(node, ast.Return) or node.value is None:
+        return False
+    v = node.value
+    if not isinstance(v, ast.Call):
+        return False
+    name = getattr(v.func, "id", None) or getattr(v.func, "attr", None)
+
+    if name == "ToolError":
+        return True
+    if name == "ExecutionResult":
+        # success=True is a SUCCESS return and satisfies nothing.
+        return any(kw.arg == "success" and getattr(kw.value, "value", None) is False
+                   for kw in v.keywords)
+    return False
+
+
+def _satisfies(node: ast.stmt) -> bool:
+    return (isinstance(node, ast.Raise)
+            or _is_failure_return(node)
+            or _is_exception_log(node))
+
+
+def _has_reasoned_marker(line: str) -> bool:
+    """`# noqa: AYDER-EXC <reason>` — the reason text is mandatory.
+
+    A bare marker records no decision, so it must not suppress.
+    """
+    idx = line.find("AYDER-EXC")
+    if idx == -1:
+        return False
+    return bool(line[idx + len("AYDER-EXC"):].strip(" :-\t"))
+
+
+def _verdict(handler: ast.ExceptHandler) -> str:
+    for stmt in handler.body:
+        if _satisfies(stmt):
+            return "PASS"
+        if isinstance(stmt, BRANCHING):
+            return "REPORT"
+        if isinstance(stmt, TERMINAL):
+            return "FAIL"        # exits without satisfying
+    return "FAIL"                 # fell off the end
+
+
+def _broad_handlers(path: str, tree: ast.AST) -> list[tuple[ast.ExceptHandler, str]]:
+    """Yield (handler, stable_id), id = `path::qualname::ordinal`.
+
+    NEVER key a finding by line number. Step 3-02 inserts an import into 15
+    files and every handler below it shifts; each remediation shifts the rest
+    again. A line-keyed baseline reports every untouched handler as a new
+    finding on the very next commit. This id survives both — verified: 119
+    handlers, 119 unique ids, byte-identical after prepending imports and
+    after editing a handler body.
+    """
+    out: list[tuple[ast.ExceptHandler, str]] = []
+    stack: list[str] = []
+    counter: dict[str, int] = {}
+
+    class _V(ast.NodeVisitor):
+        def _scope(self, node):
+            stack.append(node.name)
+            self.generic_visit(node)
+            stack.pop()
+
+        visit_FunctionDef = visit_AsyncFunctionDef = visit_ClassDef = _scope
+
+        def visit_Try(self, node):
+            for h in node.handlers:
+                if _is_broad(h):
+                    key = f"{path}::{'.'.join(stack) or '<module>'}"
+                    counter[key] = counter.get(key, 0) + 1
+                    out.append((h, f"{key}::{counter[key]}"))
+            self.generic_visit(node)
+
+        # PEP 654 `except*` groups parse to a distinct node type (ast.TryStar,
+        # not ast.Try) with the same `.handlers` shape. Without this alias they
+        # are invisible to the census: generic_visit walks straight through
+        # into the ExceptHandler children and every `except* Exception:` is
+        # silently uncounted rather than silently failing — the gate would
+        # report success over a hole in its own coverage.
+        visit_TryStar = visit_Try
+
+    _V().visit(tree)
+    return out
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--path", default=str(SRC_ROOT))
+    ap.add_argument("--baseline", default=str(DEFAULT_BASELINE))
+    ap.add_argument("--write-baseline", action="store_true")
+    ap.add_argument("--expect-broad", type=int, default=None,
+                    help="fail unless exactly this many broad handlers are found")
+    args = ap.parse_args()
+
+    root = pathlib.Path(args.path)
+    if not root.is_dir():
+        print(f"ABORT: source root does not exist: {root}", file=sys.stderr)
+        return 2
+    py_files = sorted(root.rglob("*.py"))
+    if not py_files:
+        print(f"ABORT: no Python files under {root}", file=sys.stderr)
+        return 2
+
+    findings: list = []
+    problems: list[str] = []
+    broad_total = 0
+    examined = 0
+    for p in py_files:
+        text = p.read_text()
+        lines = text.splitlines()
+        try:
+            tree = ast.parse(text, filename=str(p))
+        except SyntaxError as e:
+            # Never skip silently — an unparseable file is a hole in coverage.
+            problems.append(f"UNPARSEABLE {p}: {e}")
+            continue
+        examined += 1
+        try:
+            # REPOSITORY-relative, so ids read `src/ayder_cli/...` exactly as
+            # they did before the root was resolved absolutely. The per-directory
+            # steps grep on that prefix; changing it would silently break them.
+            rel = str(p.resolve().relative_to(REPO))
+        except ValueError:
+            rel = str(p)
+        for node, stable_id in _broad_handlers(rel, tree):
+            broad_total += 1
+            line = lines[node.lineno - 1] if node.lineno <= len(lines) else ""
+            if _has_reasoned_marker(line):
+                continue
+            v = _verdict(node)
+            if v != "PASS":
+                # The KEY is verdict + stable id, and nothing else. The line
+                # number is carried alongside for humans and is never compared.
+                findings.append((f"{v} {stable_id}", f"{rel}:{node.lineno}"))
+
+    keys = {k for k, _ in findings}
+    where = dict(findings)
+
+    # Coverage summary on EVERY run, before any verdict is printed.
+    print(f"files={examined}/{len(py_files)}  broad={broad_total}  "
+          f"findings={len(keys)}  root={root}")
+
+    if problems:
+        for x in problems:
+            print(f"  {x}")
+        print(f"FAIL — {len(problems)} unparseable file(s)")
+        return 1
+
+    expect = args.expect_broad
+    if expect is None and root.resolve() == SRC_ROOT.resolve():
+        expect = EXPECTED_BROAD                  # full-tree run: census is frozen
+    if expect is not None and broad_total != expect:
+        print(f"FAIL — census: found {broad_total} broad handlers, expected {expect}")
+        return 1
+
+    if args.write_baseline:
+        pathlib.Path(args.baseline).write_text("\n".join(sorted(keys)) + "\n")
+        print(f"baseline written: {len(keys)} findings")
+        return 0
+
+    for k in sorted(keys):
+        print(f"{k}\t# {where[k]}")          # location is display only
+
+    baseline = pathlib.Path(args.baseline)
+    if not baseline.exists():
+        print(f"\n{len(keys)} findings (no baseline)")
+        return 0
+
+    # PER-FINDING comparison on the stable id. A count check would let one
+    # finding vanish while a new one appears and still pass.
+    allowed = {line.split("\t")[0].strip() for line in baseline.read_text().splitlines()
+               if line.strip()}
+    new = sorted(keys - allowed)
+    if new:
+        print(f"\n{len(new)} NEW finding(s) not in baseline:")
+        for n in new:
+            print(f"  {n}\t# {where[n]}")
+        return 1
+    fixed = len(allowed) - len(keys & allowed)
+    print(f"\n{len(keys)} findings, 0 new, {fixed} fixed since baseline")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())