agentlint 2.5.2__tar.gz → 2.5.3__tar.gz

{agentlint-2.5.2 → agentlint-2.5.3}/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Changelog
 
+## v2.5.3 (2026-05-25) — AgentChute Queue Baseline
+
+This patch release fixes AgentChute onboarding for existing AgentLint users
+with local event history.
+
+- Fixes `agentlint queue flush`, which could crash because the CLI wrapper did
+  not pass the newer queue batch/time-budget arguments.
+- Baselines the local AgentChute queue when a machine is paired with a new
+  license key, so pre-pairing local history is not uploaded as fresh dashboard
+  activity.
+- Adds `agentlint queue discard-pending --yes` for support cases where a user
+  intentionally wants to advance the local queue cursor without uploading
+  pending events.
+- Improves `agentlint policy explain` by listing active rule IDs, making policy
+  template debugging easier.
+- Adds regression coverage for the `block-curl-sh` policy template simulation.
+
+---
+
 ## v2.5.2 (2026-05-25) — AgentChute Credential Persistence
 
 This patch release fixes the first-run AgentChute pairing flow so users can run

{agentlint-2.5.2 → agentlint-2.5.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agentlint
-Version: 2.5.2
+Version: 2.5.3
 Summary: Real-time quality guardrails for AI coding agents
 Project-URL: Homepage, https://github.com/mauhpr/agentlint
 Project-URL: Repository, https://github.com/mauhpr/agentlint

{agentlint-2.5.2 → agentlint-2.5.3}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentlint"
-version = "2.5.2"
+version = "2.5.3"
 description = "Real-time quality guardrails for AI coding agents"
 readme = "README.md"
 license = "MIT"

{agentlint-2.5.2 → agentlint-2.5.3}/src/agentlint/__init__.py

@@ -1,6 +1,6 @@
 """AgentLint - Real-time quality guardrails for AI coding agents."""
 
-__version__ = "2.5.2"
+__version__ = "2.5.3"
 
 from agentlint.core.models import (
     AgentEvent,

{agentlint-2.5.2 → agentlint-2.5.3}/src/agentlint/agentchute/queue.py

@@ -89,6 +89,24 @@ def enqueue_event(event: dict, *, session_key: str, config: Any | None = None) -
     return event_id
 
 
+def mark_existing_events_delivered() -> int:
+    """Advance delivery to the current queue tail without deleting events.
+
+    This is used when AgentChute is first paired, or when the local license key
+    changes. Local history can predate the cloud workspace and should not be
+    uploaded as new team activity.
+    """
+    lines = _read_lines()
+    total = len(lines)
+    cursor = int(_load_json(_cursor_path(), {"offset": 0}).get("offset", 0))
+    if cursor >= total:
+        _clear_retry()
+        return 0
+    _save_json(_cursor_path(), {"offset": total})
+    _clear_retry()
+    return total - cursor
+
+
 def trigger_background_flush(config: Any | None = None) -> None:
     """Start a detached flusher process if AgentChute is enabled.
 

{agentlint-2.5.2 → agentlint-2.5.3}/src/agentlint/cli.py

@@ -91,6 +91,26 @@ def _agentchute_policy_metadata() -> dict:
     }
 
 
+def _baseline_agentchute_queue_if_new_key(previous_key: str | None, next_key: str) -> int:
+    if previous_key == next_key:
+        return 0
+    try:
+        from agentlint.agentchute.queue import mark_existing_events_delivered
+
+        return mark_existing_events_delivered()
+    except Exception:
+        logger.debug("Failed to baseline AgentChute queue", exc_info=True)
+        return 0
+
+
+def _echo_queue_baseline(skipped: int) -> None:
+    if skipped:
+        click.echo(
+            f"AgentChute queue: skipped {skipped} pre-pairing event(s); "
+            "future events will upload normally"
+        )
+
+
 def _codex_hooks_enabled() -> bool:
     """Return whether current Codex native hooks are enabled in config.toml."""
     config_path = Path.home() / ".codex" / "config.toml"
@@ -1145,6 +1165,7 @@ def onboard(
             click.echo(f"Would persist AgentChute credentials to {local_credentials_path()}")
             click.echo(f"Would persist AgentChute env vars to {_default_shell_profile()}")
         else:
+            skipped = _baseline_agentchute_queue_if_new_key(existing_key, team_key)
             credentials_path = save_local_credentials(
                 api_url=api_url,
                 license_key=team_key,
@@ -1156,6 +1177,7 @@ def onboard(
             os.environ["AGENTCHUTE_ENABLED"] = "true"
             click.echo(f"Saved AgentChute credentials to {credentials_path}")
             click.echo(f"Saved AgentChute env vars to {profile}")
+            _echo_queue_baseline(skipped)
 
     for platform in selected:
         state, path = _hook_status(platform, project_dir)
@@ -1399,9 +1421,10 @@ def env_group():
 @click.option("--profile", default=None, help="Shell profile to update")
 def env_install(team_key: str, api_url: str | None, profile: str | None):
     """Persist AgentChute env vars into the shell profile."""
-    from agentlint.agentchute.settings import get_api_url, save_local_credentials
+    from agentlint.agentchute.settings import get_api_url, get_license_key, save_local_credentials
 
     resolved_api_url = api_url or get_api_url()
+    skipped = _baseline_agentchute_queue_if_new_key(get_license_key(), team_key)
     credentials_path = save_local_credentials(
         api_url=resolved_api_url,
         license_key=team_key,
@@ -1417,6 +1440,7 @@ def env_install(team_key: str, api_url: str | None, profile: str | None):
     os.environ["AGENTCHUTE_ENABLED"] = "true"
     click.echo(f"Saved AgentChute credentials to {credentials_path}")
     click.echo(f"Saved AgentChute env vars to {path}")
+    _echo_queue_baseline(skipped)
     click.echo("This terminal can use AgentChute immediately.")
     click.echo("Future terminals can also load env vars with: source " + str(path))
 
@@ -1478,10 +1502,11 @@ def env_remove(profile: str | None):
 @click.option("--manual", is_flag=True, help="Paste a license key instead of using dashboard pairing")
 def login(dashboard_url: str | None, api_url: str | None, project_dir: str | None, manual: bool):
     """Pair this machine with AgentChute through the dashboard."""
-    from agentlint.agentchute.settings import get_api_url, save_local_credentials
+    from agentlint.agentchute.settings import get_api_url, get_license_key, save_local_credentials
 
     project_dir = _resolve_project_dir(project_dir)
     api_url = api_url or get_api_url()
+    existing_key = get_license_key()
     dashboard_url = dashboard_url or (
         "http://localhost:3001/dashboard/settings/license"
         if "localhost" in api_url
@@ -1532,6 +1557,7 @@ def login(dashboard_url: str | None, api_url: str | None, project_dir: str | Non
         webbrowser.open(dashboard_url)
         team_key = click.prompt("Paste the AgentChute license key", hide_input=True)
 
+    skipped = _baseline_agentchute_queue_if_new_key(existing_key, team_key)
     credentials_path = save_local_credentials(
         api_url=api_url,
         license_key=team_key,
@@ -1546,6 +1572,7 @@ def login(dashboard_url: str | None, api_url: str | None, project_dir: str | Non
         _ensure_agentchute_enabled_config(config_path)
     click.echo(f"Paired. AgentChute credentials saved to {credentials_path}")
     click.echo(f"Shell env vars saved to {profile}")
+    _echo_queue_baseline(skipped)
     click.echo("This terminal can use AgentChute immediately.")
 
 
@@ -1569,9 +1596,41 @@ def queue_status_command():
 
 @queue_group.command("flush")
 @click.option("--max-events", default=None, type=int, help="Maximum events to flush")
-def queue_flush_command(max_events: int | None):
+@click.option("--batch-size", default=50, type=int, help="Maximum events per API batch")
+@click.option("--time-budget", default=3.0, type=float, help="Maximum seconds to spend flushing")
+def queue_flush_command(max_events: int | None, batch_size: int, time_budget: float):
     """Flush queued AgentChute events now."""
-    _flush_agentchute_queue(max_events=max_events, dry_run=False, background=False)
+    _flush_agentchute_queue(
+        max_events=max_events,
+        batch_size=batch_size,
+        time_budget=time_budget,
+        dry_run=False,
+        background=False,
+    )
+
+
+@queue_group.command("discard-pending")
+@click.option("--yes", is_flag=True, help="Skip confirmation")
+def queue_discard_pending_command(yes: bool):
+    """Mark pending AgentChute events delivered without uploading them."""
+    from agentlint.agentchute.queue import mark_existing_events_delivered, queue_status
+
+    status_data = queue_status()
+    pending = int(status_data.get("pending", 0) or 0)
+    if pending <= 0:
+        click.echo("AgentChute queue: no pending events.")
+        return
+    if not yes and not click.confirm(
+        f"Discard {pending} pending AgentChute event(s) without uploading?",
+        default=False,
+    ):
+        click.echo("AgentChute queue unchanged.")
+        return
+    skipped = mark_existing_events_delivered()
+    click.echo(
+        f"AgentChute queue: discarded {skipped} pending event(s); "
+        "future events will upload normally"
+    )
 
 
 @queue_group.command("inspect")
@@ -2325,6 +2384,7 @@ def policy_explain_command(output_format: str):
     rules = [rule for rule in policy.get("rules") or [] if isinstance(rule, dict)]
     active_rules = [rule for rule in rules if rule.get("enabled", True) is not False]
     locked_rules = [rule for rule in active_rules if rule.get("locked") is True]
+    active_rule_ids = [str(rule.get("id")) for rule in active_rules if rule.get("id")]
     packs = required_packs(policy)
     missing = missing_required_packs(policy)
     cloud_feeds = [
@@ -2339,6 +2399,7 @@ def policy_explain_command(output_format: str):
             "updated_at": policy.get("updated_at"),
             "organization_id": policy.get("organization_id"),
             "rules": len(active_rules),
+            "rule_ids": active_rule_ids,
             "locked_rules": len(locked_rules),
             "required_packs": len(packs),
             "cloud_feeds": cloud_feeds,
@@ -2353,6 +2414,8 @@ def policy_explain_command(output_format: str):
     if policy.get("updated_at"):
         click.echo(f"Updated: {policy['updated_at']}")
     click.echo(f"Rules: {len(active_rules)} active, {len(locked_rules)} locked")
+    if active_rule_ids:
+        click.echo(f"Rule IDs: {', '.join(active_rule_ids[:10])}")
     click.echo(f"Required packs: {len(packs)}")
     if cloud_feeds:
         click.echo(f"Cloud feeds: {', '.join(cloud_feeds)}")

{agentlint-2.5.2 → agentlint-2.5.3}/tests/test_agentchute_policy_queue_sync.py

@@ -258,6 +258,36 @@ def test_queue_enqueue_flush_dry_run_and_status(tmp_path, monkeypatch):
     assert not (tmp_path / "flush.lock").exists()
 
 
+def test_queue_mark_existing_events_delivered_preserves_future_pending(tmp_path, monkeypatch):
+    from agentlint.agentchute import queue
+
+    monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(tmp_path))
+    (tmp_path / "queue.jsonl").write_text(
+        "\n".join(
+            [
+                json.dumps({"event_id": "old-1", "event": {"n": 1}}),
+                json.dumps({"event_id": "old-2", "event": {"n": 2}}),
+            ]
+        )
+        + "\n",
+        encoding="utf-8",
+    )
+    queue._save_json(tmp_path / "retry.json", {"failures": 2, "next_attempt_at": 123})
+
+    skipped = queue.mark_existing_events_delivered()
+
+    assert skipped == 2
+    assert queue.queue_status()["pending"] == 0
+    assert json.loads((tmp_path / "cursor.json").read_text())["offset"] == 2
+    assert not (tmp_path / "retry.json").exists()
+    assert queue.mark_existing_events_delivered() == 0
+
+    with open(tmp_path / "queue.jsonl", "a", encoding="utf-8") as f:
+        f.write(json.dumps({"event_id": "new-1", "event": {"n": 3}}) + "\n")
+
+    assert queue.queue_status()["pending"] == 1
+
+
 def test_queue_flush_dry_run_counts_limited_poison_entries(tmp_path, monkeypatch):
     from agentlint.agentchute import queue
 

{agentlint-2.5.2 → agentlint-2.5.3}/tests/test_cli.py

@@ -19,7 +19,7 @@ class TestMainCommand:
         result = runner.invoke(main, ["--version"])
 
         assert result.exit_code == 0
-        assert result.output.strip() == "agentlint 2.5.2"
+        assert result.output.strip() == "agentlint 2.5.3"
 
 
 class TestCheckCommand:
@@ -1106,6 +1106,48 @@ class TestMagicalUxCommands:
         explain = runner.invoke(main, ["policy", "explain"])
         assert "Updated: 2026-05-19T12:00:00Z" in status.output
         assert "Updated: 2026-05-19T12:00:00Z" in explain.output
+        assert "Rule IDs: org-block-forbidden-domain" in explain.output
+
+    def test_curl_pipe_policy_template_matches_cached_policy(self, tmp_path, monkeypatch) -> None:
+        policy_dir = tmp_path / "policy"
+        monkeypatch.setenv("AGENTLINT_AGENTCHUTE_POLICY_DIR", str(policy_dir))
+        monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(tmp_path / "queue"))
+        monkeypatch.setenv("AGENTCHUTE_LICENSE_KEY", "ac_team_test_secret")
+        (tmp_path / "agentlint.yml").write_text(
+            "packs:\n  - universal\nagentchute:\n  enabled: true\n"
+        )
+        policy_dir.mkdir()
+        (policy_dir / "policy.json").write_text(json.dumps({
+            "version": 1,
+            "updated_at": "2026-05-19T12:00:00Z",
+            "rules": [{
+                "id": "org-block-curl-pipe-sh",
+                "enabled": True,
+                "event": "PreToolUse",
+                "tool": "Bash",
+                "severity": "error",
+                "match": {
+                    "field": "command",
+                    "operator": "contains",
+                    "value": "| sh",
+                },
+                "message": "Blocked curl piped to shell.",
+            }],
+        }))
+
+        result = CliRunner().invoke(
+            main,
+            [
+                "test-policy",
+                "block-curl-sh",
+                "--project-dir",
+                str(tmp_path),
+                "--no-refresh",
+            ],
+        )
+
+        assert result.exit_code == 0
+        assert "Matched: org-block-curl-pipe-sh (error)" in result.output
 
     def test_policy_template_unknown_name_errors(self) -> None:
         result = CliRunner().invoke(main, ["test-policy", "unknown-template", "--no-refresh"])
@@ -1248,8 +1290,17 @@ class TestMagicalUxCommands:
 
     def test_login_persists_key_and_enables_existing_config(self, tmp_path, monkeypatch) -> None:
         profile = tmp_path / ".zshrc"
+        queue_dir = tmp_path / "queue"
+        queue_dir.mkdir()
+        (queue_dir / "queue.jsonl").write_text(
+            json.dumps({"event_id": "old-1", "event": {}}) + "\n"
+            + json.dumps({"event_id": "old-2", "event": {}}) + "\n",
+            encoding="utf-8",
+        )
         (tmp_path / "agentlint.yml").write_text("packs:\n  - universal\n")
         monkeypatch.setenv("AGENTLINT_SHELL_PROFILE", str(profile))
+        monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(queue_dir))
+        monkeypatch.delenv("AGENTCHUTE_LICENSE_KEY", raising=False)
         monkeypatch.setattr("webbrowser.open", lambda _url: True)
         runner = CliRunner()
 
@@ -1265,18 +1316,20 @@ class TestMagicalUxCommands:
                 "--api-url",
                 "http://localhost:8000",
             ],
-            input="ac_team_test_secret\n",
+            input="ac_team_login_baseline\n",
         )
 
         assert result.exit_code == 0
         assert "Paired. AgentChute credentials saved" in result.output
         assert "Shell env vars saved" in result.output
         assert "This terminal can use AgentChute immediately." in result.output
-        assert "AGENTCHUTE_LICENSE_KEY=ac_team_test_secret" in profile.read_text()
+        assert "AgentChute queue: skipped 2 pre-pairing event(s)" in result.output
+        assert json.loads((queue_dir / "cursor.json").read_text())["offset"] == 2
+        assert "AGENTCHUTE_LICENSE_KEY=ac_team_login_baseline" in profile.read_text()
         assert "agentchute:" in (tmp_path / "agentlint.yml").read_text()
         from agentlint.agentchute.settings import load_local_credentials
 
-        assert load_local_credentials()["license_key"] == "ac_team_test_secret"
+        assert load_local_credentials()["license_key"] == "ac_team_login_baseline"
 
     def test_login_pairs_through_dashboard(self, tmp_path, monkeypatch) -> None:
         profile = tmp_path / ".zshrc"
@@ -1464,17 +1517,80 @@ class TestMagicalUxCommands:
     def test_queue_flush_command_delegates_to_flush_helper(self, monkeypatch) -> None:
         import agentlint.cli
 
-        calls: list[tuple[int | None, bool, bool]] = []
+        calls: list[dict] = []
         monkeypatch.setattr(
             agentlint.cli,
             "_flush_agentchute_queue",
-            lambda max_events, dry_run, background: calls.append((max_events, dry_run, background)),
+            lambda **kwargs: calls.append(kwargs),
         )
 
-        result = CliRunner().invoke(main, ["queue", "flush", "--max-events", "7"])
+        result = CliRunner().invoke(
+            main,
+            ["queue", "flush", "--max-events", "7", "--batch-size", "3", "--time-budget", "1.5"],
+        )
 
         assert result.exit_code == 0
-        assert calls == [(7, False, False)]
+        assert calls == [{
+            "max_events": 7,
+            "batch_size": 3,
+            "time_budget": 1.5,
+            "dry_run": False,
+            "background": False,
+        }]
+
+    def test_queue_discard_pending_advances_cursor(self, tmp_path, monkeypatch) -> None:
+        queue_dir = tmp_path / "queue"
+        queue_dir.mkdir()
+        (queue_dir / "queue.jsonl").write_text(
+            json.dumps({"event_id": "old-1", "event": {}}) + "\n"
+            + json.dumps({"event_id": "old-2", "event": {}}) + "\n",
+            encoding="utf-8",
+        )
+        monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(queue_dir))
+
+        result = CliRunner().invoke(main, ["queue", "discard-pending", "--yes"])
+
+        assert result.exit_code == 0
+        assert "AgentChute queue: discarded 2 pending event(s)" in result.output
+        assert json.loads((queue_dir / "cursor.json").read_text())["offset"] == 2
+
+    def test_queue_discard_pending_can_cancel(self, tmp_path, monkeypatch) -> None:
+        queue_dir = tmp_path / "queue"
+        queue_dir.mkdir()
+        (queue_dir / "queue.jsonl").write_text(
+            json.dumps({"event_id": "old-1", "event": {}}) + "\n",
+            encoding="utf-8",
+        )
+        monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(queue_dir))
+
+        result = CliRunner().invoke(main, ["queue", "discard-pending"], input="n\n")
+
+        assert result.exit_code == 0
+        assert "AgentChute queue unchanged." in result.output
+        assert not (queue_dir / "cursor.json").exists()
+
+    def test_queue_discard_pending_reports_empty_queue(self, tmp_path, monkeypatch) -> None:
+        monkeypatch.setenv("AGENTLINT_AGENTCHUTE_QUEUE_DIR", str(tmp_path / "queue"))
+
+        result = CliRunner().invoke(main, ["queue", "discard-pending", "--yes"])
+
+        assert result.exit_code == 0
+        assert "AgentChute queue: no pending events." in result.output
+
+    def test_queue_baseline_failure_is_non_fatal(self, monkeypatch) -> None:
+        import agentlint.agentchute.queue
+        import agentlint.cli
+
+        def fail_baseline() -> int:
+            raise OSError("queue locked")
+
+        monkeypatch.setattr(
+            agentlint.agentchute.queue,
+            "mark_existing_events_delivered",
+            fail_baseline,
+        )
+
+        assert agentlint.cli._baseline_agentchute_queue_if_new_key("old-key", "new-key") == 0
 
     def test_status_reports_cached_policy_retry_and_error(self, tmp_path, monkeypatch) -> None:
         monkeypatch.setenv("AGENTCHUTE_ENABLED", "true")

{agentlint-2.5.2 → agentlint-2.5.3}/uv.lock

@@ -4,7 +4,7 @@ requires-python = ">=3.11"
 
 [[package]]
 name = "agentlint"
-version = "2.5.2"
+version = "2.5.3"
 source = { editable = "." }
 dependencies = [
     { name = "click" },