diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.md index 5c194b4321..953ae4c5e2 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.md @@ -4561,3 +4561,39 @@ view shows its independently checked result in the same conversation. contents or activation. Full Settings journeys, actual-model adoption, total cost, natural process drain, complete D2/D5 closure, R1/M3, full C1 acceptance and its default cutover remain unqualified. + +### 2026-11-15 — Skip automatic usage observers for existing opt-outs + +- **Gap:** Python observation hints recognized fewer environment opt-outs than + the existing TypeScript usage owner. `LOOPX_USAGE_PING=off`, `CI=1` or + `DO_NOT_TRACK=yes` could still schedule observers, including binding/native + metadata discovery, before TypeScript rejected sending. +- **Delta:** one negative-only host hint preserves the owner's per-variable + trim/case semantics and skips automatic CLI, Host, quota, direct-cycle and + detached observation earlier. `LOOPX_USAGE_PING=yes` and `CI=false` remain + permitted by that hint; `DO_NOT_TRACK=false` remains blocked. TypeScript + retains positive decisions, notice, consent, generation, state and sending; + allowed payloads and business errors retain their original contracts. +- **Evidence:** against source baseline + `main@2e52541f909089181e7415e0d796f6d413c83dbf`, the real CLI counterexample + starts six detached Node children, two for each of the three opt-outs; all + return blocked. The same candidate replay starts zero, preserving CLI results + and fixture state. Source validation passes 107 Python and 55 TypeScript + tests. Eight permitted environment cases retain 48 complete observation + requests and Host error behavior under fixed fixture/clocks; this payload + comparison captures dispatch locally, alongside the real transport tests. +- **Installed scope:** fresh, non-editable only-Core installations of the + candidate and its actual composition with C1 #8266 at + `1a3740cf9e6ebad337f17967452693a9050edc81` each pass the same three real + selected `version`-CLI opt-out cases with zero observer children and unchanged + business JSON and fixture state. Each also passes 22 metadata cases and three + original Core correctness cases using real File/SQLite authority, retaining + 31 raw CLI command records. The cold metadata scope is one fresh process containing 20 + unselected IDs per composition; it is not 20 cold processes. Product payloads + are independently bound through source, wheel, RECORD and installed files. +- **Boundary:** this qualifies the tested source and installed-Core automatic + observer isolation, including the current-C1 composition. It does not + establish whole process/network closure, natural process drain, measured + overhead or complete-cost benefit, actual-model adoption, full D2/D5, + R1/M3, Goal completion or C1 default cutover. Preserve earlier checkpoints, + failures, budgets and acceptance requirements. diff --git a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md index 45b420baa1..c9ee8b7dec 100644 --- a/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md +++ b/docs/architecture/rfcs/monorepo-distribution-split-v0.zh-CN.md @@ -3530,3 +3530,31 @@ workspace 批准和脚本模型工作。桌面视图在采用检查后显示原 - **边界:**本次收窄 metadata discovery,不改变安装的 capability 内容或 activation。 全 Settings 旅程、真实模型采纳、总成本、自然进程 drain、完整 D2/D5 闭包、 R1/M3、完整 C1 验收及其默认切换仍未资格化。 + +### 2026-11-15 — 既有 opt-out 提前跳过自动 usage 观察 + +- **缺口:**Python observation hints 识别的环境 opt-out 少于原 TypeScript usage + owner。`LOOPX_USAGE_PING=off`、`CI=1` 或 `DO_NOT_TRACK=yes` 仍可能调度观察, + 包括 binding/native metadata 发现,之后 TypeScript 才拒绝发送。 +- **增量:**一个 negative-only host hint 保留原 owner 各变量的 trim/case 语义, + 提前跳过自动 CLI、Host、quota、direct-cycle 和 detached observation。 + `LOOPX_USAGE_PING=yes`、`CI=false` 仍通过该 hint,`DO_NOT_TRACK=false` 仍阻断。 + 正向 decision、notice、consent、generation、state 和发送继续由 TypeScript + 持有;允许路径的 payload 和业务错误保留原契约。 +- **证据:**源码基线 `main@2e52541f909089181e7415e0d796f6d413c83dbf` 的真实 CLI + 反例启动六个 detached Node 子进程,每个上述 opt-out 各两个,均返回 blocked; + 相同候选回放启动零个,CLI 结果和 fixture state 保持不变。源码验证通过 + 107 个 Python、55 个 TypeScript 测试。固定 fixture/clocks 的八个允许环境 + 场景保留 48 个完整 observation request 与 Host 错误行为;该 payload 对照 + 在本地捕获 dispatch,并与真实 transport 测试并列,范围不同。 +- **安装范围:**候选及其与 C1 #8266 当前 + `1a3740cf9e6ebad337f17967452693a9050edc81` 的实际组合,各自全新 non-editable + only-Core 安装通过相同三个真实 selected `version` CLI opt-out 场景,observer + 子进程为零,业务 JSON 与 fixture state 保持不变。每个组合还通过 22 个 metadata + 场景及三个使用真实 File/SQLite authority 的原 Core 正确性场景,并保留 31 份 + raw CLI command 记录。冷 metadata 范围是每个组合一个 fresh process 内含 20 个未选 ID,不能算作 + 20 次冷进程。product payload 经 source、wheel、RECORD 与安装文件独立绑定。 +- **边界:**本次资格化已测试的源码与 installed-Core 自动 observer 隔离,包括 + current-C1 实际组合;不证明完整 process/network 闭包、自然进程 + drain、实测 overhead 或完整成本收益、真实模型采用、完整 D2/D5、R1/M3、 + Goal 完成或 C1 默认切换。保留既有 checkpoints、失败、预算和验收要求。 diff --git a/loopx/usage_goal.py b/loopx/usage_goal.py index ca3d6af5b3..287b103acd 100644 --- a/loopx/usage_goal.py +++ b/loopx/usage_goal.py @@ -20,6 +20,9 @@ @contextmanager def observe_goal_execution(runtime_root: Path, goal_id: str, *, host: str = "unknown") -> Iterator[None]: + if usage_ping._environment_suppressed(): + yield + return stop = threading.Event() publish = None try: @@ -28,10 +31,7 @@ def observe_goal_execution(runtime_root: Path, goal_id: str, *, host: str = "unk path = usage_ping.state_path() state = json.loads(path.read_text(encoding="utf-8")) generation = state.get("generation") - if (goal_id and generation and state.get("consent") != "disabled" - and os.environ.get("LOOPX_USAGE_PING") != "0" - and os.environ.get("DO_NOT_TRACK") != "1" - and os.environ.get("CI") != "true"): + if goal_id and generation and state.get("consent") != "disabled": key = hashlib.sha256(json.dumps([generation, str(runtime_root.resolve()), goal_id]).encode()).hexdigest() wall = time.time_ns() // 1_000_000 origin = time.monotonic() @@ -101,12 +101,12 @@ def observe_quota_cycle(*, registry_path: Path, runtime_root: Path, goal_id: str at: int, host: str) -> None: """Detach binding discovery and session metadata lookup from quota latency.""" try: + if usage_ping._environment_suppressed(): + return import sys state = json.loads(usage_ping.state_path().read_text(encoding="utf-8")) if state.get("consent") == "disabled" or not state.get("generation"): return - if os.environ.get("LOOPX_USAGE_PING") == "0" or os.environ.get("DO_NOT_TRACK") == "1" or os.environ.get("CI") == "true": - return usage_ping._detach({"registry": str(registry_path), "runtime": str(runtime_root), "goal": goal_id, "agent": agent_id, "turn": turn_id, "phase": phase, "at": at, "host": host, @@ -155,6 +155,8 @@ def _bound_codex_session(registry_path: Path, goal_id: str, agent_id: str | None def _dispatch_cycle(request) -> None: + if usage_ping._environment_suppressed(): + return path = Path(request["path"]) state = json.loads(path.read_text(encoding="utf-8")) if state.get("consent") == "disabled" or state.get("generation") != request["generation"]: diff --git a/loopx/usage_ping.py b/loopx/usage_ping.py index 32bf72caa9..6f05f9aa3f 100644 --- a/loopx/usage_ping.py +++ b/loopx/usage_ping.py @@ -8,6 +8,7 @@ import sys import tempfile import time +from collections.abc import Mapping from contextvars import ContextVar from datetime import datetime, timezone from pathlib import Path @@ -139,12 +140,25 @@ def control(action: str, path: Path | None = None, **fields: Any) -> dict[str, A return payload +def _environment_suppressed(environment: Mapping[str, str] | None = None) -> bool: + """Negative-only host hint; the TS owner still decides every observation.""" + env = os.environ if environment is None else environment + # Match ECMAScript String.trim, including FEFF and excluding U+0085. + whitespace = (" \t\n\r\v\f\u00a0\u1680\u2000\u2001\u2002\u2003\u2004\u2005" + "\u2006\u2007\u2008\u2009\u200a\u2028\u2029\u202f\u205f\u3000\ufeff") + return ( + env.get("LOOPX_USAGE_PING", "").strip(whitespace).lower() in {"0", "false", "no", "off"} + or env.get("DO_NOT_TRACK", "").strip(whitespace) not in {"", "0"} + or env.get("CI", "").strip(whitespace).lower() not in {"", "0", "false"} + ) + + def begin(command: str) -> tuple[str, float] | None: """Read a small host hint; do not start a synchronous Node process on warm commands.""" _observation.set({}) # Negative-only scheduling hints for common unattended environments. These # cannot authorize collection; TS still checks every supported switch value. - if os.environ.get("LOOPX_USAGE_PING") == "0" or os.environ.get("DO_NOT_TRACK") == "1" or os.environ.get("CI") == "true": + if _environment_suppressed(): return None # Whole-runtime migration includes this machine state. Detached observation # would invalidate its preview or rollback receipt even with other hosts stopped. @@ -239,6 +253,8 @@ def _pin_caller_paths(request: dict[str, Any]) -> dict[str, Any]: def _detach(request: dict[str, Any], *, command: list[str] | None = None) -> None: + if _environment_suppressed(): + return request = _pin_caller_paths(request) kwargs: dict[str, Any] = {"stdin": subprocess.PIPE, "stdout": subprocess.DEVNULL, "stderr": subprocess.DEVNULL, "close_fds": True, diff --git a/tests/test_usage_goal.py b/tests/test_usage_goal.py index 24685cc58a..f4b98a293d 100644 --- a/tests/test_usage_goal.py +++ b/tests/test_usage_goal.py @@ -86,6 +86,48 @@ def test_disabled_observer_starts_no_worker_or_process(tmp_path, monkeypatch): pass +@pytest.mark.parametrize("switch,value", [ + ("LOOPX_USAGE_PING", "off"), ("DO_NOT_TRACK", "yes"), + ("DO_NOT_TRACK", "false"), ("CI", "1"), ("CI", " YES "), +]) +@pytest.mark.parametrize("entrypoint", ["host", "quota", "direct_cycle"]) +def test_environment_opt_out_skips_host_and_binding_work(tmp_path, monkeypatch, switch, value, entrypoint): + monkeypatch.setattr(usage_ping, "select_default_runtime_root", lambda: tmp_path) + for name in ("CI", "DO_NOT_TRACK", "LOOPX_USAGE_PING"): + monkeypatch.delenv(name, raising=False) + monkeypatch.setenv(switch, value) + usage_ping.state_path().write_text(json.dumps({"generation": "fixture", "consent": "enabled"})) + workers, sends, bindings = [], [], [] + monkeypatch.setattr(threading.Thread, "start", lambda worker: workers.append(worker.name)) + monkeypatch.setattr(usage_ping, "_detach", sends.append) + if entrypoint == "host": + error = ValueError("original Host failure") + with pytest.raises(ValueError) as caught: + with usage_goal.observe_goal_execution(tmp_path, "fixture-goal"): + raise error + assert caught.value is error + else: + registry, rollout = _bound_fixture(tmp_path, monkeypatch) + original = usage_goal._bound_codex_session + + def read_binding(*args): + result = original(*args) + bindings.append(result) + return result + + monkeypatch.setattr(usage_goal, "_bound_codex_session", read_binding) + if entrypoint == "quota": + usage_goal.observe_quota_cycle(registry_path=registry, runtime_root=tmp_path, goal_id="goal", + agent_id="agent", turn_id="turn", phase="start", at=0, host="codex-app") + else: + usage_goal._dispatch_cycle({"path": str(usage_ping.state_path()), "generation": "fixture", + "registry": str(registry), "runtime": str(tmp_path), "goal": "goal", "agent": "agent", + "turn": "turn", "phase": "start", "at": 0, "host": "codex-app"}) + assert workers == [] + assert sends == [] + assert bindings == [] + + def test_periodic_observation_does_not_need_turn_completion(tmp_path, monkeypatch): monkeypatch.setattr(usage_ping, "select_default_runtime_root", lambda: tmp_path) usage_ping.state_path().write_text(json.dumps({"generation": "fixture", "consent": "enabled"})) diff --git a/tests/test_usage_ping.py b/tests/test_usage_ping.py index 960bb87a3d..5a6995a166 100644 --- a/tests/test_usage_ping.py +++ b/tests/test_usage_ping.py @@ -6,6 +6,7 @@ import os import runpy import select +import shutil import socket import subprocess import sys @@ -310,6 +311,90 @@ def test_first_disclosure_respects_policy_overrides(isolated, monkeypatch, capsy assert capsys.readouterr().err == '' +@pytest.mark.parametrize('switch,value', [ + ('LOOPX_USAGE_PING', 'off'), ('LOOPX_USAGE_PING', ' FALSE '), + ('LOOPX_USAGE_PING', '\ufeffOFF\ufeff'), ('DO_NOT_TRACK', 'yes'), + ('DO_NOT_TRACK', 'false'), ('CI', '1'), ('CI', ' YES '), +]) +@pytest.mark.parametrize('current_notice', [False, True]) +def test_environment_opt_out_skips_automatic_cli_transport( + isolated, monkeypatch, capsys, switch, value, current_notice, +): + # Real business dispatch and enabled hints prevent missing state or consent + # from masking automatic disclosure or warm-command transport attempts. + usage_ping.state_path().write_text(json.dumps({ + 'generation': 'fixture', 'consent': 'enabled', + 'notice': {'version': 6 if current_notice else 0}, + })) + monkeypatch.setenv(switch, value) + attempts = [] + + def unavailable_command(): + attempts.append('transport') + raise OSError('fixture transport unavailable') + + monkeypatch.setattr(usage_ping, '_command', unavailable_command) + assert main(['version', '--format', 'json']) == 0 + captured = capsys.readouterr() + assert json.loads(captured.out)['ok'] is True + assert captured.err == '' + assert attempts == [] + + +@pytest.mark.parametrize('switch,value', [ + ('LOOPX_USAGE_PING', 'off'), ('DO_NOT_TRACK', 'yes'), ('CI', '1'), +]) +@pytest.mark.parametrize('producer', ['finish', 'verified_return', 'direct', 'python_child']) +def test_environment_opt_out_fences_late_or_direct_observation( + isolated, monkeypatch, switch, value, producer, +): + usage_ping.state_path().write_text(json.dumps({ + 'generation': 'fixture', 'consent': 'enabled', 'notice': {'version': 6}, + })) + monkeypatch.setenv(switch, value) + monkeypatch.setattr(subprocess, 'Popen', lambda *a, **k: pytest.fail('opt-out spawned a child')) + monkeypatch.setattr(usage_ping, '_pin_caller_paths', lambda *a: pytest.fail('opt-out resolved caller paths')) + if producer == 'finish': + usage_ping.finish(('fixture', time.monotonic()), 'version', 0) + elif producer == 'verified_return': + usage_ping.observe_verified_return() + else: + usage_ping._detach({'path': 'caller-relative-state'}, command=( + [sys.executable, '-P', '-m', 'loopx.usage_goal'] if producer == 'python_child' else None + )) + + +def test_environment_hint_matches_the_typescript_owner(): + node = shutil.which('node') + if node is None: + pytest.skip('TypeScript owner parity requires the supported Node runtime') + # DNT differs from CI/PING. JS trims FEFF but not U+0085; Python's default + # strip has the opposite behavior for these two characters. + values = ['', '0', '1', 'false', 'true', 'no', 'off', 'yes', 'unknown', + ' FALSE ', ' OFF ', ' YES ', '\ufeff0\ufeff', '\ufeffOFF\ufeff', + '\ufefffalse\ufeff', '\u00850\u0085', '\u0085off\u0085'] + environments = [{}] + [{key: value} for key in ('LOOPX_USAGE_PING', 'DO_NOT_TRACK', 'CI') for value in values] + environments += [ + {'LOOPX_USAGE_PING': 'yes', 'DO_NOT_TRACK': '0', 'CI': 'false'}, + {'LOOPX_USAGE_PING': 'off', 'DO_NOT_TRACK': 'yes', 'CI': '1'}, + ] + owner = (Path(usage_ping.__file__).parent / 'control_plane/runtime/usage_statistics.ts').as_uri() + script = f'''import {{ blockedBy }} from {json.dumps(owner)}; +let input=''; for await (const chunk of process.stdin) input+=chunk; +const reasons=JSON.parse(input).map(env=>blockedBy({{consent:'disabled'}}, + {{env,version:'1.0.0',python:'3.13',channel:'source'}},'unused')); +process.stdout.write(JSON.stringify(reasons));''' + result = subprocess.run([node, '--no-warnings', '--experimental-strip-types', '--input-type=module', '-e', script], + input=json.dumps(environments), capture_output=True, text=True, timeout=20, check=True) + reasons = json.loads(result.stdout) + assert len(reasons) == len(environments) + for env, reason in zip(environments, reasons): + # Disabled consent makes the existing owner return before filesystem or + # sending when no environment suppressor exists; this does not enable it. + expected = reason in {'LOOPX_USAGE_PING', 'DO_NOT_TRACK', 'CI'} + assert usage_ping._environment_suppressed(env) is expected, (env, reason) + + def test_real_agent_cli_keeps_json_clean_and_sends_only_after_disclosure(isolated, collector, monkeypatch): endpoint, received, accepted, release = collector monkeypatch.setenv('LOOPX_USAGE_PING_ENDPOINT', endpoint)