keboola-cli 0.93.0__tar.gz → 0.93.2__tar.gz

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/CLAUDE.md

@@ -853,6 +853,7 @@ kbagent config new --component-id ID [--name NAME] [--project NAME] [--output-di
 # sync: GitOps -- configs as local files. init/pull/push/diff are filesystem-local (no serve REST surface).
 kbagent sync init --project ALIAS [--directory DIR] [--git-branching] [--adopt-existing]
 kbagent sync pull --project ALIAS [--all-projects] [--force] [--theirs] [--dry-run] [--with-samples] [--no-storage] [--no-jobs] [--job-limit N] [--branch ID]
+# `sync pull` auto-inits: if the target directory has no `.keboola/manifest.json`, pull runs `init` first, so a separate `sync init` is NOT needed for a first checkout. `sync pull --project X -d ./dir` on an empty dir writes the manifest and fetches the configs in one step.
 # `sync pull --force` is conflict-aware (since 0.53.0): locally-modified config whose remote is UNCHANGED is preserved (delta stays pushable, never silently re-stamped); a true merge conflict (local AND remote both changed since last pull) aborts (exit 1, SYNC_CONFLICT, --json lists details.conflicts); local-untouched + remote-changed takes remote.
 # `sync pull --theirs` (0.72.0+) is the supported reconcile path for a drifted tree: remote wins everywhere -- overwrites locally-modified configs/rows, restores deleted/missing files, resolves conflicts by taking remote (no abort). Since 0.72.0 plain pull also re-materializes a tracked config whose local dir was deleted (manifest<->disk invariant), so delete-dir-then-pull refetches; config-level isDisabled round-trips as sparse `is_disabled: true` in _config.yml (pull/diff/push).
 kbagent sync status [--directory DIR]
@@ -873,7 +874,7 @@ kbagent sync push --project ALIAS [--all-projects] [--dry-run] [--force] [--allo
 # sync diff/push (0.89.0+, #649): local side read from exactly ONE tree (target branch subtree, else main/); entries tracked on another branch's tree are excluded from the changeset and reported under orphaned[] + summary.orphaned (reasons + reconcile hints); fix with sync pull. Adopt-by-id is branch-aware.
 # Ignored components (since 0.91.0, #689): keboola.mcp-server-tool joins keboola.sandboxes on ALWAYS_IGNORED_COMPONENTS (the MCP server's auto-created empty mcp-workspace-<hex> configs); the manifest field ignoredComponents (.keboola/manifest.json) is now LIVE and unions with the hardcoded set, honored by pull/diff/push. pull drops manifest entries + local dirs for a newly-ignored component, reported with action "ignored" (distinct from "removed" = deleted on remote); diff filters the local side too, so a stale dir for an ignored component can never classify as DELETED -- closes the delete-dir-then-push trap that used to destroy production keboola.mcp-server-tool configs.
 kbagent sync clone --source DIR --target ALIAS --target-dir DIR [--bucket-map FILE] [--variable-values FILE] [--instance-rename FILE] [--dry-run] [--branch ID]
-# `sync clone` (0.63.0+) copies a reference synced tree into a fresh target project + parameterizes it: applies bucket_map / variable_values / instance_rename overrides (JSON/YAML files), then pushes so every config CREATEs fresh -- keboola.flow task configIds and transformation variable links are remapped reference->ULID by push Phase C/D. Idempotent: re-run with an existing --target-dir reports no_changes. Fails fast if the target already contains the reference's configs (clone needs a fresh target). Override files must be flat {id: scalar} mappings (0.89.0+): a nested mapping/list/null value is rejected with CONFIG_ERROR naming the key + actual type, instead of being silently stringified into a bogus ID.
+# `sync clone` (0.63.0+) copies a reference synced tree into a fresh target project + parameterizes it: applies bucket_map / variable_values / instance_rename overrides (JSON/YAML files), then pushes so every config CREATEs fresh -- keboola.flow task configIds and transformation variable links are remapped reference->ULID by push Phase C/D. Idempotent: re-run with an existing --target-dir reports no_changes. Fails fast if the target already contains the reference's configs (clone needs a fresh target). Override files must be flat {id: scalar} mappings (0.89.0+): a nested mapping/list/null value is rejected with CONFIG_ERROR naming the key + actual type, instead of being silently stringified into a bogus ID. `--branch` is optional on a fresh clone. It defaults to the target's production branch, resolved from the API like `sync init`. Pass it only to target a dev branch of the target.
 kbagent sync branch-link --project ALIAS (--branch-id ID | --branch-name NAME) [--directory DIR]
 kbagent sync branch-unlink [--directory DIR]
 kbagent sync branch-status [--directory DIR]

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: keboola-cli
-Version: 0.93.0
+Version: 0.93.2
 Summary: AI-friendly CLI for managing Keboola projects
 Author-email: Keboola <dev@keboola.com>
 License-Expression: Apache-2.0

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "keboola-cli"
-version = "0.93.0"
+version = "0.93.2"
 description = "AI-friendly CLI for managing Keboola projects"
 readme = "README.md"
 requires-python = ">=3.12"

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/src/keboola_agent_cli/changelog.py

@@ -24,6 +24,30 @@ from .constants import CHANGELOG_HEADLINE_MAX_CHARS
 
 # Ordered newest-first.  Each value is a list of brief one-line descriptions.
 CHANGELOG: dict[str, list[str]] = {
+    "0.93.2": [
+        "New (#757): each usage event now also carries the kbagent version and an agent-vs-human "
+        "marker for the telemetry team (CLI-12). `params.cliContext` holds the User-Agent "
+        "(version + OS/arch/Python) and, when set, the conversation id -- from "
+        "`KBAGENT_CONVERSATION_ID` / `--conversation-id` on the CLI, or the `X-Conversation-ID` "
+        "header over serve. The id is bounded and cleaned (200 chars, printable only), like "
+        "`results.error`, so an oversized value never reaches the project's event log. A "
+        "`serve-` prefixed id marks a serve session, not an external agent, so a report reads "
+        "the id's shape, not its mere presence.",
+        "Note (#748, #749): housekeeping with no user-facing change. A CODEOWNERS file that "
+        "auto-requests PR review, and a docs note that `sync pull` auto-inits the manifest (CLI-7).",
+    ],
+    "0.93.1": [
+        "Fix (#744): `sync clone` into a fresh (empty) target project now defaults to the "
+        "target's production branch, so `--branch` is optional (CLI-5). Before, "
+        "`repoint_manifest_project` re-pointed only the project id and left the copied manifest "
+        "on the SOURCE project's branch id. `_resolve_branch_id` then used that id, so a clone "
+        'with no `--branch` failed with `Branch id "..." does not exists`. The clone path now '
+        "resolves the target's default branch from the API (`list_dev_branches` + "
+        "`find_default_branch_id`, the same way `sync init` does) and re-points the production "
+        "branch onto it. It resolves the branch only when the caller passes no explicit "
+        "`--branch`, so an explicit-branch clone makes no extra `list_dev_branches` call. "
+        "`--branch` stays an override for a dev branch.",
+    ],
     "0.93.0": [
         "New (#731): kbagent now posts a best-effort usage event per command, so its usage is "
         "visible in Keboola telemetry like the original Go CLI. Connection stores it as "

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/src/keboola_agent_cli/server/app.py

@@ -708,6 +708,15 @@ class _UsageTelemetryMiddleware:
             values = parse_qs(scope.get("query_string", b"").decode("latin-1")).get("project")
             project_alias = values[0] if values else None
 
+        # The caller's X-Conversation-ID (set by kbagent's own clients) rides into
+        # params.cliContext so the telemetry reader tells an agent request from a
+        # human one; a web-UI request sends no such header and stays unmarked (CLI-12).
+        conversation_id: str | None = None
+        for key, value in scope.get("headers") or []:
+            if key == b"x-conversation-id":
+                conversation_id = value.decode("latin-1") or None
+                break
+
         await asyncio.to_thread(
             telemetry.send_serve_event,
             self._config_store,
@@ -717,6 +726,7 @@ class _UsageTelemetryMiddleware:
             status_code=status_code,
             duration_s=duration_s,
             project_alias=project_alias,
+            conversation_id=conversation_id,
         )
 
 

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/src/keboola_agent_cli/services/_sync_clone.py

@@ -22,11 +22,24 @@ from ..sync.clone import (
     repoint_manifest_project,
 )
 from ..sync.manifest import load_manifest, save_manifest
+from .base import find_default_branch_id
 
 if TYPE_CHECKING:
     from .sync_service import SyncService
 
 
+def _target_default_branch_id(service: SyncService, target_project: Any) -> int | None:
+    """Return the target project's default branch id from the API.
+
+    Mirrors ``sync init`` so a fresh clone re-points the manifest onto the
+    target's own production branch instead of reusing the source's (CLI-5).
+    """
+    client = service._client_factory(target_project.stack_url, target_project.token)
+    with client:
+        branches = client.list_dev_branches()
+    return find_default_branch_id(branches)
+
+
 def clone_project(
     service: SyncService,
     source: str | Path,
@@ -106,10 +119,17 @@ def clone_project(
     if not already_cloned:
         copy_reference_tree(source_dir, target_path)
         manifest = load_manifest(target_path)
+        # _resolve_branch_id prefers an explicit --branch, so resolve the
+        # target's default branch only when branch_override is None (#744).
         repoint_manifest_project(
             manifest,
             project_id=target_project.project_id or 0,
             api_host=urlparse(target_project.stack_url).netloc,
+            default_branch_id=(
+                _target_default_branch_id(service, target_project)
+                if branch_override is None
+                else None
+            ),
         )
         bucket_rewrites = apply_bucket_map(target_path, manifest, bucket_map)
         variable_overrides = apply_variable_values(target_path, manifest, variable_values)

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/src/keboola_agent_cli/sync/clone.py

@@ -63,10 +63,27 @@ def copy_reference_tree(source_dir: Path, target_dir: Path) -> None:
     shutil.copytree(source_dir, target_dir)
 
 
-def repoint_manifest_project(manifest: Any, *, project_id: int, api_host: str) -> None:
-    """Re-point the manifest's project block at the clone's target project."""
+def repoint_manifest_project(
+    manifest: Any,
+    *,
+    project_id: int,
+    api_host: str,
+    default_branch_id: int | None = None,
+) -> None:
+    """Re-point the manifest's project block at the clone's target project.
+
+    When ``default_branch_id`` is given, the production branch id (the first
+    manifest branch, which ``_resolve_branch_id`` uses as its fallback) is
+    re-pointed onto the target project's default branch too. The copied
+    manifest otherwise keeps the SOURCE project's branch id, which does not
+    exist in the target; a fresh clone with no explicit ``--branch`` then
+    resolves that stale id and diff/push fail with
+    ``Branch id "..." does not exists`` (CLI-5).
+    """
     manifest.project.id = project_id
     manifest.project.api_host = api_host
+    if default_branch_id is not None and manifest.branches:
+        manifest.branches[0].id = default_branch_id
 
 
 def _config_dir(target_dir: Path, branch_map: dict[int, str], branch_id: int, path: str) -> Path:

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/src/keboola_agent_cli/telemetry.py

@@ -5,6 +5,11 @@ events (``POST /v2/storage/events``), the same mechanism the kbc CLI uses. The
 event is stored as ``ext.keboola.cli.`` (CLI) or ``ext.keboola.cli.serve``
 (serve REST API) and stamped server-side with the caller's token + user agent.
 
+The event body also carries ``params.cliContext``: the kbagent User-Agent
+(version + OS/arch/Python) and, when set, the conversation id. The events store
+keeps the request body, not the server-stamped envelope, so a downstream reader
+reads the version and an agent-vs-human marker off the event itself (CLI-12).
+
 This is telemetry, NOT an audit trail: it is voluntary (the two env vars below
 disable it) and best-effort (a failed or blocked events endpoint never affects
 the command). Mutating operations are recorded server-side by Connection as
@@ -27,12 +32,14 @@ import typer
 from .auth.sentinel import is_session_token
 from .config_store import ConfigStore, resolve_config_dir
 from .constants import (
+    ENV_CONVERSATION_ID,
     ENV_DISABLE_TELEMETRY,
     ENV_DO_NOT_TRACK,
     TELEMETRY_COMPONENT_ID,
     TELEMETRY_SERVE_CONFIG_ID,
     TELEMETRY_TIMEOUT,
 )
+from .http_base import build_user_agent
 from .services.base import make_telemetry_client
 from .services.project_service import ProjectService
 
@@ -46,6 +53,13 @@ logger = logging.getLogger(__name__)
 # events API's 200 KB cap and avoids dumping large response/state buffers.
 _MAX_ERROR_LEN = 1000
 
+# Longest conversation id carried in ``params.cliContext.conversationId``. The id
+# is caller-supplied -- the ``KBAGENT_CONVERSATION_ID`` env var, or (over serve) the
+# request's ``X-Conversation-ID`` header -- so it is bounded and cleaned like
+# ``results.error``: an oversized or control-character value would otherwise bloat the
+# project's event log or push the POST past the events API cap.
+_MAX_CONVERSATION_ID_LEN = 200
+
 # Command wrappers that are not a unit of work themselves. ``serve`` posts a
 # per-request event from its middleware; ``repl`` posts a per-line event from its
 # own loop. The outer invocation of each is excluded so it does not add a second,
@@ -217,6 +231,7 @@ def emit_cli_invocation(
             duration_s=duration_s,
             configuration_id=None,
             extra_params=None,
+            conversation_id=os.environ.get(ENV_CONVERSATION_ID) or None,
         )
     except Exception as exc:
         logger.debug("usage event failed: %s", exc)
@@ -232,11 +247,14 @@ def send_serve_event(
     status_code: int,
     duration_s: float,
     project_alias: str | None,
+    conversation_id: str | None = None,
 ) -> None:
     """Post a usage event for one serve REST request. Never raises.
 
     Blocking (builds a sync client + posts), so serve calls this off the event
-    loop via a worker thread.
+    loop via a worker thread. ``conversation_id`` is the request's own
+    ``X-Conversation-ID`` (read by the middleware), so an agent-driven request is
+    marked and a human web-UI request -- which sends no such header -- is not.
     """
     try:
         if telemetry_disabled():
@@ -264,6 +282,7 @@ def send_serve_event(
             duration_s=duration_s,
             configuration_id=TELEMETRY_SERVE_CONFIG_ID,
             extra_params={"path": f"{method} {path}"},
+            conversation_id=conversation_id,
         )
     except Exception as exc:
         logger.debug("serve usage event failed: %s", exc)
@@ -289,6 +308,18 @@ def _telemetry_client(config_store: ConfigStore, stack_url: str, token: str) ->
     return client, True
 
 
+def _clean_conversation_id(value: str | None) -> str | None:
+    """Strip control characters and cap the length; None if nothing usable.
+
+    The id is a caller-supplied token, so it gets the same bound as ``results.error``
+    before it enters the event body (see ``_MAX_CONVERSATION_ID_LEN``).
+    """
+    if not value:
+        return None
+    cleaned = "".join(ch for ch in value if ch.isprintable()).strip()
+    return cleaned[:_MAX_CONVERSATION_ID_LEN] or None
+
+
 def _send_event(
     config_store: ConfigStore,
     *,
@@ -301,10 +332,18 @@ def _send_event(
     duration_s: float,
     configuration_id: str | None,
     extra_params: dict[str, Any] | None,
+    conversation_id: str | None,
 ) -> None:
     params: dict[str, Any] = {"command": command}
     if extra_params:
         params.update(extra_params)
+    # KIDS reads the CLI version (auto-update adoption) and an agent-vs-human
+    # marker off the stored event body, so both ride in params.cliContext (CLI-12).
+    cli_context: dict[str, Any] = {"userAgent": build_user_agent()}
+    clean_conversation_id = _clean_conversation_id(conversation_id)
+    if clean_conversation_id:
+        cli_context["conversationId"] = clean_conversation_id
+    params["cliContext"] = cli_context
     results: dict[str, Any] = {}
     if project_id is not None:
         results["projectId"] = project_id

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/tests/test_serve_telemetry.py

@@ -45,7 +45,17 @@ def test_serve_logs_a_mutation_with_the_mapped_command(
     """
     captured: list[tuple[str, str | None]] = []
 
-    def fake_send(config_store, *, method, path, operation, status_code, duration_s, project_alias):
+    def fake_send(
+        config_store,
+        *,
+        method,
+        path,
+        operation,
+        status_code,
+        duration_s,
+        project_alias,
+        conversation_id=None,
+    ):
         captured.append((operation, project_alias))
 
     monkeypatch.setattr(telemetry, "send_serve_event", fake_send)
@@ -68,7 +78,17 @@ def test_unhandled_route_error_is_logged_as_a_failure(
     """
     captured: list[int] = []
 
-    def fake_send(config_store, *, method, path, operation, status_code, duration_s, project_alias):
+    def fake_send(
+        config_store,
+        *,
+        method,
+        path,
+        operation,
+        status_code,
+        duration_s,
+        project_alias,
+        conversation_id=None,
+    ):
         captured.append(status_code)
 
     monkeypatch.setattr(telemetry, "send_serve_event", fake_send)
@@ -100,7 +120,17 @@ def test_serve_maps_a_path_converter_route(
     """
     captured: list[str] = []
 
-    def fake_send(config_store, *, method, path, operation, status_code, duration_s, project_alias):
+    def fake_send(
+        config_store,
+        *,
+        method,
+        path,
+        operation,
+        status_code,
+        duration_s,
+        project_alias,
+        conversation_id=None,
+    ):
         captured.append(operation)
 
     monkeypatch.setattr(telemetry, "send_serve_event", fake_send)
@@ -125,7 +155,17 @@ def test_serve_skips_read_requests(tmp_config_dir: Path, monkeypatch: pytest.Mon
     """
     captured: list[tuple[str, str]] = []
 
-    def fake_send(config_store, *, method, path, operation, status_code, duration_s, project_alias):
+    def fake_send(
+        config_store,
+        *,
+        method,
+        path,
+        operation,
+        status_code,
+        duration_s,
+        project_alias,
+        conversation_id=None,
+    ):
         captured.append((method, operation))
 
     monkeypatch.setattr(telemetry, "send_serve_event", fake_send)
@@ -152,7 +192,17 @@ def test_serve_does_not_wait_for_the_telemetry_post(
     """
     posted = threading.Event()
 
-    def slow_send(config_store, *, method, path, operation, status_code, duration_s, project_alias):
+    def slow_send(
+        config_store,
+        *,
+        method,
+        path,
+        operation,
+        status_code,
+        duration_s,
+        project_alias,
+        conversation_id=None,
+    ):
         time.sleep(0.3)
         posted.set()
 
@@ -164,3 +214,36 @@ def test_serve_does_not_wait_for_the_telemetry_post(
         assert not posted.is_set()
         # ...but the event still fires, off the request path.
         assert posted.wait(2.0)
+
+
+def test_serve_passes_the_request_conversation_id(
+    tmp_config_dir: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """The request's X-Conversation-ID reaches send_serve_event; its absence sends None.
+
+    That header is the agent-vs-human marker for serve (CLI-12): an agent-driven
+    request carries it, a human web-UI request does not.
+    """
+    captured: list[str | None] = []
+
+    def fake_send(
+        config_store,
+        *,
+        method,
+        path,
+        operation,
+        status_code,
+        duration_s,
+        project_alias,
+        conversation_id=None,
+    ):
+        captured.append(conversation_id)
+
+    monkeypatch.setattr(telemetry, "send_serve_event", fake_send)
+    app = create_app(config_dir=str(tmp_config_dir), auth_token="tok")
+    with TestClient(app, raise_server_exceptions=False) as client:
+        headers = {"Authorization": "Bearer tok"}
+        client.post("/jobs/prod/run", headers={**headers, "X-Conversation-ID": "conv-xyz"}, json={})
+        client.post("/jobs/prod/run", headers=headers, json={})
+
+    assert captured == ["conv-xyz", None]

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/tests/test_sync_clone.py

@@ -85,6 +85,19 @@ class TestCopyAndRepoint:
         repoint_manifest_project(m, project_id=999, api_host="other.keboola.com")
         assert m.project.id == 999
         assert m.project.api_host == "other.keboola.com"
+        # without a target default branch id the branch id is left as-is
+        assert [b.id for b in m.branches] == [0]
+
+    def test_repoint_manifest_project_remaps_default_branch(self) -> None:
+        # CLI-5: given the target's default branch id, the production branch
+        # (the fallback branch _resolve_branch_id uses) is re-pointed too, not
+        # left on the source project's id.
+        m = _manifest([])  # branches = [ManifestBranch(id=0, path="main")]
+        repoint_manifest_project(
+            m, project_id=999, api_host="other.keboola.com", default_branch_id=52099
+        )
+        assert m.project.id == 999
+        assert [b.id for b in m.branches] == [52099]
 
 
 class TestBucketMap:
@@ -448,6 +461,78 @@ class TestCloneProjectOrchestration:
         assert load_manifest(target_dir).project.id == 4242
         push_mock.assert_called_once()
 
+    def test_clone_repoints_branch_to_target_default(
+        self, tmp_path: Path, tmp_config_dir: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # CLI-5: a fresh clone re-points the manifest branch onto the target's
+        # own default branch (from list_dev_branches), so a later diff/push with
+        # no --branch does not resolve the source project's branch id -- which
+        # does not exist in the target.
+        source = tmp_path / "golden"
+        _golden_source(source)  # source manifest branch id = 0
+        target_dir = tmp_path / "clone"
+
+        client = MagicMock()
+        client.list_dev_branches.return_value = [{"id": 52099, "isDefault": True}]
+        svc = _service(tmp_config_dir, client)
+        monkeypatch.setattr(
+            svc,
+            "diff",
+            MagicMock(
+                return_value={
+                    "changes": [{"change_type": "added", "component_id": "keboola.ex-db"}]
+                }
+            ),
+        )
+        monkeypatch.setattr(
+            svc,
+            "push",
+            MagicMock(
+                return_value={"status": "pushed", "created": 1, "flow_task_remaps": 0, "errors": []}
+            ),
+        )
+
+        svc.clone_project(source=source, target_alias="target", target_dir=target_dir)
+
+        from keboola_agent_cli.sync.manifest import load_manifest
+
+        assert [b.id for b in load_manifest(target_dir).branches] == [52099]
+
+    def test_clone_with_explicit_branch_skips_default_branch_fetch(
+        self, tmp_path: Path, tmp_config_dir: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        # #744: an explicit --branch wins in _resolve_branch_id, so clone must
+        # not spend a list_dev_branches call resolving the target's default.
+        source = tmp_path / "golden"
+        _golden_source(source)
+        client = MagicMock()
+        svc = _service(tmp_config_dir, client)
+        monkeypatch.setattr(
+            svc,
+            "diff",
+            MagicMock(
+                return_value={
+                    "changes": [{"change_type": "added", "component_id": "keboola.ex-db"}]
+                }
+            ),
+        )
+        monkeypatch.setattr(
+            svc,
+            "push",
+            MagicMock(
+                return_value={"status": "pushed", "created": 1, "flow_task_remaps": 0, "errors": []}
+            ),
+        )
+
+        svc.clone_project(
+            source=source,
+            target_alias="target",
+            target_dir=tmp_path / "clone",
+            branch_override=52099,
+        )
+
+        client.list_dev_branches.assert_not_called()
+
     def test_fresh_target_guard_rejects_collision(
         self, tmp_path: Path, tmp_config_dir: Path, monkeypatch: pytest.MonkeyPatch
     ) -> None:

{keboola_cli-0.93.0 → keboola_cli-0.93.2}/tests/test_telemetry.py

@@ -23,9 +23,15 @@ from keboola_agent_cli.auth.token_provider import reset_provider_registry
 _EVENTS_URL = "https://connection.keboola.com/v2/storage/events"
 
 
-def test_success_posts_expected_cli_event(tmp_config_dir: Path, httpx_mock) -> None:
+def test_success_posts_expected_cli_event(
+    tmp_config_dir: Path, httpx_mock, monkeypatch: pytest.MonkeyPatch
+) -> None:
     """A successful command posts one ``ext.keboola.cli.`` event with the command path."""
     telemetry.reset()
+    # This test asserts the no-conversation-id branch, so it must own that env var:
+    # cli.py sets KBAGENT_CONVERSATION_ID directly on os.environ for --conversation-id,
+    # which can leak across tests in one xdist worker.
+    monkeypatch.delenv("KBAGENT_CONVERSATION_ID", raising=False)
     setup_single_project(tmp_config_dir)  # sole project -> resolves without --project
     httpx_mock.add_response(url=_EVENTS_URL, method="POST", json={"id": "evt-1"})
 
@@ -42,7 +48,14 @@ def test_success_posts_expected_cli_event(tmp_config_dir: Path, httpx_mock) -> N
     assert body["component"] == "keboola.cli"
     assert "configurationId" not in body  # CLI -> ext.keboola.cli. (serve adds "serve")
     assert body["type"] == "info"
-    assert body["params"] == {"command": "config list"}
+    assert body["params"]["command"] == "config list"
+    # cliContext carries the version (via the User-Agent) into the event body,
+    # since the events store keeps the body, not the server-stamped envelope (CLI-12).
+    assert body["params"]["cliContext"]["userAgent"].startswith(
+        ("keboola-cli/", "keboola-agent-cli/")
+    )
+    # No KBAGENT_CONVERSATION_ID set -> no agent marker (a human invocation).
+    assert "conversationId" not in body["params"]["cliContext"]
     assert body["results"]["projectId"] == 258
     assert body["duration"] == 1  # ceil(0.4s)
     # The acting client identifies kbagent to Connection by its User-Agent, which
@@ -50,6 +63,58 @@ def test_success_posts_expected_cli_event(tmp_config_dir: Path, httpx_mock) -> N
     assert requests[0].headers["User-Agent"].startswith(("keboola-cli/", "keboola-agent-cli/"))
 
 
+def test_conversation_id_marks_an_agent_run(
+    tmp_config_dir: Path, httpx_mock, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """A set KBAGENT_CONVERSATION_ID lands in params.cliContext.conversationId.
+
+    Presence of the id is the agent-vs-human marker KIDS reads off the event (CLI-12).
+    """
+    telemetry.reset()
+    setup_single_project(tmp_config_dir)
+    monkeypatch.setenv("KBAGENT_CONVERSATION_ID", "conv-abc123")
+    httpx_mock.add_response(url=_EVENTS_URL, method="POST", json={"id": "evt-1"})
+
+    telemetry.emit_cli_invocation(
+        ["kbagent", "config", "list", "--config-dir", str(tmp_config_dir)],
+        exit_code=0,
+        error=None,
+        duration_s=0.4,
+    )
+
+    body = json.loads(httpx_mock.get_requests()[0].content)
+    assert body["params"]["cliContext"]["conversationId"] == "conv-abc123"
+
+
+def test_conversation_id_is_bounded_and_stripped(
+    tmp_config_dir: Path, httpx_mock, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """An oversized / control-character conversation id is capped and cleaned (CLI-12).
+
+    conversationId is copied into the event body like results.error, so it gets the same
+    bound: a caller-supplied X-Conversation-ID / env var cannot bloat the project's event
+    log or push the POST past the events API size cap.
+    """
+    telemetry.reset()
+    setup_single_project(tmp_config_dir)
+    monkeypatch.setenv("KBAGENT_CONVERSATION_ID", "conv\x07\x1f\x7f-" + "x" * 500)
+    httpx_mock.add_response(url=_EVENTS_URL, method="POST", json={"id": "evt-1"})
+
+    telemetry.emit_cli_invocation(
+        ["kbagent", "config", "list", "--config-dir", str(tmp_config_dir)],
+        exit_code=0,
+        error=None,
+        duration_s=0.4,
+    )
+
+    conv = json.loads(httpx_mock.get_requests()[0].content)["params"]["cliContext"][
+        "conversationId"
+    ]
+    assert all(ch.isprintable() for ch in conv)  # control chars stripped
+    assert conv == "conv-" + "x" * (telemetry._MAX_CONVERSATION_ID_LEN - len("conv-"))
+    assert len(conv) == telemetry._MAX_CONVERSATION_ID_LEN
+
+
 def test_failed_command_reports_error_and_is_best_effort(tmp_config_dir: Path, httpx_mock) -> None:
     """A failed command posts ``type=error`` + message; a failing endpoint never raises."""
     telemetry.reset()