From 0d37619f24ef94f5f9cfbe3bbc18e04e1c53f0e4 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:17:26 +0530 Subject: [PATCH 01/30] fix(plugins): say what telemetry actually sends, and salt the hashes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The plugin README promises "anonymous usage events" and the telemetry module's docstring says it sends only "salted hashes". Neither is true. resolve_distinct_id() exchanges the API key for the account email and sends that as the distinct_id on every event. Installing the plugin requires an API key, so this is nearly every user. That is probably the behaviour we want — the Python SDK and the CLI attribute the same way — but the description has to match it. repo_hash and session_hash were unsalted SHA-256 cut to 16 hex characters. repo.identity is a git remote URL, or `local:` when there is no remote, which normally contains the account username. Sixteen unsalted hex characters over that input space is enumerable, so the hash was not a privacy control at all. Salted per install, with the salt kept in the identity file. That preserves every within-account join the analytics actually use and gives up only cross-machine joins on the same repository, which nothing computes. Since the distinct_id is already the email, the hash was never buying privacy from us — only from whoever obtains the data later, which is exactly what the salt fixes. Also corrects deepseek-plugin's README and source comment, which told readers ZAPIER and STRANDS were already in the backend's KNOWN_EVENT_SOURCES allowlist. Neither was. Adds a Telemetry section to docs/integrations/claude-code.mdx, which had none. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- docs/integrations/claude-code.mdx | 25 ++++++++++++ .../agent-plugin-core/python/telemetry.py | 40 +++++++++++++++++-- .../antigravity-plugin/core/telemetry.py | 40 +++++++++++++++++-- integrations/claude-code-plugin/README.md | 10 ++++- .../claude-code-plugin/core/telemetry.py | 40 +++++++++++++++++-- integrations/codex-plugin/core/telemetry.py | 40 +++++++++++++++++-- integrations/cursor-plugin/core/telemetry.py | 40 +++++++++++++++++-- integrations/deepseek-plugin/README.md | 4 +- integrations/deepseek-plugin/src/index.ts | 6 +-- integrations/kimi-plugin/core/telemetry.py | 40 +++++++++++++++++-- .../mem0-agent-plugin/core/telemetry.py | 40 +++++++++++++++++-- integrations/mem0-strands/README.md | 8 ++-- 12 files changed, 294 insertions(+), 39 deletions(-) diff --git a/docs/integrations/claude-code.mdx b/docs/integrations/claude-code.mdx index 0b8e5a328..c4b5a2c35 100644 --- a/docs/integrations/claude-code.mdx +++ b/docs/integrations/claude-code.mdx @@ -172,6 +172,31 @@ claude plugin update mem0@mem0-plugins --scope user | Sidekick won't start | Must be in a Git repo. Check that your Claude Code version supports plugin agents and worktrees. | | Remove the plugin | `claude plugin uninstall mem0@mem0-plugins` | +## Telemetry + +The plugin sends usage events (which hook ran, timing, result counts, failure +types) so Mem0 can see what's used and what's breaking. + +These events are **not anonymous**. When an API key is configured, which +installing the plugin requires, they are sent under your Mem0 account email, +the same way the Python SDK and the CLI attribute theirs. Without a key they +are sent under a random per-machine id. + +Each event carries the event name, the plugin version, the harness it ran in, +your OS and Python version, timings, counts, and a coarse failure label. +Repository and session identifiers are hashed with a random salt generated on +your machine and never sent, so they cannot be linked back to a repository name +or path. + +Prompts, memory text, queries, file paths, repository names, and API keys are +never sent. + +Turn it off: + +```bash +export MEM0_TELEMETRY=false +``` + Detailed MCP configuration for all clients diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 249595475..1b6bd854e 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -1,5 +1,9 @@ #!/usr/bin/env python3 -"""Anonymous usage telemetry for Mem0 agent plugins. +"""Usage telemetry for Mem0 agent plugins. + +Events are linked to your Mem0 account email when an API key is configured, and +to a random per-machine id otherwise. Not anonymous — the Python SDK and CLI +attribute the same way. Hooks run on a 3-6 second budget and fire on every tool call, so recording never touches the network: `record` appends one JSON line to a local spool and returns. @@ -9,7 +13,8 @@ started once per session and again from the flush worker that is already detache Pure stdlib, matching the rest of the plugin. Opt out with MEM0_TELEMETRY=false. Never sends prompts, memory text, queries, file paths, repository names, or API -keys: only event names, durations, counts, coarse outcomes, and salted hashes. +keys: only event names, durations, counts, coarse outcomes, and repo/session +identifiers hashed with a random per-install salt. """ from __future__ import annotations @@ -83,9 +88,36 @@ def is_enabled() -> bool: def _digest(value: str, length: int = 16) -> str: + """Unsalted digest. Only for values that are already secrets (API keys).""" return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _install_salt() -> str: + """Random per-install salt, created on first use and kept in the identity file.""" + identity = _read_identity() + salt = identity.get("salt") + if not salt: + salt = uuid.uuid4().hex + identity["salt"] = salt + _write_identity(identity) + return salt + + +def _scoped_digest(value: str, length: int = 16) -> str: + """Salted digest for values drawn from a guessable space. + + repo.identity is a git remote URL, or ``local:`` when there is + no remote — which normally contains the account username. Sixteen unsalted + hex characters over that input space is enumerable, so this is not a + privacy control without the salt. Salting per install keeps every + within-account join the analytics actually use and gives up only + cross-machine joins on the same repository, which nothing computes. + """ + if not value: + return "" + return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + + def _safe_value(value: Any) -> Any: if isinstance(value, str): return memory_core.redact(value) @@ -175,9 +207,9 @@ def record( python_version=platform.python_version(), ) if repo is not None: - properties["repo_hash"] = _digest(getattr(repo, "identity", "")) + properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) if session_id: - properties["session_hash"] = _digest(session_id) + properties["session_hash"] = _scoped_digest(session_id) line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 249595475..1b6bd854e 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -1,5 +1,9 @@ #!/usr/bin/env python3 -"""Anonymous usage telemetry for Mem0 agent plugins. +"""Usage telemetry for Mem0 agent plugins. + +Events are linked to your Mem0 account email when an API key is configured, and +to a random per-machine id otherwise. Not anonymous — the Python SDK and CLI +attribute the same way. Hooks run on a 3-6 second budget and fire on every tool call, so recording never touches the network: `record` appends one JSON line to a local spool and returns. @@ -9,7 +13,8 @@ started once per session and again from the flush worker that is already detache Pure stdlib, matching the rest of the plugin. Opt out with MEM0_TELEMETRY=false. Never sends prompts, memory text, queries, file paths, repository names, or API -keys: only event names, durations, counts, coarse outcomes, and salted hashes. +keys: only event names, durations, counts, coarse outcomes, and repo/session +identifiers hashed with a random per-install salt. """ from __future__ import annotations @@ -83,9 +88,36 @@ def is_enabled() -> bool: def _digest(value: str, length: int = 16) -> str: + """Unsalted digest. Only for values that are already secrets (API keys).""" return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _install_salt() -> str: + """Random per-install salt, created on first use and kept in the identity file.""" + identity = _read_identity() + salt = identity.get("salt") + if not salt: + salt = uuid.uuid4().hex + identity["salt"] = salt + _write_identity(identity) + return salt + + +def _scoped_digest(value: str, length: int = 16) -> str: + """Salted digest for values drawn from a guessable space. + + repo.identity is a git remote URL, or ``local:`` when there is + no remote — which normally contains the account username. Sixteen unsalted + hex characters over that input space is enumerable, so this is not a + privacy control without the salt. Salting per install keeps every + within-account join the analytics actually use and gives up only + cross-machine joins on the same repository, which nothing computes. + """ + if not value: + return "" + return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + + def _safe_value(value: Any) -> Any: if isinstance(value, str): return memory_core.redact(value) @@ -175,9 +207,9 @@ def record( python_version=platform.python_version(), ) if repo is not None: - properties["repo_hash"] = _digest(getattr(repo, "identity", "")) + properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) if session_id: - properties["session_hash"] = _digest(session_id) + properties["session_hash"] = _scoped_digest(session_id) line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/claude-code-plugin/README.md b/integrations/claude-code-plugin/README.md index 130460b17..872071abe 100644 --- a/integrations/claude-code-plugin/README.md +++ b/integrations/claude-code-plugin/README.md @@ -136,13 +136,19 @@ Local data lives in `${CLAUDE_PLUGIN_DATA}`: - `pending/`: sessions waiting to be sent to Mem0 (retried after interruption) - `flush-worker.log`: whether memory creation succeeded - `plugin-errors.log`: hook errors (no credentials) -- `telemetry.jsonl` / `telemetry-identity.json`: anonymous usage events +- `telemetry.jsonl` / `telemetry-identity.json`: usage events and the id they are sent under Mem0 receives captured user messages, Claude's answers, sidekick assignments and completed responses, and changed file paths. When a failed command is recorded, extraction can also include bounded command details and results. Complete files and general tool output stay on your machine. Values that look like credentials are redacted before anything is sent. ## Telemetry -Anonymous usage events (which hook ran, timing, result counts, failure types) so Mem0 can identify what's used and what's breaking. Repo and session IDs are hashed before leaving your machine. Prompts, memory text, file paths, tool output, and API keys are never sent. +Usage events (which hook ran, timing, result counts, failure types) so Mem0 can identify what's used and what's breaking. + +**These events are not anonymous.** When an API key is configured — which installing the plugin requires — events are sent under your Mem0 account email, the same way the Python SDK and the CLI attribute theirs. Without a key they are sent under a random per-machine id. + +What each event carries: the event name, the plugin version, the harness it ran in, your OS and Python version, timings, counts, and a coarse failure label. Repository and session identifiers are hashed with a random salt generated on your machine and never sent, so they cannot be linked back to a repository name or path. + +Prompts, memory text, queries, file paths, repository names, and API keys are never sent. Turn it off: diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 249595475..1b6bd854e 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -1,5 +1,9 @@ #!/usr/bin/env python3 -"""Anonymous usage telemetry for Mem0 agent plugins. +"""Usage telemetry for Mem0 agent plugins. + +Events are linked to your Mem0 account email when an API key is configured, and +to a random per-machine id otherwise. Not anonymous — the Python SDK and CLI +attribute the same way. Hooks run on a 3-6 second budget and fire on every tool call, so recording never touches the network: `record` appends one JSON line to a local spool and returns. @@ -9,7 +13,8 @@ started once per session and again from the flush worker that is already detache Pure stdlib, matching the rest of the plugin. Opt out with MEM0_TELEMETRY=false. Never sends prompts, memory text, queries, file paths, repository names, or API -keys: only event names, durations, counts, coarse outcomes, and salted hashes. +keys: only event names, durations, counts, coarse outcomes, and repo/session +identifiers hashed with a random per-install salt. """ from __future__ import annotations @@ -83,9 +88,36 @@ def is_enabled() -> bool: def _digest(value: str, length: int = 16) -> str: + """Unsalted digest. Only for values that are already secrets (API keys).""" return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _install_salt() -> str: + """Random per-install salt, created on first use and kept in the identity file.""" + identity = _read_identity() + salt = identity.get("salt") + if not salt: + salt = uuid.uuid4().hex + identity["salt"] = salt + _write_identity(identity) + return salt + + +def _scoped_digest(value: str, length: int = 16) -> str: + """Salted digest for values drawn from a guessable space. + + repo.identity is a git remote URL, or ``local:`` when there is + no remote — which normally contains the account username. Sixteen unsalted + hex characters over that input space is enumerable, so this is not a + privacy control without the salt. Salting per install keeps every + within-account join the analytics actually use and gives up only + cross-machine joins on the same repository, which nothing computes. + """ + if not value: + return "" + return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + + def _safe_value(value: Any) -> Any: if isinstance(value, str): return memory_core.redact(value) @@ -175,9 +207,9 @@ def record( python_version=platform.python_version(), ) if repo is not None: - properties["repo_hash"] = _digest(getattr(repo, "identity", "")) + properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) if session_id: - properties["session_hash"] = _digest(session_id) + properties["session_hash"] = _scoped_digest(session_id) line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 249595475..1b6bd854e 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -1,5 +1,9 @@ #!/usr/bin/env python3 -"""Anonymous usage telemetry for Mem0 agent plugins. +"""Usage telemetry for Mem0 agent plugins. + +Events are linked to your Mem0 account email when an API key is configured, and +to a random per-machine id otherwise. Not anonymous — the Python SDK and CLI +attribute the same way. Hooks run on a 3-6 second budget and fire on every tool call, so recording never touches the network: `record` appends one JSON line to a local spool and returns. @@ -9,7 +13,8 @@ started once per session and again from the flush worker that is already detache Pure stdlib, matching the rest of the plugin. Opt out with MEM0_TELEMETRY=false. Never sends prompts, memory text, queries, file paths, repository names, or API -keys: only event names, durations, counts, coarse outcomes, and salted hashes. +keys: only event names, durations, counts, coarse outcomes, and repo/session +identifiers hashed with a random per-install salt. """ from __future__ import annotations @@ -83,9 +88,36 @@ def is_enabled() -> bool: def _digest(value: str, length: int = 16) -> str: + """Unsalted digest. Only for values that are already secrets (API keys).""" return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _install_salt() -> str: + """Random per-install salt, created on first use and kept in the identity file.""" + identity = _read_identity() + salt = identity.get("salt") + if not salt: + salt = uuid.uuid4().hex + identity["salt"] = salt + _write_identity(identity) + return salt + + +def _scoped_digest(value: str, length: int = 16) -> str: + """Salted digest for values drawn from a guessable space. + + repo.identity is a git remote URL, or ``local:`` when there is + no remote — which normally contains the account username. Sixteen unsalted + hex characters over that input space is enumerable, so this is not a + privacy control without the salt. Salting per install keeps every + within-account join the analytics actually use and gives up only + cross-machine joins on the same repository, which nothing computes. + """ + if not value: + return "" + return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + + def _safe_value(value: Any) -> Any: if isinstance(value, str): return memory_core.redact(value) @@ -175,9 +207,9 @@ def record( python_version=platform.python_version(), ) if repo is not None: - properties["repo_hash"] = _digest(getattr(repo, "identity", "")) + properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) if session_id: - properties["session_hash"] = _digest(session_id) + properties["session_hash"] = _scoped_digest(session_id) line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 249595475..1b6bd854e 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -1,5 +1,9 @@ #!/usr/bin/env python3 -"""Anonymous usage telemetry for Mem0 agent plugins. +"""Usage telemetry for Mem0 agent plugins. + +Events are linked to your Mem0 account email when an API key is configured, and +to a random per-machine id otherwise. Not anonymous — the Python SDK and CLI +attribute the same way. Hooks run on a 3-6 second budget and fire on every tool call, so recording never touches the network: `record` appends one JSON line to a local spool and returns. @@ -9,7 +13,8 @@ started once per session and again from the flush worker that is already detache Pure stdlib, matching the rest of the plugin. Opt out with MEM0_TELEMETRY=false. Never sends prompts, memory text, queries, file paths, repository names, or API -keys: only event names, durations, counts, coarse outcomes, and salted hashes. +keys: only event names, durations, counts, coarse outcomes, and repo/session +identifiers hashed with a random per-install salt. """ from __future__ import annotations @@ -83,9 +88,36 @@ def is_enabled() -> bool: def _digest(value: str, length: int = 16) -> str: + """Unsalted digest. Only for values that are already secrets (API keys).""" return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _install_salt() -> str: + """Random per-install salt, created on first use and kept in the identity file.""" + identity = _read_identity() + salt = identity.get("salt") + if not salt: + salt = uuid.uuid4().hex + identity["salt"] = salt + _write_identity(identity) + return salt + + +def _scoped_digest(value: str, length: int = 16) -> str: + """Salted digest for values drawn from a guessable space. + + repo.identity is a git remote URL, or ``local:`` when there is + no remote — which normally contains the account username. Sixteen unsalted + hex characters over that input space is enumerable, so this is not a + privacy control without the salt. Salting per install keeps every + within-account join the analytics actually use and gives up only + cross-machine joins on the same repository, which nothing computes. + """ + if not value: + return "" + return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + + def _safe_value(value: Any) -> Any: if isinstance(value, str): return memory_core.redact(value) @@ -175,9 +207,9 @@ def record( python_version=platform.python_version(), ) if repo is not None: - properties["repo_hash"] = _digest(getattr(repo, "identity", "")) + properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) if session_id: - properties["session_hash"] = _digest(session_id) + properties["session_hash"] = _scoped_digest(session_id) line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/deepseek-plugin/README.md b/integrations/deepseek-plugin/README.md index 93e5f563f..bcd333311 100644 --- a/integrations/deepseek-plugin/README.md +++ b/integrations/deepseek-plugin/README.md @@ -86,9 +86,9 @@ Per-call `userId` overrides are rejected unless the operator enables `allowUserO ## Telemetry -Writes are tagged `source="DEEPSEEK_HARNESS"` so Mem0's backend can attribute usage to this integration. For it to surface by name (rather than bucketing into `OTHERS`), `DEEPSEEK_HARNESS` must be present in the backend's `KNOWN_EVENT_SOURCES` allowlist, a one-line platform change matching the existing `ZAPIER` / `STRANDS` sources. +Writes are tagged `source="DEEPSEEK_HARNESS"`, which the Mem0 backend recognizes so usage surfaces by name rather than bucketing into `OTHERS`. -The plugin also sends anonymous usage events (which tool ran, duration, result counts, coarse failure kind) so Mem0 can tell how the plugin is used and where it breaks. Queries, memory text, and entity ids are never sent. Turn it off with `MEM0_TELEMETRY=false`. +The plugin also sends usage events (which tool ran, duration, result counts, coarse failure kind) so Mem0 can tell how the plugin is used and where it breaks. These are **not anonymous**: when an API key is configured they are sent under your Mem0 account email, the same way the SDK attributes its own. Queries, memory text, and entity ids are never sent. Turn it off with `MEM0_TELEMETRY=false`. ## Status diff --git a/integrations/deepseek-plugin/src/index.ts b/integrations/deepseek-plugin/src/index.ts index bea70c02c..2d24b498a 100644 --- a/integrations/deepseek-plugin/src/index.ts +++ b/integrations/deepseek-plugin/src/index.ts @@ -26,10 +26,8 @@ export const name = "mem0"; export const inject = ["tools", "systemPrompt"]; // Tags writes so Mem0's backend attributes them to this integration in -// telemetry. The backend keeps recognized values via its KNOWN_EVENT_SOURCES -// allowlist; unknown values bucket into "OTHERS", so "DEEPSEEK_HARNESS" must be -// added to that allowlist for usage to surface by name (a one-line backend PR, -// same pattern as the ZAPIER / STRANDS sources). +// telemetry. The backend's KNOWN_EVENT_SOURCES allowlist recognizes this value; +// anything outside it buckets into "OTHERS". const SOURCE = "DEEPSEEK_HARNESS"; const DEFAULT_SEARCH_LIMIT = 10; diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 249595475..1b6bd854e 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -1,5 +1,9 @@ #!/usr/bin/env python3 -"""Anonymous usage telemetry for Mem0 agent plugins. +"""Usage telemetry for Mem0 agent plugins. + +Events are linked to your Mem0 account email when an API key is configured, and +to a random per-machine id otherwise. Not anonymous — the Python SDK and CLI +attribute the same way. Hooks run on a 3-6 second budget and fire on every tool call, so recording never touches the network: `record` appends one JSON line to a local spool and returns. @@ -9,7 +13,8 @@ started once per session and again from the flush worker that is already detache Pure stdlib, matching the rest of the plugin. Opt out with MEM0_TELEMETRY=false. Never sends prompts, memory text, queries, file paths, repository names, or API -keys: only event names, durations, counts, coarse outcomes, and salted hashes. +keys: only event names, durations, counts, coarse outcomes, and repo/session +identifiers hashed with a random per-install salt. """ from __future__ import annotations @@ -83,9 +88,36 @@ def is_enabled() -> bool: def _digest(value: str, length: int = 16) -> str: + """Unsalted digest. Only for values that are already secrets (API keys).""" return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _install_salt() -> str: + """Random per-install salt, created on first use and kept in the identity file.""" + identity = _read_identity() + salt = identity.get("salt") + if not salt: + salt = uuid.uuid4().hex + identity["salt"] = salt + _write_identity(identity) + return salt + + +def _scoped_digest(value: str, length: int = 16) -> str: + """Salted digest for values drawn from a guessable space. + + repo.identity is a git remote URL, or ``local:`` when there is + no remote — which normally contains the account username. Sixteen unsalted + hex characters over that input space is enumerable, so this is not a + privacy control without the salt. Salting per install keeps every + within-account join the analytics actually use and gives up only + cross-machine joins on the same repository, which nothing computes. + """ + if not value: + return "" + return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + + def _safe_value(value: Any) -> Any: if isinstance(value, str): return memory_core.redact(value) @@ -175,9 +207,9 @@ def record( python_version=platform.python_version(), ) if repo is not None: - properties["repo_hash"] = _digest(getattr(repo, "identity", "")) + properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) if session_id: - properties["session_hash"] = _digest(session_id) + properties["session_hash"] = _scoped_digest(session_id) line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 249595475..1b6bd854e 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -1,5 +1,9 @@ #!/usr/bin/env python3 -"""Anonymous usage telemetry for Mem0 agent plugins. +"""Usage telemetry for Mem0 agent plugins. + +Events are linked to your Mem0 account email when an API key is configured, and +to a random per-machine id otherwise. Not anonymous — the Python SDK and CLI +attribute the same way. Hooks run on a 3-6 second budget and fire on every tool call, so recording never touches the network: `record` appends one JSON line to a local spool and returns. @@ -9,7 +13,8 @@ started once per session and again from the flush worker that is already detache Pure stdlib, matching the rest of the plugin. Opt out with MEM0_TELEMETRY=false. Never sends prompts, memory text, queries, file paths, repository names, or API -keys: only event names, durations, counts, coarse outcomes, and salted hashes. +keys: only event names, durations, counts, coarse outcomes, and repo/session +identifiers hashed with a random per-install salt. """ from __future__ import annotations @@ -83,9 +88,36 @@ def is_enabled() -> bool: def _digest(value: str, length: int = 16) -> str: + """Unsalted digest. Only for values that are already secrets (API keys).""" return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _install_salt() -> str: + """Random per-install salt, created on first use and kept in the identity file.""" + identity = _read_identity() + salt = identity.get("salt") + if not salt: + salt = uuid.uuid4().hex + identity["salt"] = salt + _write_identity(identity) + return salt + + +def _scoped_digest(value: str, length: int = 16) -> str: + """Salted digest for values drawn from a guessable space. + + repo.identity is a git remote URL, or ``local:`` when there is + no remote — which normally contains the account username. Sixteen unsalted + hex characters over that input space is enumerable, so this is not a + privacy control without the salt. Salting per install keeps every + within-account join the analytics actually use and gives up only + cross-machine joins on the same repository, which nothing computes. + """ + if not value: + return "" + return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + + def _safe_value(value: Any) -> Any: if isinstance(value, str): return memory_core.redact(value) @@ -175,9 +207,9 @@ def record( python_version=platform.python_version(), ) if repo is not None: - properties["repo_hash"] = _digest(getattr(repo, "identity", "")) + properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) if session_id: - properties["session_hash"] = _digest(session_id) + properties["session_hash"] = _scoped_digest(session_id) line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/mem0-strands/README.md b/integrations/mem0-strands/README.md index f45d98e44..8ea4ecacc 100644 --- a/integrations/mem0-strands/README.md +++ b/integrations/mem0-strands/README.md @@ -79,9 +79,11 @@ the tool share one Mem0 backend and namespace. ## Telemetry -The store sends anonymous usage events (store configuration, operation, duration, -result counts, coarse failure kind) over the Mem0 SDK's existing telemetry client, -tagged `source="STRANDS"`. Queries, memory text, message content, entity ids, and +The store sends usage events (store configuration, operation, duration, result +counts, coarse failure kind) over the Mem0 SDK's existing telemetry client, +tagged `source="STRANDS"`. These are **not anonymous**: when an API key is +configured they are sent under your Mem0 account email, the same way the SDK +attributes its own. Queries, memory text, message content, entity ids, and metadata are never sent. Turn it off with `MEM0_TELEMETRY=false`. ## Development From f9c566aa161e1090c6aacf742b345ca0a9a52e52 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:17:53 +0530 Subject: [PATCH 02/30] fix(plugins): report the plugin that produced the event, not the one that sent it MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit harness is set when an event is recorded; source was set when its batch was sent. Both came from module globals that stay at "generic" and "MEM0_PLUGIN" until telemetry.init() runs, and two processes in the pipeline never run it: - `python3 telemetry.py`, the detached sender spawn_flush() starts at session start, after every skill command, and when the MCP server exits. Everything it delivered was labelled source=MEM0_PLUGIN. Only batches flush_worker.py happened to drain got the real host. - mcp_server.py, which records every manual search as harness=generic. All six Python plugins ship the same files, so source could not tell any of them apart and MCP searches from every plugin landed in one generic bucket. The portable plugin is worse: it has no flush_worker at all, so its only sender is the uninitialised one and 100% of its events were mislabelled. Two changes. record() stamps source beside harness, so the sending process stops mattering — flush() already spreads per-event properties last, so a per-event source wins over any sender default. And the build generates core/_harness_id.py per host, seeding both modules at import, so identity no longer depends on an entrypoint remembering to call init(). The build already computed HARNESS_ID and spent it only on skill templating, and bundle_drift already diffs core/ byte-for-byte, so --check catches drift for free. Deliberately not adding MEM0_PLUGIN_HARNESS to the six manifests: they sit outside the --sync and --check boundary, which is the property that caused this. Also unifies two defaults that disagreed. configure_harness derived `_plugin` while telemetry.init derived `MEM0__PLUGIN`, so a third value existed. It was unreachable only because hook_runner never calls flush(); moving source into record() would have made it live. Events now carry a uuid so a resend can be collapsed. The suite stayed green through all of this because the only tests live under one host, behind a conftest that calls init() at import. New tests run in real subprocesses with no init, and cover the portable plugin, which would pass a native-only test vacuously. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- integrations/agent-plugin-core/build/build.py | 28 +++ .../agent-plugin-core/python/telemetry.py | 42 +++- .../tests/test_uninitialised_identity.py | 179 ++++++++++++++++++ .../antigravity-plugin/core/_harness_id.py | 9 + .../antigravity-plugin/core/telemetry.py | 42 +++- .../claude-code-plugin/core/_harness_id.py | 9 + .../claude-code-plugin/core/telemetry.py | 42 +++- integrations/codex-plugin/core/_harness_id.py | 9 + integrations/codex-plugin/core/telemetry.py | 42 +++- .../cursor-plugin/core/_harness_id.py | 9 + integrations/cursor-plugin/core/telemetry.py | 42 +++- integrations/kimi-plugin/core/_harness_id.py | 9 + integrations/kimi-plugin/core/telemetry.py | 42 +++- .../mem0-agent-plugin/core/_harness_id.py | 9 + .../mem0-agent-plugin/core/telemetry.py | 42 +++- 15 files changed, 520 insertions(+), 35 deletions(-) create mode 100644 integrations/agent-plugin-core/tests/test_uninitialised_identity.py create mode 100644 integrations/antigravity-plugin/core/_harness_id.py create mode 100644 integrations/claude-code-plugin/core/_harness_id.py create mode 100644 integrations/codex-plugin/core/_harness_id.py create mode 100644 integrations/cursor-plugin/core/_harness_id.py create mode 100644 integrations/kimi-plugin/core/_harness_id.py create mode 100644 integrations/mem0-agent-plugin/core/_harness_id.py diff --git a/integrations/agent-plugin-core/build/build.py b/integrations/agent-plugin-core/build/build.py index 7a72e5c51..e675efb02 100644 --- a/integrations/agent-plugin-core/build/build.py +++ b/integrations/agent-plugin-core/build/build.py @@ -81,6 +81,28 @@ def replace_output(staged: Path, output: Path) -> Path: return output +def _render_harness_id(host: str) -> str: + """Emit core/_harness_id.py for one host. + + Carries both vocabularies from a single definition: the PostHog `source` tag + and the platform's X-Mem0-Source / X-Application pair. Keeping them together + is what stops the two from drifting into separate vocabularies for the same + thing. + """ + tag = host.upper().replace("-", "_") + "_PLUGIN" + return ( + '"""Generated by integrations/agent-plugin-core/build/build.py. Do not edit."""\n' + "\n" + f'HARNESS_ID = "{host}"\n' + f'SOURCE_TAG = "{tag}"\n' + "\n" + "# Platform-side vocabulary (mem0_event.source + X-Application). The whole\n" + "# plugin family is one source; which editor it runs in is the application.\n" + 'PLATFORM_SOURCE = "MEM0_PLUGIN"\n' + f'PLATFORM_APPLICATION = "{host}"\n' + ) + + def _bundle_python( staged: Path, host: str, @@ -96,6 +118,12 @@ def _bundle_python( continue shutil.copy2(source, core / source.name) + # Generated per host so identity does not depend on an entrypoint remembering + # to call telemetry.init(). mcp_server.py and the detached telemetry.py sender + # never did, which is how MCP searches reported harness=generic and every + # batch they drained was labelled MEM0_PLUGIN regardless of the real host. + (core / "_harness_id.py").write_text(_render_harness_id(host), encoding="utf-8") + values = { "PLUGIN_ROOT": plugin_root, "PLUGIN_DATA": "${PLUGIN_DATA}", diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 1b6bd854e..157db297d 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -34,8 +34,23 @@ from typing import Any import memory_core -_harness: str = "generic" -_source_tag: str = "MEM0_PLUGIN" +# Seeded from the per-host module the build generates into core/. Two processes +# in this pipeline never call init() — mcp_server.py, and the detached +# `python3 telemetry.py` sender that spawn_flush() starts — so a module default +# was what every one of their events got labelled with. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import HARNESS_ID as _DEFAULT_HARNESS + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE + from _harness_id import SOURCE_TAG as _DEFAULT_SOURCE_TAG +except ImportError: + _DEFAULT_HARNESS = "generic" + _DEFAULT_SOURCE_TAG = "MEM0_PLUGIN" + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + +_harness: str = _DEFAULT_HARNESS +_source_tag: str = _DEFAULT_SOURCE_TAG _PRIVATE_KEYS = { "apikey", "authorization", @@ -61,10 +76,19 @@ _PRIVATE_KEYS = { } -def init(harness: str = "generic", source_tag: str = "") -> None: +def init(harness: str = "", source_tag: str = "") -> None: + """Override the generated identity. Optional — core/_harness_id.py is the default. + + The fallback shape matches memory_core.configure_harness's (``_PLUGIN``). + It used to be ``MEM0__PLUGIN`` here and ``_plugin`` there, which + meant one plugin could emit three different source values depending on which + process happened to send the batch. + """ global _harness, _source_tag - _harness = harness - _source_tag = source_tag or f"MEM0_{harness.upper().replace('-', '_')}_PLUGIN" + _harness = harness or _DEFAULT_HARNESS + _source_tag = source_tag or ( + f"{_harness.upper().replace('-', '_')}_PLUGIN" if harness else _DEFAULT_SOURCE_TAG + ) POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX" POSTHOG_CAPTURE_URL = "https://us.i.posthog.com/i/v0/e/" @@ -200,8 +224,13 @@ def record( except OSError: pass properties = _safe_value(properties) + # Stamped in the RECORDING process, beside harness. `source` used to be + # read in the sending process from a module global, so whichever process + # drained the spool named every event in it. flush() spreads per-event + # properties last, so this now wins over any sender's default. properties.update( harness=_harness, + source=_source_tag, plugin_version=memory_core.PLUGIN_VERSION, os=sys.platform, python_version=platform.python_version(), @@ -213,6 +242,7 @@ def record( line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", + "uuid": str(uuid.uuid4()), "timestamp": memory_core.utc_now(), "properties": { key: value for key, value in properties.items() if value is not None @@ -398,6 +428,8 @@ def flush() -> int: "distinct_id": distinct_id, "timestamp": event.get("timestamp"), "properties": { + # Fallback only: events recorded by a build before source + # moved into record() have none of their own. "source": _source_tag, "language": "python", "$process_person_profile": False, diff --git a/integrations/agent-plugin-core/tests/test_uninitialised_identity.py b/integrations/agent-plugin-core/tests/test_uninitialised_identity.py new file mode 100644 index 000000000..14f911bee --- /dev/null +++ b/integrations/agent-plugin-core/tests/test_uninitialised_identity.py @@ -0,0 +1,179 @@ +"""Core telemetry behaviour with NO telemetry.init(), in a real subprocess. + +Why this file exists +-------------------- +``telemetry.py`` lives in ``agent-plugin-core/python/`` but its only tests lived +under ``claude-code-plugin/tests/``, behind a ``conftest.py`` that calls +``configure_harness()`` and ``telemetry.init()`` at import. Core behaviour was +therefore only ever exercised inside an already-configured module. + +Two processes in the real pipeline never call ``init()``: + +- ``mcp_server.py``, which records every manual search; +- the detached ``python3 telemetry.py`` sender that ``spawn_flush()`` starts at + session start, after every skill command, and when the MCP server exits. + +Both fell back to module defaults, so MCP searches reported ``harness=generic`` +and everything that sender delivered was labelled ``MEM0_PLUGIN`` regardless of +which of the six plugins produced it. The suite stayed green throughout. + +These tests run in a fresh interpreter with no conftest, against a built host +bundle, which is the only arrangement that can catch that class of bug. +""" + +from __future__ import annotations + +import json +import subprocess +import sys +import tempfile +from pathlib import Path + +import pytest + +CORE_ROOT = Path(__file__).resolve().parents[1] +REPOSITORY_ROOT = CORE_ROOT.parents[1] +HOSTS = { + "claude-code": ("claude-code-plugin", "CLAUDE_CODE_PLUGIN"), + "cursor": ("cursor-plugin", "CURSOR_PLUGIN"), + "codex": ("codex-plugin", "CODEX_PLUGIN"), + "kimi": ("kimi-plugin", "KIMI_PLUGIN"), + "antigravity": ("antigravity-plugin", "ANTIGRAVITY_PLUGIN"), + # Portable: no flush_worker and no hook_runner, so its ONLY sender is the + # uninitialised telemetry.py. A native-only test passes here vacuously. + "coding-agent": ("mem0-agent-plugin", "CODING_AGENT_PLUGIN"), +} + + +def _core_dir(directory: str) -> Path: + return REPOSITORY_ROOT / "integrations" / directory / "core" + + +def _run(core: Path, data_dir: Path, body: str) -> str: + """Execute `body` in a fresh interpreter with only the host's core on sys.path.""" + script = f"import sys; sys.path.insert(0, {str(core)!r})\n{body}" + result = subprocess.run( + [sys.executable, "-c", script], + capture_output=True, + text=True, + env={ + "MEM0_CODE_DATA_DIR": str(data_dir), + "PATH": "/usr/bin:/bin", + "HOME": str(data_dir), + }, + ) + assert result.returncode == 0, result.stderr + return result.stdout.strip() + + +@pytest.mark.parametrize("harness,spec", sorted(HOSTS.items())) +def test_identity_resolves_without_init(harness, spec): + """Every built host knows what it is with no configuration call at all.""" + directory, source_tag = spec + core = _core_dir(directory) + if not core.exists(): + pytest.skip(f"{directory} is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + out = _run( + core, + Path(tmp), + "import telemetry; print(telemetry._harness, telemetry._source_tag)", + ) + assert out == f"{harness} {source_tag}" + + +def test_mcp_server_records_the_real_harness(): + """mcp_server imports telemetry and never initialises it (server.py has no init). + + Its recorded events used to carry harness=generic for every plugin. + """ + core = _core_dir("claude-code-plugin") + if not core.exists(): + pytest.skip("claude-code-plugin is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + data_dir = Path(tmp) + _run( + core, + data_dir, + "import mcp_server, telemetry; telemetry.record('search', trigger='mcp-search')", + ) + spooled = (data_dir / "telemetry.jsonl").read_text(encoding="utf-8").strip() + + event = json.loads(spooled) + assert event["properties"]["harness"] == "claude-code" + assert event["properties"]["source"] == "CLAUDE_CODE_PLUGIN" + + +def test_the_detached_sender_does_not_relabel_events(): + """`python3 telemetry.py` is the sender spawn_flush() starts, and never inits. + + source is stamped at record time now, so which process sends is irrelevant. + """ + core = _core_dir("claude-code-plugin") + if not core.exists(): + pytest.skip("claude-code-plugin is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + data_dir = Path(tmp) + _run(core, data_dir, "import telemetry; telemetry.record('search')") + + captured = data_dir / "captured.json" + # Drain with a fresh, unconfigured interpreter, capturing the payload + # instead of posting it. + _run( + core, + data_dir, + "import json, telemetry\n" + "sent = []\n" + "telemetry._post = lambda payload, url: sent.append(payload) or True\n" + "telemetry.flush()\n" + f"open({str(captured)!r}, 'w').write(json.dumps(sent))", + ) + payloads = json.loads(captured.read_text(encoding="utf-8")) + + batches = [p for p in payloads if "batch" in p] + assert batches, "nothing was sent" + properties = batches[0]["batch"][0]["properties"] + assert properties["source"] == "CLAUDE_CODE_PLUGIN" + assert properties["harness"] == "claude-code" + + +def test_every_event_carries_a_uuid_for_dedupe(): + core = _core_dir("claude-code-plugin") + if not core.exists(): + pytest.skip("claude-code-plugin is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + data_dir = Path(tmp) + _run(core, data_dir, "import telemetry; telemetry.record('search'); telemetry.record('flush')") + lines = (data_dir / "telemetry.jsonl").read_text(encoding="utf-8").strip().splitlines() + + ids = [json.loads(line)["uuid"] for line in lines] + assert len(ids) == 2 + assert len(set(ids)) == 2 + + +def test_source_tag_defaults_agree_between_the_two_modules(): + """configure_harness and telemetry.init must derive the same tag. + + They disagreed: `_plugin` in one and `MEM0__PLUGIN` in the other, + so one plugin could emit three different source values depending on which + process sent the batch. + """ + core = _core_dir("claude-code-plugin") + if not core.exists(): + pytest.skip("claude-code-plugin is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + out = _run( + core, + Path(tmp), + "import memory_core, telemetry\n" + "memory_core.configure_harness('kimi')\n" + "telemetry.init(harness='kimi')\n" + "print(memory_core.harness_config()['source_tag'].upper(), telemetry._source_tag)", + ) + left, right = out.split() + assert left == right == "KIMI_PLUGIN" diff --git a/integrations/antigravity-plugin/core/_harness_id.py b/integrations/antigravity-plugin/core/_harness_id.py new file mode 100644 index 000000000..2c8a515f4 --- /dev/null +++ b/integrations/antigravity-plugin/core/_harness_id.py @@ -0,0 +1,9 @@ +"""Generated by integrations/agent-plugin-core/build/build.py. Do not edit.""" + +HARNESS_ID = "antigravity" +SOURCE_TAG = "ANTIGRAVITY_PLUGIN" + +# Platform-side vocabulary (mem0_event.source + X-Application). The whole +# plugin family is one source; which editor it runs in is the application. +PLATFORM_SOURCE = "MEM0_PLUGIN" +PLATFORM_APPLICATION = "antigravity" diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 1b6bd854e..157db297d 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -34,8 +34,23 @@ from typing import Any import memory_core -_harness: str = "generic" -_source_tag: str = "MEM0_PLUGIN" +# Seeded from the per-host module the build generates into core/. Two processes +# in this pipeline never call init() — mcp_server.py, and the detached +# `python3 telemetry.py` sender that spawn_flush() starts — so a module default +# was what every one of their events got labelled with. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import HARNESS_ID as _DEFAULT_HARNESS + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE + from _harness_id import SOURCE_TAG as _DEFAULT_SOURCE_TAG +except ImportError: + _DEFAULT_HARNESS = "generic" + _DEFAULT_SOURCE_TAG = "MEM0_PLUGIN" + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + +_harness: str = _DEFAULT_HARNESS +_source_tag: str = _DEFAULT_SOURCE_TAG _PRIVATE_KEYS = { "apikey", "authorization", @@ -61,10 +76,19 @@ _PRIVATE_KEYS = { } -def init(harness: str = "generic", source_tag: str = "") -> None: +def init(harness: str = "", source_tag: str = "") -> None: + """Override the generated identity. Optional — core/_harness_id.py is the default. + + The fallback shape matches memory_core.configure_harness's (``_PLUGIN``). + It used to be ``MEM0__PLUGIN`` here and ``_plugin`` there, which + meant one plugin could emit three different source values depending on which + process happened to send the batch. + """ global _harness, _source_tag - _harness = harness - _source_tag = source_tag or f"MEM0_{harness.upper().replace('-', '_')}_PLUGIN" + _harness = harness or _DEFAULT_HARNESS + _source_tag = source_tag or ( + f"{_harness.upper().replace('-', '_')}_PLUGIN" if harness else _DEFAULT_SOURCE_TAG + ) POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX" POSTHOG_CAPTURE_URL = "https://us.i.posthog.com/i/v0/e/" @@ -200,8 +224,13 @@ def record( except OSError: pass properties = _safe_value(properties) + # Stamped in the RECORDING process, beside harness. `source` used to be + # read in the sending process from a module global, so whichever process + # drained the spool named every event in it. flush() spreads per-event + # properties last, so this now wins over any sender's default. properties.update( harness=_harness, + source=_source_tag, plugin_version=memory_core.PLUGIN_VERSION, os=sys.platform, python_version=platform.python_version(), @@ -213,6 +242,7 @@ def record( line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", + "uuid": str(uuid.uuid4()), "timestamp": memory_core.utc_now(), "properties": { key: value for key, value in properties.items() if value is not None @@ -398,6 +428,8 @@ def flush() -> int: "distinct_id": distinct_id, "timestamp": event.get("timestamp"), "properties": { + # Fallback only: events recorded by a build before source + # moved into record() have none of their own. "source": _source_tag, "language": "python", "$process_person_profile": False, diff --git a/integrations/claude-code-plugin/core/_harness_id.py b/integrations/claude-code-plugin/core/_harness_id.py new file mode 100644 index 000000000..6c3e1ce15 --- /dev/null +++ b/integrations/claude-code-plugin/core/_harness_id.py @@ -0,0 +1,9 @@ +"""Generated by integrations/agent-plugin-core/build/build.py. Do not edit.""" + +HARNESS_ID = "claude-code" +SOURCE_TAG = "CLAUDE_CODE_PLUGIN" + +# Platform-side vocabulary (mem0_event.source + X-Application). The whole +# plugin family is one source; which editor it runs in is the application. +PLATFORM_SOURCE = "MEM0_PLUGIN" +PLATFORM_APPLICATION = "claude-code" diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 1b6bd854e..157db297d 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -34,8 +34,23 @@ from typing import Any import memory_core -_harness: str = "generic" -_source_tag: str = "MEM0_PLUGIN" +# Seeded from the per-host module the build generates into core/. Two processes +# in this pipeline never call init() — mcp_server.py, and the detached +# `python3 telemetry.py` sender that spawn_flush() starts — so a module default +# was what every one of their events got labelled with. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import HARNESS_ID as _DEFAULT_HARNESS + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE + from _harness_id import SOURCE_TAG as _DEFAULT_SOURCE_TAG +except ImportError: + _DEFAULT_HARNESS = "generic" + _DEFAULT_SOURCE_TAG = "MEM0_PLUGIN" + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + +_harness: str = _DEFAULT_HARNESS +_source_tag: str = _DEFAULT_SOURCE_TAG _PRIVATE_KEYS = { "apikey", "authorization", @@ -61,10 +76,19 @@ _PRIVATE_KEYS = { } -def init(harness: str = "generic", source_tag: str = "") -> None: +def init(harness: str = "", source_tag: str = "") -> None: + """Override the generated identity. Optional — core/_harness_id.py is the default. + + The fallback shape matches memory_core.configure_harness's (``_PLUGIN``). + It used to be ``MEM0__PLUGIN`` here and ``_plugin`` there, which + meant one plugin could emit three different source values depending on which + process happened to send the batch. + """ global _harness, _source_tag - _harness = harness - _source_tag = source_tag or f"MEM0_{harness.upper().replace('-', '_')}_PLUGIN" + _harness = harness or _DEFAULT_HARNESS + _source_tag = source_tag or ( + f"{_harness.upper().replace('-', '_')}_PLUGIN" if harness else _DEFAULT_SOURCE_TAG + ) POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX" POSTHOG_CAPTURE_URL = "https://us.i.posthog.com/i/v0/e/" @@ -200,8 +224,13 @@ def record( except OSError: pass properties = _safe_value(properties) + # Stamped in the RECORDING process, beside harness. `source` used to be + # read in the sending process from a module global, so whichever process + # drained the spool named every event in it. flush() spreads per-event + # properties last, so this now wins over any sender's default. properties.update( harness=_harness, + source=_source_tag, plugin_version=memory_core.PLUGIN_VERSION, os=sys.platform, python_version=platform.python_version(), @@ -213,6 +242,7 @@ def record( line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", + "uuid": str(uuid.uuid4()), "timestamp": memory_core.utc_now(), "properties": { key: value for key, value in properties.items() if value is not None @@ -398,6 +428,8 @@ def flush() -> int: "distinct_id": distinct_id, "timestamp": event.get("timestamp"), "properties": { + # Fallback only: events recorded by a build before source + # moved into record() have none of their own. "source": _source_tag, "language": "python", "$process_person_profile": False, diff --git a/integrations/codex-plugin/core/_harness_id.py b/integrations/codex-plugin/core/_harness_id.py new file mode 100644 index 000000000..152313a21 --- /dev/null +++ b/integrations/codex-plugin/core/_harness_id.py @@ -0,0 +1,9 @@ +"""Generated by integrations/agent-plugin-core/build/build.py. Do not edit.""" + +HARNESS_ID = "codex" +SOURCE_TAG = "CODEX_PLUGIN" + +# Platform-side vocabulary (mem0_event.source + X-Application). The whole +# plugin family is one source; which editor it runs in is the application. +PLATFORM_SOURCE = "MEM0_PLUGIN" +PLATFORM_APPLICATION = "codex" diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 1b6bd854e..157db297d 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -34,8 +34,23 @@ from typing import Any import memory_core -_harness: str = "generic" -_source_tag: str = "MEM0_PLUGIN" +# Seeded from the per-host module the build generates into core/. Two processes +# in this pipeline never call init() — mcp_server.py, and the detached +# `python3 telemetry.py` sender that spawn_flush() starts — so a module default +# was what every one of their events got labelled with. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import HARNESS_ID as _DEFAULT_HARNESS + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE + from _harness_id import SOURCE_TAG as _DEFAULT_SOURCE_TAG +except ImportError: + _DEFAULT_HARNESS = "generic" + _DEFAULT_SOURCE_TAG = "MEM0_PLUGIN" + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + +_harness: str = _DEFAULT_HARNESS +_source_tag: str = _DEFAULT_SOURCE_TAG _PRIVATE_KEYS = { "apikey", "authorization", @@ -61,10 +76,19 @@ _PRIVATE_KEYS = { } -def init(harness: str = "generic", source_tag: str = "") -> None: +def init(harness: str = "", source_tag: str = "") -> None: + """Override the generated identity. Optional — core/_harness_id.py is the default. + + The fallback shape matches memory_core.configure_harness's (``_PLUGIN``). + It used to be ``MEM0__PLUGIN`` here and ``_plugin`` there, which + meant one plugin could emit three different source values depending on which + process happened to send the batch. + """ global _harness, _source_tag - _harness = harness - _source_tag = source_tag or f"MEM0_{harness.upper().replace('-', '_')}_PLUGIN" + _harness = harness or _DEFAULT_HARNESS + _source_tag = source_tag or ( + f"{_harness.upper().replace('-', '_')}_PLUGIN" if harness else _DEFAULT_SOURCE_TAG + ) POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX" POSTHOG_CAPTURE_URL = "https://us.i.posthog.com/i/v0/e/" @@ -200,8 +224,13 @@ def record( except OSError: pass properties = _safe_value(properties) + # Stamped in the RECORDING process, beside harness. `source` used to be + # read in the sending process from a module global, so whichever process + # drained the spool named every event in it. flush() spreads per-event + # properties last, so this now wins over any sender's default. properties.update( harness=_harness, + source=_source_tag, plugin_version=memory_core.PLUGIN_VERSION, os=sys.platform, python_version=platform.python_version(), @@ -213,6 +242,7 @@ def record( line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", + "uuid": str(uuid.uuid4()), "timestamp": memory_core.utc_now(), "properties": { key: value for key, value in properties.items() if value is not None @@ -398,6 +428,8 @@ def flush() -> int: "distinct_id": distinct_id, "timestamp": event.get("timestamp"), "properties": { + # Fallback only: events recorded by a build before source + # moved into record() have none of their own. "source": _source_tag, "language": "python", "$process_person_profile": False, diff --git a/integrations/cursor-plugin/core/_harness_id.py b/integrations/cursor-plugin/core/_harness_id.py new file mode 100644 index 000000000..40241a7f4 --- /dev/null +++ b/integrations/cursor-plugin/core/_harness_id.py @@ -0,0 +1,9 @@ +"""Generated by integrations/agent-plugin-core/build/build.py. Do not edit.""" + +HARNESS_ID = "cursor" +SOURCE_TAG = "CURSOR_PLUGIN" + +# Platform-side vocabulary (mem0_event.source + X-Application). The whole +# plugin family is one source; which editor it runs in is the application. +PLATFORM_SOURCE = "MEM0_PLUGIN" +PLATFORM_APPLICATION = "cursor" diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 1b6bd854e..157db297d 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -34,8 +34,23 @@ from typing import Any import memory_core -_harness: str = "generic" -_source_tag: str = "MEM0_PLUGIN" +# Seeded from the per-host module the build generates into core/. Two processes +# in this pipeline never call init() — mcp_server.py, and the detached +# `python3 telemetry.py` sender that spawn_flush() starts — so a module default +# was what every one of their events got labelled with. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import HARNESS_ID as _DEFAULT_HARNESS + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE + from _harness_id import SOURCE_TAG as _DEFAULT_SOURCE_TAG +except ImportError: + _DEFAULT_HARNESS = "generic" + _DEFAULT_SOURCE_TAG = "MEM0_PLUGIN" + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + +_harness: str = _DEFAULT_HARNESS +_source_tag: str = _DEFAULT_SOURCE_TAG _PRIVATE_KEYS = { "apikey", "authorization", @@ -61,10 +76,19 @@ _PRIVATE_KEYS = { } -def init(harness: str = "generic", source_tag: str = "") -> None: +def init(harness: str = "", source_tag: str = "") -> None: + """Override the generated identity. Optional — core/_harness_id.py is the default. + + The fallback shape matches memory_core.configure_harness's (``_PLUGIN``). + It used to be ``MEM0__PLUGIN`` here and ``_plugin`` there, which + meant one plugin could emit three different source values depending on which + process happened to send the batch. + """ global _harness, _source_tag - _harness = harness - _source_tag = source_tag or f"MEM0_{harness.upper().replace('-', '_')}_PLUGIN" + _harness = harness or _DEFAULT_HARNESS + _source_tag = source_tag or ( + f"{_harness.upper().replace('-', '_')}_PLUGIN" if harness else _DEFAULT_SOURCE_TAG + ) POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX" POSTHOG_CAPTURE_URL = "https://us.i.posthog.com/i/v0/e/" @@ -200,8 +224,13 @@ def record( except OSError: pass properties = _safe_value(properties) + # Stamped in the RECORDING process, beside harness. `source` used to be + # read in the sending process from a module global, so whichever process + # drained the spool named every event in it. flush() spreads per-event + # properties last, so this now wins over any sender's default. properties.update( harness=_harness, + source=_source_tag, plugin_version=memory_core.PLUGIN_VERSION, os=sys.platform, python_version=platform.python_version(), @@ -213,6 +242,7 @@ def record( line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", + "uuid": str(uuid.uuid4()), "timestamp": memory_core.utc_now(), "properties": { key: value for key, value in properties.items() if value is not None @@ -398,6 +428,8 @@ def flush() -> int: "distinct_id": distinct_id, "timestamp": event.get("timestamp"), "properties": { + # Fallback only: events recorded by a build before source + # moved into record() have none of their own. "source": _source_tag, "language": "python", "$process_person_profile": False, diff --git a/integrations/kimi-plugin/core/_harness_id.py b/integrations/kimi-plugin/core/_harness_id.py new file mode 100644 index 000000000..aa17750b1 --- /dev/null +++ b/integrations/kimi-plugin/core/_harness_id.py @@ -0,0 +1,9 @@ +"""Generated by integrations/agent-plugin-core/build/build.py. Do not edit.""" + +HARNESS_ID = "kimi" +SOURCE_TAG = "KIMI_PLUGIN" + +# Platform-side vocabulary (mem0_event.source + X-Application). The whole +# plugin family is one source; which editor it runs in is the application. +PLATFORM_SOURCE = "MEM0_PLUGIN" +PLATFORM_APPLICATION = "kimi" diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 1b6bd854e..157db297d 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -34,8 +34,23 @@ from typing import Any import memory_core -_harness: str = "generic" -_source_tag: str = "MEM0_PLUGIN" +# Seeded from the per-host module the build generates into core/. Two processes +# in this pipeline never call init() — mcp_server.py, and the detached +# `python3 telemetry.py` sender that spawn_flush() starts — so a module default +# was what every one of their events got labelled with. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import HARNESS_ID as _DEFAULT_HARNESS + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE + from _harness_id import SOURCE_TAG as _DEFAULT_SOURCE_TAG +except ImportError: + _DEFAULT_HARNESS = "generic" + _DEFAULT_SOURCE_TAG = "MEM0_PLUGIN" + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + +_harness: str = _DEFAULT_HARNESS +_source_tag: str = _DEFAULT_SOURCE_TAG _PRIVATE_KEYS = { "apikey", "authorization", @@ -61,10 +76,19 @@ _PRIVATE_KEYS = { } -def init(harness: str = "generic", source_tag: str = "") -> None: +def init(harness: str = "", source_tag: str = "") -> None: + """Override the generated identity. Optional — core/_harness_id.py is the default. + + The fallback shape matches memory_core.configure_harness's (``_PLUGIN``). + It used to be ``MEM0__PLUGIN`` here and ``_plugin`` there, which + meant one plugin could emit three different source values depending on which + process happened to send the batch. + """ global _harness, _source_tag - _harness = harness - _source_tag = source_tag or f"MEM0_{harness.upper().replace('-', '_')}_PLUGIN" + _harness = harness or _DEFAULT_HARNESS + _source_tag = source_tag or ( + f"{_harness.upper().replace('-', '_')}_PLUGIN" if harness else _DEFAULT_SOURCE_TAG + ) POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX" POSTHOG_CAPTURE_URL = "https://us.i.posthog.com/i/v0/e/" @@ -200,8 +224,13 @@ def record( except OSError: pass properties = _safe_value(properties) + # Stamped in the RECORDING process, beside harness. `source` used to be + # read in the sending process from a module global, so whichever process + # drained the spool named every event in it. flush() spreads per-event + # properties last, so this now wins over any sender's default. properties.update( harness=_harness, + source=_source_tag, plugin_version=memory_core.PLUGIN_VERSION, os=sys.platform, python_version=platform.python_version(), @@ -213,6 +242,7 @@ def record( line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", + "uuid": str(uuid.uuid4()), "timestamp": memory_core.utc_now(), "properties": { key: value for key, value in properties.items() if value is not None @@ -398,6 +428,8 @@ def flush() -> int: "distinct_id": distinct_id, "timestamp": event.get("timestamp"), "properties": { + # Fallback only: events recorded by a build before source + # moved into record() have none of their own. "source": _source_tag, "language": "python", "$process_person_profile": False, diff --git a/integrations/mem0-agent-plugin/core/_harness_id.py b/integrations/mem0-agent-plugin/core/_harness_id.py new file mode 100644 index 000000000..b0836d6de --- /dev/null +++ b/integrations/mem0-agent-plugin/core/_harness_id.py @@ -0,0 +1,9 @@ +"""Generated by integrations/agent-plugin-core/build/build.py. Do not edit.""" + +HARNESS_ID = "coding-agent" +SOURCE_TAG = "CODING_AGENT_PLUGIN" + +# Platform-side vocabulary (mem0_event.source + X-Application). The whole +# plugin family is one source; which editor it runs in is the application. +PLATFORM_SOURCE = "MEM0_PLUGIN" +PLATFORM_APPLICATION = "coding-agent" diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 1b6bd854e..157db297d 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -34,8 +34,23 @@ from typing import Any import memory_core -_harness: str = "generic" -_source_tag: str = "MEM0_PLUGIN" +# Seeded from the per-host module the build generates into core/. Two processes +# in this pipeline never call init() — mcp_server.py, and the detached +# `python3 telemetry.py` sender that spawn_flush() starts — so a module default +# was what every one of their events got labelled with. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import HARNESS_ID as _DEFAULT_HARNESS + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE + from _harness_id import SOURCE_TAG as _DEFAULT_SOURCE_TAG +except ImportError: + _DEFAULT_HARNESS = "generic" + _DEFAULT_SOURCE_TAG = "MEM0_PLUGIN" + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + +_harness: str = _DEFAULT_HARNESS +_source_tag: str = _DEFAULT_SOURCE_TAG _PRIVATE_KEYS = { "apikey", "authorization", @@ -61,10 +76,19 @@ _PRIVATE_KEYS = { } -def init(harness: str = "generic", source_tag: str = "") -> None: +def init(harness: str = "", source_tag: str = "") -> None: + """Override the generated identity. Optional — core/_harness_id.py is the default. + + The fallback shape matches memory_core.configure_harness's (``_PLUGIN``). + It used to be ``MEM0__PLUGIN`` here and ``_plugin`` there, which + meant one plugin could emit three different source values depending on which + process happened to send the batch. + """ global _harness, _source_tag - _harness = harness - _source_tag = source_tag or f"MEM0_{harness.upper().replace('-', '_')}_PLUGIN" + _harness = harness or _DEFAULT_HARNESS + _source_tag = source_tag or ( + f"{_harness.upper().replace('-', '_')}_PLUGIN" if harness else _DEFAULT_SOURCE_TAG + ) POSTHOG_API_KEY = "phc_hgJkUVJFYtmaJqrvf6CYN67TIQ8yhXAkWzUn9AMU4yX" POSTHOG_CAPTURE_URL = "https://us.i.posthog.com/i/v0/e/" @@ -200,8 +224,13 @@ def record( except OSError: pass properties = _safe_value(properties) + # Stamped in the RECORDING process, beside harness. `source` used to be + # read in the sending process from a module global, so whichever process + # drained the spool named every event in it. flush() spreads per-event + # properties last, so this now wins over any sender's default. properties.update( harness=_harness, + source=_source_tag, plugin_version=memory_core.PLUGIN_VERSION, os=sys.platform, python_version=platform.python_version(), @@ -213,6 +242,7 @@ def record( line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", + "uuid": str(uuid.uuid4()), "timestamp": memory_core.utc_now(), "properties": { key: value for key, value in properties.items() if value is not None @@ -398,6 +428,8 @@ def flush() -> int: "distinct_id": distinct_id, "timestamp": event.get("timestamp"), "properties": { + # Fallback only: events recorded by a build before source + # moved into record() have none of their own. "source": _source_tag, "language": "python", "$process_person_profile": False, From cfdfe40e090c54bf2d7640afae66b2bc2dadae2a Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:18:21 +0530 Subject: [PATCH 03/30] fix(plugins): stop delivering telemetry events twice, and stop losing parked ones MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two defects, one cause: the spool protocol infers ownership instead of holding it, and never records progress. Duplicate delivery after a partial failure. flush() posts the claim in batches of 100 and returns on the first failure, keeping the whole file. The retry then posts every batch again, including the ones that already arrived — 150 recorded events were delivered 250 times. Progress is now written back to the claim after each successful batch, so a retry resumes where the send stopped and a crash repeats at most one batch. Duplicate delivery when two senders overlap. spool.replace(claim) is os.rename, which preserves mtime, so a claim created after a quiet minute inherited the spool's last-write time and looked abandoned the instant it existed. A second sender starting while the first was still posting took it over and sent it too — most likely at session end, when the MCP server's exit sender and the SessionEnd flush worker both drain. Claims are now touched at claim time, and the per-batch rewrite doubles as a lease heartbeat. _post makes one attempt with SEND_TIMEOUT and no retry, so a heartbeat lands well inside the 120s lease; a test asserts that margin so adding a retry loop to _post cannot silently break it. Parked batches starved. _claim_spool only looked at parked .sending files when no spool existed, and because sessions keep recording there usually was one — so a batch parked by a failed send waited until the 7-day expiry deleted it unsent, despite its own presence being what starts the sender in the first place. flush() now drains the live spool and then parked claims in the same run, oldest first, bounded. Expiry applies only after a genuine retry has failed, with the attempt count carried in the filename. A sender that gives up releases its lease rather than heartbeating on the way out, so the next run picks the batch up promptly instead of waiting a full stale window for a batch nobody is working on. A failing send stops the run, so one broken connection cannot burn every parked batch's attempt budget at once. Two existing tests asserted the old lifecycle and are updated in place, each with a comment saying what changed. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/telemetry.py | 168 ++++++++++++++++-- .../tests/test_spool_delivery.py | 164 +++++++++++++++++ .../antigravity-plugin/core/telemetry.py | 168 ++++++++++++++++-- .../claude-code-plugin/core/telemetry.py | 168 ++++++++++++++++-- .../tests/test_telemetry.py | 19 +- integrations/codex-plugin/core/telemetry.py | 168 ++++++++++++++++-- integrations/cursor-plugin/core/telemetry.py | 168 ++++++++++++++++-- integrations/kimi-plugin/core/telemetry.py | 168 ++++++++++++++++-- .../mem0-agent-plugin/core/telemetry.py | 168 ++++++++++++++++-- 9 files changed, 1241 insertions(+), 118 deletions(-) create mode 100644 integrations/agent-plugin-core/tests/test_spool_delivery.py diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 157db297d..55ee7c907 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -99,6 +99,11 @@ BATCH_SIZE = 100 SEND_TIMEOUT = 5 CLAIM_STALE_SECONDS = 120 CLAIM_EXPIRY_SECONDS = 7 * 24 * 60 * 60 +# A batch is only discarded once it has genuinely been retried this many times. +MAX_CLAIM_ATTEMPTS = 3 +# Parked claims drained per run, after the live spool. Bounded so a long backlog +# cannot turn one flush into an unbounded send loop. +MAX_PARKED_PER_RUN = 3 def is_enabled() -> bool: @@ -301,38 +306,139 @@ def spawn_flush() -> bool: return False +def _claim_name(attempt: int = 0) -> str: + """Claim filename. The attempt count rides in the name so the 7-day expiry + only ever discards a batch that was actually retried and failed.""" + return f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}-a{attempt}.sending" + + +def _claim_attempt(claim: Path) -> int: + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name + tail = stem.rsplit("-", 1)[-1] + if tail.startswith("a") and tail[1:].isdigit(): + return int(tail[1:]) + return 0 + + +def _touch(path: Path) -> None: + """Refresh mtime so a claim's age measures time since it was claimed. + + ``Path.replace`` is ``os.rename``, which preserves mtime — so a claim created + after a quiet minute inherited the spool's last-write time and looked + abandoned the instant it was made. A second sender would then take it over + while the first was still posting, and both would deliver the batch. + """ + try: + os.utime(path, None) + except OSError: + pass + + def _claim_spool() -> Path | None: """Rename the spool aside so exactly one sender owns each batch.""" directory = memory_core.data_dir() - claim = directory / f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}.sending" + claim = directory / _claim_name() spool = _spool_path() try: spool.replace(claim) + _touch(claim) return claim except OSError: pass + return _claim_parked(directory) + + +def _claim_parked(directory: Path) -> Path | None: + """Take the oldest abandoned claim, if any lease has actually expired. + + Kept separate from the live spool so flush() can drain both in one run. + Previously parked batches were only reachable when no spool existed at all, + and because sessions keep recording there usually was one — so a batch + parked by a failed send waited until the 7-day expiry deleted it unsent, + even though its own presence is what started the sender. + """ now = time.time() - for orphan in sorted(directory.glob("telemetry-*.sending")): + for orphan in sorted(directory.glob("telemetry-*.sending"), key=_safe_mtime): try: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS: + if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: try: orphan.unlink() except OSError: pass continue if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. continue + claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) + _touch(claim) return claim except OSError: continue return None +def _safe_mtime(path: Path) -> float: + try: + return path.stat().st_mtime + except OSError: + return 0.0 + + +def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: + """Persist the unsent remainder, atomically, and refresh the lease. + + Called after every successful batch. Two jobs: a retry resumes where the + send stopped instead of re-posting from the top, and the rewrite doubles as + the lease heartbeat, so a slow sender does not have its claim stolen + mid-flight. Interval is one batch, well inside CLAIM_STALE_SECONDS. + """ + if not remaining: + try: + claim.unlink() + except OSError: + pass + return True + temporary = claim.with_suffix(f".{os.getpid()}.partial") + try: + temporary.write_text( + "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), + encoding="utf-8", + ) + temporary.replace(claim) + _touch(claim) + return True + except OSError: + try: + temporary.unlink() + except OSError: + pass + return False + + +def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: + """Persist the remainder and drop the lease, because this sender has given up. + + Distinct from the per-batch heartbeat: heartbeating on the way out would + make an abandoned batch look actively owned for a further + CLAIM_STALE_SECONDS, delaying the retry for no reason. Ageing it past the + threshold lets the next flush pick it up immediately, while the attempt + count in the filename still bounds how many times that can happen. + """ + if not _rewrite_claim(claim, remaining): + return + try: + released = time.time() - CLAIM_STALE_SECONDS - 1 + os.utime(claim, (released, released)) + except OSError: + pass + + def _resolve_email(key: str) -> str: """Trade the API key for the account email so events join other Mem0 surfaces.""" url = os.environ.get("MEM0_API_URL", memory_core.DEFAULT_API_URL).rstrip("/") + "/v1/ping/" @@ -380,16 +486,40 @@ def resolve_distinct_id() -> tuple[str, str]: def flush() -> int: - """Drain claimed spools to PostHog and return the number of events sent.""" + """Drain the live spool, then any parked claims, and return events sent.""" if not is_enabled(): return 0 - claim = _claim_spool() + sent, delivered = _drain(_claim_spool()) + if not delivered: + # The network is failing. Retrying other batches now would only burn + # their attempt budget against the same broken connection. + return sent + + # Parked batches used to starve behind the live spool indefinitely. Bounded + # per run so a long backlog cannot turn one flush into an unbounded loop. + directory = memory_core.data_dir() + for _ in range(MAX_PARKED_PER_RUN): + parked = _claim_parked(directory) + if parked is None: + break + count, delivered = _drain(parked) + sent += count + if not delivered: + break + return sent + + +def _drain(claim: Path | None) -> tuple[int, bool]: + """Post one claimed batch file, recording progress after every batch. + + Returns (events sent, whether everything was delivered). + """ if claim is None: - return 0 + return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() except OSError: - return 0 + return 0, True events = [] for line in lines: try: @@ -403,7 +533,7 @@ def flush() -> int: claim.unlink() except OSError: pass - return 0 + return 0, True distinct_id, aliased_anonymous_id = resolve_distinct_id() if aliased_anonymous_id: @@ -422,10 +552,13 @@ def flush() -> int: sent = 0 for start in range(0, len(events), BATCH_SIZE): + chunk = events[start : start + BATCH_SIZE] batch = [ { "event": event["event"], "distinct_id": distinct_id, + # Carried through from record() so a resend can be collapsed. + "uuid": event.get("uuid"), "timestamp": event.get("timestamp"), "properties": { # Fallback only: events recorded by a build before source @@ -437,16 +570,19 @@ def flush() -> int: **(event.get("properties") or {}), }, } - for event in events[start : start + BATCH_SIZE] + for event in chunk ] if not _post({"api_key": POSTHOG_API_KEY, "batch": batch}, POSTHOG_BATCH_URL): - return sent - sent += len(batch) - try: - claim.unlink() - except OSError: - pass - return sent + # Keep only what has not been delivered, and release the lease. + # Previously the whole file was kept and the retry re-posted every + # batch, including the ones that had already arrived. + _release_claim(claim, events[start:]) + return sent, False + sent += len(chunk) + # Record progress and refresh the lease after each successful batch, so + # a crash repeats at most one batch instead of the entire file. + _rewrite_claim(claim, events[start + len(chunk) :]) + return sent, True def main() -> int: diff --git a/integrations/agent-plugin-core/tests/test_spool_delivery.py b/integrations/agent-plugin-core/tests/test_spool_delivery.py new file mode 100644 index 000000000..754307454 --- /dev/null +++ b/integrations/agent-plugin-core/tests/test_spool_delivery.py @@ -0,0 +1,164 @@ +"""Delivery semantics of the telemetry spool: no duplicates, no starvation. + +These run against a built host's core in-process (not a subprocess) because they +need to inject failures into ``_post``. The identity tests next door cover the +uninitialised-process case that needs a real interpreter. +""" + +from __future__ import annotations + +import importlib +import json +import os +import sys +import time +from pathlib import Path + +import pytest + +CORE_ROOT = Path(__file__).resolve().parents[1] +REPOSITORY_ROOT = CORE_ROOT.parents[1] +HOST_CORE = REPOSITORY_ROOT / "integrations" / "claude-code-plugin" / "core" + +pytestmark = pytest.mark.skipif(not HOST_CORE.exists(), reason="claude-code-plugin is not built") + + +@pytest.fixture() +def telemetry(tmp_path, monkeypatch): + monkeypatch.setenv("MEM0_CODE_DATA_DIR", str(tmp_path / "data")) + monkeypatch.syspath_prepend(str(HOST_CORE)) + for name in ("telemetry", "memory_core", "_harness_id"): + sys.modules.pop(name, None) + module = importlib.import_module("telemetry") + monkeypatch.setattr(module, "resolve_distinct_id", lambda: ("tester@example.com", "")) + yield module + for name in ("telemetry", "memory_core", "_harness_id"): + sys.modules.pop(name, None) + + +def _delivered(payloads): + return [event for payload in payloads if "batch" in payload for event in payload["batch"]] + + +def test_a_partial_failure_does_not_redeliver_what_already_arrived(telemetry): + """Defect 2a: flush kept the whole claim on failure and retried from the top. + + 150 events across two batches, the second failing, previously delivered 250. + """ + for index in range(150): + telemetry.record("search", index=index) + + sent: list[dict] = [] + calls = {"n": 0} + + def flaky(payload, url): + calls["n"] += 1 + if calls["n"] == 2: # second batch fails + return False + sent.append(payload) + return True + + telemetry._post = flaky + telemetry.flush() + + telemetry._post = lambda payload, url: sent.append(payload) or True + telemetry.flush() + + events = _delivered(sent) + assert len(events) == 150 + assert len({event["uuid"] for event in events}) == 150 + + +def test_a_fresh_claim_is_not_immediately_stealable(telemetry): + """Defect 2b: rename preserves mtime, so a claim inherited the spool's age. + + With the last write older than the stale threshold, a claim made now looked + abandoned the instant it existed and a second sender took it over. + """ + telemetry.record("search") + spool = telemetry._spool_path() + old = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(spool, (old, old)) + + first = telemetry._claim_spool() + assert first is not None + + # A second sender starting right now must find nothing to take. + assert telemetry._claim_parked(first.parent) is None + + +def test_a_parked_batch_is_drained_behind_the_live_spool(telemetry): + """Defect 6: parked claims were only reachable when no spool existed. + + Because sessions keep recording there usually was one, so a batch parked by + a failed send waited until the 7-day expiry deleted it unsent — even though + its own presence is what starts the sender. + """ + telemetry.record("parked") + telemetry._post = lambda payload, url: False + telemetry.flush() + + parked = list(telemetry.memory_core.data_dir().glob("telemetry-*.sending")) + assert len(parked) == 1 + old = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(parked[0], (old, old)) + + telemetry.record("fresh") + sent: list[dict] = [] + telemetry._post = lambda payload, url: sent.append(payload) or True + telemetry.flush() + + names = {event["event"] for event in _delivered(sent)} + assert names == {"code.parked", "code.fresh"} + + +def test_an_untried_batch_is_not_expired_by_age_alone(telemetry): + """Expiry should discard what failed, not what never got a turn.""" + telemetry.record("parked") + telemetry._post = lambda payload, url: False + telemetry.flush() + + parked = list(telemetry.memory_core.data_dir().glob("telemetry-*.sending")) + assert len(parked) == 1 + ancient = time.time() - (telemetry.CLAIM_EXPIRY_SECONDS + 60) + os.utime(parked[0], (ancient, ancient)) + + sent: list[dict] = [] + telemetry._post = lambda payload, url: sent.append(payload) or True + telemetry.flush() + + assert [event["event"] for event in _delivered(sent)] == ["code.parked"] + + +def test_progress_is_recorded_after_every_batch(telemetry): + """A crash repeats at most one batch, not the whole file.""" + for index in range(250): + telemetry.record("search", index=index) + + calls = {"n": 0} + + def die_after_two(payload, url): + calls["n"] += 1 + if calls["n"] > 2: + return False + return True + + telemetry._post = die_after_two + telemetry.flush() + + parked = list(telemetry.memory_core.data_dir().glob("telemetry-*.sending")) + assert len(parked) == 1 + remaining = parked[0].read_text(encoding="utf-8").strip().splitlines() + # Two batches of 100 landed; only the last 50 should still be pending. + assert len(remaining) == 50 + assert json.loads(remaining[0])["properties"]["index"] == 200 + + +def test_the_heartbeat_stays_well_inside_the_lease(telemetry): + """The claim rewrite doubles as the lease heartbeat. + + _post makes a single attempt with SEND_TIMEOUT and no retry, so a heartbeat + lands at least that often. If a retry loop is ever added to _post, this is + the assertion that catches a sender losing its claim mid-flight. + """ + assert telemetry.SEND_TIMEOUT * 4 < telemetry.CLAIM_STALE_SECONDS diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 157db297d..55ee7c907 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -99,6 +99,11 @@ BATCH_SIZE = 100 SEND_TIMEOUT = 5 CLAIM_STALE_SECONDS = 120 CLAIM_EXPIRY_SECONDS = 7 * 24 * 60 * 60 +# A batch is only discarded once it has genuinely been retried this many times. +MAX_CLAIM_ATTEMPTS = 3 +# Parked claims drained per run, after the live spool. Bounded so a long backlog +# cannot turn one flush into an unbounded send loop. +MAX_PARKED_PER_RUN = 3 def is_enabled() -> bool: @@ -301,38 +306,139 @@ def spawn_flush() -> bool: return False +def _claim_name(attempt: int = 0) -> str: + """Claim filename. The attempt count rides in the name so the 7-day expiry + only ever discards a batch that was actually retried and failed.""" + return f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}-a{attempt}.sending" + + +def _claim_attempt(claim: Path) -> int: + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name + tail = stem.rsplit("-", 1)[-1] + if tail.startswith("a") and tail[1:].isdigit(): + return int(tail[1:]) + return 0 + + +def _touch(path: Path) -> None: + """Refresh mtime so a claim's age measures time since it was claimed. + + ``Path.replace`` is ``os.rename``, which preserves mtime — so a claim created + after a quiet minute inherited the spool's last-write time and looked + abandoned the instant it was made. A second sender would then take it over + while the first was still posting, and both would deliver the batch. + """ + try: + os.utime(path, None) + except OSError: + pass + + def _claim_spool() -> Path | None: """Rename the spool aside so exactly one sender owns each batch.""" directory = memory_core.data_dir() - claim = directory / f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}.sending" + claim = directory / _claim_name() spool = _spool_path() try: spool.replace(claim) + _touch(claim) return claim except OSError: pass + return _claim_parked(directory) + + +def _claim_parked(directory: Path) -> Path | None: + """Take the oldest abandoned claim, if any lease has actually expired. + + Kept separate from the live spool so flush() can drain both in one run. + Previously parked batches were only reachable when no spool existed at all, + and because sessions keep recording there usually was one — so a batch + parked by a failed send waited until the 7-day expiry deleted it unsent, + even though its own presence is what started the sender. + """ now = time.time() - for orphan in sorted(directory.glob("telemetry-*.sending")): + for orphan in sorted(directory.glob("telemetry-*.sending"), key=_safe_mtime): try: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS: + if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: try: orphan.unlink() except OSError: pass continue if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. continue + claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) + _touch(claim) return claim except OSError: continue return None +def _safe_mtime(path: Path) -> float: + try: + return path.stat().st_mtime + except OSError: + return 0.0 + + +def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: + """Persist the unsent remainder, atomically, and refresh the lease. + + Called after every successful batch. Two jobs: a retry resumes where the + send stopped instead of re-posting from the top, and the rewrite doubles as + the lease heartbeat, so a slow sender does not have its claim stolen + mid-flight. Interval is one batch, well inside CLAIM_STALE_SECONDS. + """ + if not remaining: + try: + claim.unlink() + except OSError: + pass + return True + temporary = claim.with_suffix(f".{os.getpid()}.partial") + try: + temporary.write_text( + "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), + encoding="utf-8", + ) + temporary.replace(claim) + _touch(claim) + return True + except OSError: + try: + temporary.unlink() + except OSError: + pass + return False + + +def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: + """Persist the remainder and drop the lease, because this sender has given up. + + Distinct from the per-batch heartbeat: heartbeating on the way out would + make an abandoned batch look actively owned for a further + CLAIM_STALE_SECONDS, delaying the retry for no reason. Ageing it past the + threshold lets the next flush pick it up immediately, while the attempt + count in the filename still bounds how many times that can happen. + """ + if not _rewrite_claim(claim, remaining): + return + try: + released = time.time() - CLAIM_STALE_SECONDS - 1 + os.utime(claim, (released, released)) + except OSError: + pass + + def _resolve_email(key: str) -> str: """Trade the API key for the account email so events join other Mem0 surfaces.""" url = os.environ.get("MEM0_API_URL", memory_core.DEFAULT_API_URL).rstrip("/") + "/v1/ping/" @@ -380,16 +486,40 @@ def resolve_distinct_id() -> tuple[str, str]: def flush() -> int: - """Drain claimed spools to PostHog and return the number of events sent.""" + """Drain the live spool, then any parked claims, and return events sent.""" if not is_enabled(): return 0 - claim = _claim_spool() + sent, delivered = _drain(_claim_spool()) + if not delivered: + # The network is failing. Retrying other batches now would only burn + # their attempt budget against the same broken connection. + return sent + + # Parked batches used to starve behind the live spool indefinitely. Bounded + # per run so a long backlog cannot turn one flush into an unbounded loop. + directory = memory_core.data_dir() + for _ in range(MAX_PARKED_PER_RUN): + parked = _claim_parked(directory) + if parked is None: + break + count, delivered = _drain(parked) + sent += count + if not delivered: + break + return sent + + +def _drain(claim: Path | None) -> tuple[int, bool]: + """Post one claimed batch file, recording progress after every batch. + + Returns (events sent, whether everything was delivered). + """ if claim is None: - return 0 + return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() except OSError: - return 0 + return 0, True events = [] for line in lines: try: @@ -403,7 +533,7 @@ def flush() -> int: claim.unlink() except OSError: pass - return 0 + return 0, True distinct_id, aliased_anonymous_id = resolve_distinct_id() if aliased_anonymous_id: @@ -422,10 +552,13 @@ def flush() -> int: sent = 0 for start in range(0, len(events), BATCH_SIZE): + chunk = events[start : start + BATCH_SIZE] batch = [ { "event": event["event"], "distinct_id": distinct_id, + # Carried through from record() so a resend can be collapsed. + "uuid": event.get("uuid"), "timestamp": event.get("timestamp"), "properties": { # Fallback only: events recorded by a build before source @@ -437,16 +570,19 @@ def flush() -> int: **(event.get("properties") or {}), }, } - for event in events[start : start + BATCH_SIZE] + for event in chunk ] if not _post({"api_key": POSTHOG_API_KEY, "batch": batch}, POSTHOG_BATCH_URL): - return sent - sent += len(batch) - try: - claim.unlink() - except OSError: - pass - return sent + # Keep only what has not been delivered, and release the lease. + # Previously the whole file was kept and the retry re-posted every + # batch, including the ones that had already arrived. + _release_claim(claim, events[start:]) + return sent, False + sent += len(chunk) + # Record progress and refresh the lease after each successful batch, so + # a crash repeats at most one batch instead of the entire file. + _rewrite_claim(claim, events[start + len(chunk) :]) + return sent, True def main() -> int: diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 157db297d..55ee7c907 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -99,6 +99,11 @@ BATCH_SIZE = 100 SEND_TIMEOUT = 5 CLAIM_STALE_SECONDS = 120 CLAIM_EXPIRY_SECONDS = 7 * 24 * 60 * 60 +# A batch is only discarded once it has genuinely been retried this many times. +MAX_CLAIM_ATTEMPTS = 3 +# Parked claims drained per run, after the live spool. Bounded so a long backlog +# cannot turn one flush into an unbounded send loop. +MAX_PARKED_PER_RUN = 3 def is_enabled() -> bool: @@ -301,38 +306,139 @@ def spawn_flush() -> bool: return False +def _claim_name(attempt: int = 0) -> str: + """Claim filename. The attempt count rides in the name so the 7-day expiry + only ever discards a batch that was actually retried and failed.""" + return f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}-a{attempt}.sending" + + +def _claim_attempt(claim: Path) -> int: + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name + tail = stem.rsplit("-", 1)[-1] + if tail.startswith("a") and tail[1:].isdigit(): + return int(tail[1:]) + return 0 + + +def _touch(path: Path) -> None: + """Refresh mtime so a claim's age measures time since it was claimed. + + ``Path.replace`` is ``os.rename``, which preserves mtime — so a claim created + after a quiet minute inherited the spool's last-write time and looked + abandoned the instant it was made. A second sender would then take it over + while the first was still posting, and both would deliver the batch. + """ + try: + os.utime(path, None) + except OSError: + pass + + def _claim_spool() -> Path | None: """Rename the spool aside so exactly one sender owns each batch.""" directory = memory_core.data_dir() - claim = directory / f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}.sending" + claim = directory / _claim_name() spool = _spool_path() try: spool.replace(claim) + _touch(claim) return claim except OSError: pass + return _claim_parked(directory) + + +def _claim_parked(directory: Path) -> Path | None: + """Take the oldest abandoned claim, if any lease has actually expired. + + Kept separate from the live spool so flush() can drain both in one run. + Previously parked batches were only reachable when no spool existed at all, + and because sessions keep recording there usually was one — so a batch + parked by a failed send waited until the 7-day expiry deleted it unsent, + even though its own presence is what started the sender. + """ now = time.time() - for orphan in sorted(directory.glob("telemetry-*.sending")): + for orphan in sorted(directory.glob("telemetry-*.sending"), key=_safe_mtime): try: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS: + if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: try: orphan.unlink() except OSError: pass continue if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. continue + claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) + _touch(claim) return claim except OSError: continue return None +def _safe_mtime(path: Path) -> float: + try: + return path.stat().st_mtime + except OSError: + return 0.0 + + +def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: + """Persist the unsent remainder, atomically, and refresh the lease. + + Called after every successful batch. Two jobs: a retry resumes where the + send stopped instead of re-posting from the top, and the rewrite doubles as + the lease heartbeat, so a slow sender does not have its claim stolen + mid-flight. Interval is one batch, well inside CLAIM_STALE_SECONDS. + """ + if not remaining: + try: + claim.unlink() + except OSError: + pass + return True + temporary = claim.with_suffix(f".{os.getpid()}.partial") + try: + temporary.write_text( + "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), + encoding="utf-8", + ) + temporary.replace(claim) + _touch(claim) + return True + except OSError: + try: + temporary.unlink() + except OSError: + pass + return False + + +def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: + """Persist the remainder and drop the lease, because this sender has given up. + + Distinct from the per-batch heartbeat: heartbeating on the way out would + make an abandoned batch look actively owned for a further + CLAIM_STALE_SECONDS, delaying the retry for no reason. Ageing it past the + threshold lets the next flush pick it up immediately, while the attempt + count in the filename still bounds how many times that can happen. + """ + if not _rewrite_claim(claim, remaining): + return + try: + released = time.time() - CLAIM_STALE_SECONDS - 1 + os.utime(claim, (released, released)) + except OSError: + pass + + def _resolve_email(key: str) -> str: """Trade the API key for the account email so events join other Mem0 surfaces.""" url = os.environ.get("MEM0_API_URL", memory_core.DEFAULT_API_URL).rstrip("/") + "/v1/ping/" @@ -380,16 +486,40 @@ def resolve_distinct_id() -> tuple[str, str]: def flush() -> int: - """Drain claimed spools to PostHog and return the number of events sent.""" + """Drain the live spool, then any parked claims, and return events sent.""" if not is_enabled(): return 0 - claim = _claim_spool() + sent, delivered = _drain(_claim_spool()) + if not delivered: + # The network is failing. Retrying other batches now would only burn + # their attempt budget against the same broken connection. + return sent + + # Parked batches used to starve behind the live spool indefinitely. Bounded + # per run so a long backlog cannot turn one flush into an unbounded loop. + directory = memory_core.data_dir() + for _ in range(MAX_PARKED_PER_RUN): + parked = _claim_parked(directory) + if parked is None: + break + count, delivered = _drain(parked) + sent += count + if not delivered: + break + return sent + + +def _drain(claim: Path | None) -> tuple[int, bool]: + """Post one claimed batch file, recording progress after every batch. + + Returns (events sent, whether everything was delivered). + """ if claim is None: - return 0 + return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() except OSError: - return 0 + return 0, True events = [] for line in lines: try: @@ -403,7 +533,7 @@ def flush() -> int: claim.unlink() except OSError: pass - return 0 + return 0, True distinct_id, aliased_anonymous_id = resolve_distinct_id() if aliased_anonymous_id: @@ -422,10 +552,13 @@ def flush() -> int: sent = 0 for start in range(0, len(events), BATCH_SIZE): + chunk = events[start : start + BATCH_SIZE] batch = [ { "event": event["event"], "distinct_id": distinct_id, + # Carried through from record() so a resend can be collapsed. + "uuid": event.get("uuid"), "timestamp": event.get("timestamp"), "properties": { # Fallback only: events recorded by a build before source @@ -437,16 +570,19 @@ def flush() -> int: **(event.get("properties") or {}), }, } - for event in events[start : start + BATCH_SIZE] + for event in chunk ] if not _post({"api_key": POSTHOG_API_KEY, "batch": batch}, POSTHOG_BATCH_URL): - return sent - sent += len(batch) - try: - claim.unlink() - except OSError: - pass - return sent + # Keep only what has not been delivered, and release the lease. + # Previously the whole file was kept and the retry re-posted every + # batch, including the ones that had already arrived. + _release_claim(claim, events[start:]) + return sent, False + sent += len(chunk) + # Record progress and refresh the lease after each successful batch, so + # a crash repeats at most one batch instead of the entire file. + _rewrite_claim(claim, events[start + len(chunk) :]) + return sent, True def main() -> int: diff --git a/integrations/claude-code-plugin/tests/test_telemetry.py b/integrations/claude-code-plugin/tests/test_telemetry.py index 0ae280b19..580bc1100 100644 --- a/integrations/claude-code-plugin/tests/test_telemetry.py +++ b/integrations/claude-code-plugin/tests/test_telemetry.py @@ -1,6 +1,7 @@ from __future__ import annotations import json +import os import sys from pathlib import Path from unittest.mock import patch @@ -198,9 +199,11 @@ def test_a_stale_claim_is_reclaimed(isolated_env, monkeypatch): telemetry.record("search") orphan = telemetry._claim_spool() assert orphan is not None - monkeypatch.setattr( - telemetry.time, "time", lambda: orphan.stat().st_mtime + telemetry.CLAIM_STALE_SECONDS + 1 - ) + # Frozen rather than re-stat'd per call: flush() drains the live spool and + # then looks for parked claims in the same run, so by the second look this + # file no longer exists. + stale_now = orphan.stat().st_mtime + telemetry.CLAIM_STALE_SECONDS + 1 + monkeypatch.setattr(telemetry.time, "time", lambda: stale_now) with patch.object(telemetry, "_post", lambda payload, url: True): assert telemetry.flush() == 1 @@ -210,9 +213,13 @@ def test_an_expired_claim_is_dropped(isolated_env, monkeypatch): telemetry.record("search") orphan = telemetry._claim_spool() assert orphan is not None - monkeypatch.setattr( - telemetry.time, "time", lambda: orphan.stat().st_mtime + telemetry.CLAIM_EXPIRY_SECONDS + 1 - ) + expired_now = orphan.stat().st_mtime + telemetry.CLAIM_EXPIRY_SECONDS + 1 + monkeypatch.setattr(telemetry.time, "time", lambda: expired_now) + # Expiry now only discards a batch that was genuinely retried and failed, + # so age alone is not enough — age it past the attempt budget too. + retried = orphan.parent / orphan.name.replace("-a0.", f"-a{telemetry.MAX_CLAIM_ATTEMPTS}.") + orphan.replace(retried) + os.utime(retried, (expired_now, expired_now - telemetry.CLAIM_EXPIRY_SECONDS - 1)) assert telemetry._claim_spool() is None assert not list(memory_core.data_dir().glob("telemetry-*.sending")) diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 157db297d..55ee7c907 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -99,6 +99,11 @@ BATCH_SIZE = 100 SEND_TIMEOUT = 5 CLAIM_STALE_SECONDS = 120 CLAIM_EXPIRY_SECONDS = 7 * 24 * 60 * 60 +# A batch is only discarded once it has genuinely been retried this many times. +MAX_CLAIM_ATTEMPTS = 3 +# Parked claims drained per run, after the live spool. Bounded so a long backlog +# cannot turn one flush into an unbounded send loop. +MAX_PARKED_PER_RUN = 3 def is_enabled() -> bool: @@ -301,38 +306,139 @@ def spawn_flush() -> bool: return False +def _claim_name(attempt: int = 0) -> str: + """Claim filename. The attempt count rides in the name so the 7-day expiry + only ever discards a batch that was actually retried and failed.""" + return f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}-a{attempt}.sending" + + +def _claim_attempt(claim: Path) -> int: + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name + tail = stem.rsplit("-", 1)[-1] + if tail.startswith("a") and tail[1:].isdigit(): + return int(tail[1:]) + return 0 + + +def _touch(path: Path) -> None: + """Refresh mtime so a claim's age measures time since it was claimed. + + ``Path.replace`` is ``os.rename``, which preserves mtime — so a claim created + after a quiet minute inherited the spool's last-write time and looked + abandoned the instant it was made. A second sender would then take it over + while the first was still posting, and both would deliver the batch. + """ + try: + os.utime(path, None) + except OSError: + pass + + def _claim_spool() -> Path | None: """Rename the spool aside so exactly one sender owns each batch.""" directory = memory_core.data_dir() - claim = directory / f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}.sending" + claim = directory / _claim_name() spool = _spool_path() try: spool.replace(claim) + _touch(claim) return claim except OSError: pass + return _claim_parked(directory) + + +def _claim_parked(directory: Path) -> Path | None: + """Take the oldest abandoned claim, if any lease has actually expired. + + Kept separate from the live spool so flush() can drain both in one run. + Previously parked batches were only reachable when no spool existed at all, + and because sessions keep recording there usually was one — so a batch + parked by a failed send waited until the 7-day expiry deleted it unsent, + even though its own presence is what started the sender. + """ now = time.time() - for orphan in sorted(directory.glob("telemetry-*.sending")): + for orphan in sorted(directory.glob("telemetry-*.sending"), key=_safe_mtime): try: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS: + if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: try: orphan.unlink() except OSError: pass continue if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. continue + claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) + _touch(claim) return claim except OSError: continue return None +def _safe_mtime(path: Path) -> float: + try: + return path.stat().st_mtime + except OSError: + return 0.0 + + +def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: + """Persist the unsent remainder, atomically, and refresh the lease. + + Called after every successful batch. Two jobs: a retry resumes where the + send stopped instead of re-posting from the top, and the rewrite doubles as + the lease heartbeat, so a slow sender does not have its claim stolen + mid-flight. Interval is one batch, well inside CLAIM_STALE_SECONDS. + """ + if not remaining: + try: + claim.unlink() + except OSError: + pass + return True + temporary = claim.with_suffix(f".{os.getpid()}.partial") + try: + temporary.write_text( + "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), + encoding="utf-8", + ) + temporary.replace(claim) + _touch(claim) + return True + except OSError: + try: + temporary.unlink() + except OSError: + pass + return False + + +def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: + """Persist the remainder and drop the lease, because this sender has given up. + + Distinct from the per-batch heartbeat: heartbeating on the way out would + make an abandoned batch look actively owned for a further + CLAIM_STALE_SECONDS, delaying the retry for no reason. Ageing it past the + threshold lets the next flush pick it up immediately, while the attempt + count in the filename still bounds how many times that can happen. + """ + if not _rewrite_claim(claim, remaining): + return + try: + released = time.time() - CLAIM_STALE_SECONDS - 1 + os.utime(claim, (released, released)) + except OSError: + pass + + def _resolve_email(key: str) -> str: """Trade the API key for the account email so events join other Mem0 surfaces.""" url = os.environ.get("MEM0_API_URL", memory_core.DEFAULT_API_URL).rstrip("/") + "/v1/ping/" @@ -380,16 +486,40 @@ def resolve_distinct_id() -> tuple[str, str]: def flush() -> int: - """Drain claimed spools to PostHog and return the number of events sent.""" + """Drain the live spool, then any parked claims, and return events sent.""" if not is_enabled(): return 0 - claim = _claim_spool() + sent, delivered = _drain(_claim_spool()) + if not delivered: + # The network is failing. Retrying other batches now would only burn + # their attempt budget against the same broken connection. + return sent + + # Parked batches used to starve behind the live spool indefinitely. Bounded + # per run so a long backlog cannot turn one flush into an unbounded loop. + directory = memory_core.data_dir() + for _ in range(MAX_PARKED_PER_RUN): + parked = _claim_parked(directory) + if parked is None: + break + count, delivered = _drain(parked) + sent += count + if not delivered: + break + return sent + + +def _drain(claim: Path | None) -> tuple[int, bool]: + """Post one claimed batch file, recording progress after every batch. + + Returns (events sent, whether everything was delivered). + """ if claim is None: - return 0 + return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() except OSError: - return 0 + return 0, True events = [] for line in lines: try: @@ -403,7 +533,7 @@ def flush() -> int: claim.unlink() except OSError: pass - return 0 + return 0, True distinct_id, aliased_anonymous_id = resolve_distinct_id() if aliased_anonymous_id: @@ -422,10 +552,13 @@ def flush() -> int: sent = 0 for start in range(0, len(events), BATCH_SIZE): + chunk = events[start : start + BATCH_SIZE] batch = [ { "event": event["event"], "distinct_id": distinct_id, + # Carried through from record() so a resend can be collapsed. + "uuid": event.get("uuid"), "timestamp": event.get("timestamp"), "properties": { # Fallback only: events recorded by a build before source @@ -437,16 +570,19 @@ def flush() -> int: **(event.get("properties") or {}), }, } - for event in events[start : start + BATCH_SIZE] + for event in chunk ] if not _post({"api_key": POSTHOG_API_KEY, "batch": batch}, POSTHOG_BATCH_URL): - return sent - sent += len(batch) - try: - claim.unlink() - except OSError: - pass - return sent + # Keep only what has not been delivered, and release the lease. + # Previously the whole file was kept and the retry re-posted every + # batch, including the ones that had already arrived. + _release_claim(claim, events[start:]) + return sent, False + sent += len(chunk) + # Record progress and refresh the lease after each successful batch, so + # a crash repeats at most one batch instead of the entire file. + _rewrite_claim(claim, events[start + len(chunk) :]) + return sent, True def main() -> int: diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 157db297d..55ee7c907 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -99,6 +99,11 @@ BATCH_SIZE = 100 SEND_TIMEOUT = 5 CLAIM_STALE_SECONDS = 120 CLAIM_EXPIRY_SECONDS = 7 * 24 * 60 * 60 +# A batch is only discarded once it has genuinely been retried this many times. +MAX_CLAIM_ATTEMPTS = 3 +# Parked claims drained per run, after the live spool. Bounded so a long backlog +# cannot turn one flush into an unbounded send loop. +MAX_PARKED_PER_RUN = 3 def is_enabled() -> bool: @@ -301,38 +306,139 @@ def spawn_flush() -> bool: return False +def _claim_name(attempt: int = 0) -> str: + """Claim filename. The attempt count rides in the name so the 7-day expiry + only ever discards a batch that was actually retried and failed.""" + return f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}-a{attempt}.sending" + + +def _claim_attempt(claim: Path) -> int: + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name + tail = stem.rsplit("-", 1)[-1] + if tail.startswith("a") and tail[1:].isdigit(): + return int(tail[1:]) + return 0 + + +def _touch(path: Path) -> None: + """Refresh mtime so a claim's age measures time since it was claimed. + + ``Path.replace`` is ``os.rename``, which preserves mtime — so a claim created + after a quiet minute inherited the spool's last-write time and looked + abandoned the instant it was made. A second sender would then take it over + while the first was still posting, and both would deliver the batch. + """ + try: + os.utime(path, None) + except OSError: + pass + + def _claim_spool() -> Path | None: """Rename the spool aside so exactly one sender owns each batch.""" directory = memory_core.data_dir() - claim = directory / f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}.sending" + claim = directory / _claim_name() spool = _spool_path() try: spool.replace(claim) + _touch(claim) return claim except OSError: pass + return _claim_parked(directory) + + +def _claim_parked(directory: Path) -> Path | None: + """Take the oldest abandoned claim, if any lease has actually expired. + + Kept separate from the live spool so flush() can drain both in one run. + Previously parked batches were only reachable when no spool existed at all, + and because sessions keep recording there usually was one — so a batch + parked by a failed send waited until the 7-day expiry deleted it unsent, + even though its own presence is what started the sender. + """ now = time.time() - for orphan in sorted(directory.glob("telemetry-*.sending")): + for orphan in sorted(directory.glob("telemetry-*.sending"), key=_safe_mtime): try: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS: + if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: try: orphan.unlink() except OSError: pass continue if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. continue + claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) + _touch(claim) return claim except OSError: continue return None +def _safe_mtime(path: Path) -> float: + try: + return path.stat().st_mtime + except OSError: + return 0.0 + + +def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: + """Persist the unsent remainder, atomically, and refresh the lease. + + Called after every successful batch. Two jobs: a retry resumes where the + send stopped instead of re-posting from the top, and the rewrite doubles as + the lease heartbeat, so a slow sender does not have its claim stolen + mid-flight. Interval is one batch, well inside CLAIM_STALE_SECONDS. + """ + if not remaining: + try: + claim.unlink() + except OSError: + pass + return True + temporary = claim.with_suffix(f".{os.getpid()}.partial") + try: + temporary.write_text( + "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), + encoding="utf-8", + ) + temporary.replace(claim) + _touch(claim) + return True + except OSError: + try: + temporary.unlink() + except OSError: + pass + return False + + +def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: + """Persist the remainder and drop the lease, because this sender has given up. + + Distinct from the per-batch heartbeat: heartbeating on the way out would + make an abandoned batch look actively owned for a further + CLAIM_STALE_SECONDS, delaying the retry for no reason. Ageing it past the + threshold lets the next flush pick it up immediately, while the attempt + count in the filename still bounds how many times that can happen. + """ + if not _rewrite_claim(claim, remaining): + return + try: + released = time.time() - CLAIM_STALE_SECONDS - 1 + os.utime(claim, (released, released)) + except OSError: + pass + + def _resolve_email(key: str) -> str: """Trade the API key for the account email so events join other Mem0 surfaces.""" url = os.environ.get("MEM0_API_URL", memory_core.DEFAULT_API_URL).rstrip("/") + "/v1/ping/" @@ -380,16 +486,40 @@ def resolve_distinct_id() -> tuple[str, str]: def flush() -> int: - """Drain claimed spools to PostHog and return the number of events sent.""" + """Drain the live spool, then any parked claims, and return events sent.""" if not is_enabled(): return 0 - claim = _claim_spool() + sent, delivered = _drain(_claim_spool()) + if not delivered: + # The network is failing. Retrying other batches now would only burn + # their attempt budget against the same broken connection. + return sent + + # Parked batches used to starve behind the live spool indefinitely. Bounded + # per run so a long backlog cannot turn one flush into an unbounded loop. + directory = memory_core.data_dir() + for _ in range(MAX_PARKED_PER_RUN): + parked = _claim_parked(directory) + if parked is None: + break + count, delivered = _drain(parked) + sent += count + if not delivered: + break + return sent + + +def _drain(claim: Path | None) -> tuple[int, bool]: + """Post one claimed batch file, recording progress after every batch. + + Returns (events sent, whether everything was delivered). + """ if claim is None: - return 0 + return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() except OSError: - return 0 + return 0, True events = [] for line in lines: try: @@ -403,7 +533,7 @@ def flush() -> int: claim.unlink() except OSError: pass - return 0 + return 0, True distinct_id, aliased_anonymous_id = resolve_distinct_id() if aliased_anonymous_id: @@ -422,10 +552,13 @@ def flush() -> int: sent = 0 for start in range(0, len(events), BATCH_SIZE): + chunk = events[start : start + BATCH_SIZE] batch = [ { "event": event["event"], "distinct_id": distinct_id, + # Carried through from record() so a resend can be collapsed. + "uuid": event.get("uuid"), "timestamp": event.get("timestamp"), "properties": { # Fallback only: events recorded by a build before source @@ -437,16 +570,19 @@ def flush() -> int: **(event.get("properties") or {}), }, } - for event in events[start : start + BATCH_SIZE] + for event in chunk ] if not _post({"api_key": POSTHOG_API_KEY, "batch": batch}, POSTHOG_BATCH_URL): - return sent - sent += len(batch) - try: - claim.unlink() - except OSError: - pass - return sent + # Keep only what has not been delivered, and release the lease. + # Previously the whole file was kept and the retry re-posted every + # batch, including the ones that had already arrived. + _release_claim(claim, events[start:]) + return sent, False + sent += len(chunk) + # Record progress and refresh the lease after each successful batch, so + # a crash repeats at most one batch instead of the entire file. + _rewrite_claim(claim, events[start + len(chunk) :]) + return sent, True def main() -> int: diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 157db297d..55ee7c907 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -99,6 +99,11 @@ BATCH_SIZE = 100 SEND_TIMEOUT = 5 CLAIM_STALE_SECONDS = 120 CLAIM_EXPIRY_SECONDS = 7 * 24 * 60 * 60 +# A batch is only discarded once it has genuinely been retried this many times. +MAX_CLAIM_ATTEMPTS = 3 +# Parked claims drained per run, after the live spool. Bounded so a long backlog +# cannot turn one flush into an unbounded send loop. +MAX_PARKED_PER_RUN = 3 def is_enabled() -> bool: @@ -301,38 +306,139 @@ def spawn_flush() -> bool: return False +def _claim_name(attempt: int = 0) -> str: + """Claim filename. The attempt count rides in the name so the 7-day expiry + only ever discards a batch that was actually retried and failed.""" + return f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}-a{attempt}.sending" + + +def _claim_attempt(claim: Path) -> int: + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name + tail = stem.rsplit("-", 1)[-1] + if tail.startswith("a") and tail[1:].isdigit(): + return int(tail[1:]) + return 0 + + +def _touch(path: Path) -> None: + """Refresh mtime so a claim's age measures time since it was claimed. + + ``Path.replace`` is ``os.rename``, which preserves mtime — so a claim created + after a quiet minute inherited the spool's last-write time and looked + abandoned the instant it was made. A second sender would then take it over + while the first was still posting, and both would deliver the batch. + """ + try: + os.utime(path, None) + except OSError: + pass + + def _claim_spool() -> Path | None: """Rename the spool aside so exactly one sender owns each batch.""" directory = memory_core.data_dir() - claim = directory / f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}.sending" + claim = directory / _claim_name() spool = _spool_path() try: spool.replace(claim) + _touch(claim) return claim except OSError: pass + return _claim_parked(directory) + + +def _claim_parked(directory: Path) -> Path | None: + """Take the oldest abandoned claim, if any lease has actually expired. + + Kept separate from the live spool so flush() can drain both in one run. + Previously parked batches were only reachable when no spool existed at all, + and because sessions keep recording there usually was one — so a batch + parked by a failed send waited until the 7-day expiry deleted it unsent, + even though its own presence is what started the sender. + """ now = time.time() - for orphan in sorted(directory.glob("telemetry-*.sending")): + for orphan in sorted(directory.glob("telemetry-*.sending"), key=_safe_mtime): try: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS: + if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: try: orphan.unlink() except OSError: pass continue if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. continue + claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) + _touch(claim) return claim except OSError: continue return None +def _safe_mtime(path: Path) -> float: + try: + return path.stat().st_mtime + except OSError: + return 0.0 + + +def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: + """Persist the unsent remainder, atomically, and refresh the lease. + + Called after every successful batch. Two jobs: a retry resumes where the + send stopped instead of re-posting from the top, and the rewrite doubles as + the lease heartbeat, so a slow sender does not have its claim stolen + mid-flight. Interval is one batch, well inside CLAIM_STALE_SECONDS. + """ + if not remaining: + try: + claim.unlink() + except OSError: + pass + return True + temporary = claim.with_suffix(f".{os.getpid()}.partial") + try: + temporary.write_text( + "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), + encoding="utf-8", + ) + temporary.replace(claim) + _touch(claim) + return True + except OSError: + try: + temporary.unlink() + except OSError: + pass + return False + + +def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: + """Persist the remainder and drop the lease, because this sender has given up. + + Distinct from the per-batch heartbeat: heartbeating on the way out would + make an abandoned batch look actively owned for a further + CLAIM_STALE_SECONDS, delaying the retry for no reason. Ageing it past the + threshold lets the next flush pick it up immediately, while the attempt + count in the filename still bounds how many times that can happen. + """ + if not _rewrite_claim(claim, remaining): + return + try: + released = time.time() - CLAIM_STALE_SECONDS - 1 + os.utime(claim, (released, released)) + except OSError: + pass + + def _resolve_email(key: str) -> str: """Trade the API key for the account email so events join other Mem0 surfaces.""" url = os.environ.get("MEM0_API_URL", memory_core.DEFAULT_API_URL).rstrip("/") + "/v1/ping/" @@ -380,16 +486,40 @@ def resolve_distinct_id() -> tuple[str, str]: def flush() -> int: - """Drain claimed spools to PostHog and return the number of events sent.""" + """Drain the live spool, then any parked claims, and return events sent.""" if not is_enabled(): return 0 - claim = _claim_spool() + sent, delivered = _drain(_claim_spool()) + if not delivered: + # The network is failing. Retrying other batches now would only burn + # their attempt budget against the same broken connection. + return sent + + # Parked batches used to starve behind the live spool indefinitely. Bounded + # per run so a long backlog cannot turn one flush into an unbounded loop. + directory = memory_core.data_dir() + for _ in range(MAX_PARKED_PER_RUN): + parked = _claim_parked(directory) + if parked is None: + break + count, delivered = _drain(parked) + sent += count + if not delivered: + break + return sent + + +def _drain(claim: Path | None) -> tuple[int, bool]: + """Post one claimed batch file, recording progress after every batch. + + Returns (events sent, whether everything was delivered). + """ if claim is None: - return 0 + return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() except OSError: - return 0 + return 0, True events = [] for line in lines: try: @@ -403,7 +533,7 @@ def flush() -> int: claim.unlink() except OSError: pass - return 0 + return 0, True distinct_id, aliased_anonymous_id = resolve_distinct_id() if aliased_anonymous_id: @@ -422,10 +552,13 @@ def flush() -> int: sent = 0 for start in range(0, len(events), BATCH_SIZE): + chunk = events[start : start + BATCH_SIZE] batch = [ { "event": event["event"], "distinct_id": distinct_id, + # Carried through from record() so a resend can be collapsed. + "uuid": event.get("uuid"), "timestamp": event.get("timestamp"), "properties": { # Fallback only: events recorded by a build before source @@ -437,16 +570,19 @@ def flush() -> int: **(event.get("properties") or {}), }, } - for event in events[start : start + BATCH_SIZE] + for event in chunk ] if not _post({"api_key": POSTHOG_API_KEY, "batch": batch}, POSTHOG_BATCH_URL): - return sent - sent += len(batch) - try: - claim.unlink() - except OSError: - pass - return sent + # Keep only what has not been delivered, and release the lease. + # Previously the whole file was kept and the retry re-posted every + # batch, including the ones that had already arrived. + _release_claim(claim, events[start:]) + return sent, False + sent += len(chunk) + # Record progress and refresh the lease after each successful batch, so + # a crash repeats at most one batch instead of the entire file. + _rewrite_claim(claim, events[start + len(chunk) :]) + return sent, True def main() -> int: diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 157db297d..55ee7c907 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -99,6 +99,11 @@ BATCH_SIZE = 100 SEND_TIMEOUT = 5 CLAIM_STALE_SECONDS = 120 CLAIM_EXPIRY_SECONDS = 7 * 24 * 60 * 60 +# A batch is only discarded once it has genuinely been retried this many times. +MAX_CLAIM_ATTEMPTS = 3 +# Parked claims drained per run, after the live spool. Bounded so a long backlog +# cannot turn one flush into an unbounded send loop. +MAX_PARKED_PER_RUN = 3 def is_enabled() -> bool: @@ -301,38 +306,139 @@ def spawn_flush() -> bool: return False +def _claim_name(attempt: int = 0) -> str: + """Claim filename. The attempt count rides in the name so the 7-day expiry + only ever discards a batch that was actually retried and failed.""" + return f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}-a{attempt}.sending" + + +def _claim_attempt(claim: Path) -> int: + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name + tail = stem.rsplit("-", 1)[-1] + if tail.startswith("a") and tail[1:].isdigit(): + return int(tail[1:]) + return 0 + + +def _touch(path: Path) -> None: + """Refresh mtime so a claim's age measures time since it was claimed. + + ``Path.replace`` is ``os.rename``, which preserves mtime — so a claim created + after a quiet minute inherited the spool's last-write time and looked + abandoned the instant it was made. A second sender would then take it over + while the first was still posting, and both would deliver the batch. + """ + try: + os.utime(path, None) + except OSError: + pass + + def _claim_spool() -> Path | None: """Rename the spool aside so exactly one sender owns each batch.""" directory = memory_core.data_dir() - claim = directory / f"telemetry-{os.getpid()}-{uuid.uuid4().hex[:8]}.sending" + claim = directory / _claim_name() spool = _spool_path() try: spool.replace(claim) + _touch(claim) return claim except OSError: pass + return _claim_parked(directory) + + +def _claim_parked(directory: Path) -> Path | None: + """Take the oldest abandoned claim, if any lease has actually expired. + + Kept separate from the live spool so flush() can drain both in one run. + Previously parked batches were only reachable when no spool existed at all, + and because sessions keep recording there usually was one — so a batch + parked by a failed send waited until the 7-day expiry deleted it unsent, + even though its own presence is what started the sender. + """ now = time.time() - for orphan in sorted(directory.glob("telemetry-*.sending")): + for orphan in sorted(directory.glob("telemetry-*.sending"), key=_safe_mtime): try: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS: + if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: try: orphan.unlink() except OSError: pass continue if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. continue + claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) + _touch(claim) return claim except OSError: continue return None +def _safe_mtime(path: Path) -> float: + try: + return path.stat().st_mtime + except OSError: + return 0.0 + + +def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: + """Persist the unsent remainder, atomically, and refresh the lease. + + Called after every successful batch. Two jobs: a retry resumes where the + send stopped instead of re-posting from the top, and the rewrite doubles as + the lease heartbeat, so a slow sender does not have its claim stolen + mid-flight. Interval is one batch, well inside CLAIM_STALE_SECONDS. + """ + if not remaining: + try: + claim.unlink() + except OSError: + pass + return True + temporary = claim.with_suffix(f".{os.getpid()}.partial") + try: + temporary.write_text( + "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), + encoding="utf-8", + ) + temporary.replace(claim) + _touch(claim) + return True + except OSError: + try: + temporary.unlink() + except OSError: + pass + return False + + +def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: + """Persist the remainder and drop the lease, because this sender has given up. + + Distinct from the per-batch heartbeat: heartbeating on the way out would + make an abandoned batch look actively owned for a further + CLAIM_STALE_SECONDS, delaying the retry for no reason. Ageing it past the + threshold lets the next flush pick it up immediately, while the attempt + count in the filename still bounds how many times that can happen. + """ + if not _rewrite_claim(claim, remaining): + return + try: + released = time.time() - CLAIM_STALE_SECONDS - 1 + os.utime(claim, (released, released)) + except OSError: + pass + + def _resolve_email(key: str) -> str: """Trade the API key for the account email so events join other Mem0 surfaces.""" url = os.environ.get("MEM0_API_URL", memory_core.DEFAULT_API_URL).rstrip("/") + "/v1/ping/" @@ -380,16 +486,40 @@ def resolve_distinct_id() -> tuple[str, str]: def flush() -> int: - """Drain claimed spools to PostHog and return the number of events sent.""" + """Drain the live spool, then any parked claims, and return events sent.""" if not is_enabled(): return 0 - claim = _claim_spool() + sent, delivered = _drain(_claim_spool()) + if not delivered: + # The network is failing. Retrying other batches now would only burn + # their attempt budget against the same broken connection. + return sent + + # Parked batches used to starve behind the live spool indefinitely. Bounded + # per run so a long backlog cannot turn one flush into an unbounded loop. + directory = memory_core.data_dir() + for _ in range(MAX_PARKED_PER_RUN): + parked = _claim_parked(directory) + if parked is None: + break + count, delivered = _drain(parked) + sent += count + if not delivered: + break + return sent + + +def _drain(claim: Path | None) -> tuple[int, bool]: + """Post one claimed batch file, recording progress after every batch. + + Returns (events sent, whether everything was delivered). + """ if claim is None: - return 0 + return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() except OSError: - return 0 + return 0, True events = [] for line in lines: try: @@ -403,7 +533,7 @@ def flush() -> int: claim.unlink() except OSError: pass - return 0 + return 0, True distinct_id, aliased_anonymous_id = resolve_distinct_id() if aliased_anonymous_id: @@ -422,10 +552,13 @@ def flush() -> int: sent = 0 for start in range(0, len(events), BATCH_SIZE): + chunk = events[start : start + BATCH_SIZE] batch = [ { "event": event["event"], "distinct_id": distinct_id, + # Carried through from record() so a resend can be collapsed. + "uuid": event.get("uuid"), "timestamp": event.get("timestamp"), "properties": { # Fallback only: events recorded by a build before source @@ -437,16 +570,19 @@ def flush() -> int: **(event.get("properties") or {}), }, } - for event in events[start : start + BATCH_SIZE] + for event in chunk ] if not _post({"api_key": POSTHOG_API_KEY, "batch": batch}, POSTHOG_BATCH_URL): - return sent - sent += len(batch) - try: - claim.unlink() - except OSError: - pass - return sent + # Keep only what has not been delivered, and release the lease. + # Previously the whole file was kept and the retry re-posted every + # batch, including the ones that had already arrived. + _release_claim(claim, events[start:]) + return sent, False + sent += len(chunk) + # Record progress and refresh the lease after each successful batch, so + # a crash repeats at most one batch instead of the entire file. + _rewrite_claim(claim, events[start + len(chunk) :]) + return sent, True def main() -> int: From 0d2b20c03d8866d1e3da198951660f1507989988 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:18:38 +0530 Subject: [PATCH 04/30] fix(plugins): count installs once, and re-resolve the email when the key changes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit code.install counted upgrades and repeat sessions. Session start records install whenever is_first_run() is true, and that only checked whether telemetry-identity.json exists. Recording install does not create that file — only the first successful flush does. So install fired for every 0.2.x user on their first 0.3.x session (0.2.x never wrote the file, and the data directory survives the upgrade), again for any session starting before that first flush finished, and — this is the part that makes it unbounded rather than a race — on every single session, forever, for anyone whose flush never succeeds. An offline or firewalled user reported a new install every time they opened an editor, which is exactly the population hardest to see in the data. A dedicated install-state.json is now claimed with O_CREAT|O_EXCL at the moment install is recorded, so two sessions starting together cannot both win, and the marker is not coupled to identity. Deliberately not the identity file: writing that from a recording process would race the sender, which writes it during resolve_distinct_id, and overloading it is what caused this. Upgrade detection keys on the data directory already having content. A fresh install has an empty one; anything else predates this session. That is a firmer predicate than looking for 0.2.x's venv/ and requirements.txt, which is a guess about files another part of the plugin may or may not have written and only ever works for this one upgrade. The version is stored in the marker so later changes record code.upgrade with a real from_version. A cached email outlived an API key change. resolve_distinct_id kept the first email it resolved and never looked again, so switching to a key from another account kept attributing events to the previous one. It now stores a fingerprint of the key the email came from and re-resolves when the current key differs, and falls back to the anonymous id when no key is configured rather than continuing to attribute to an account it cannot verify. The dangerous part is the alias. resolve_distinct_id's second return value becomes a PostHog $identify with $anon_distinct_id, and aliasing one account email to another merges two real person profiles irreversibly. The re-resolve path returns no alias; aliasing runs anonymous to email only, and never email to email. One existing test asserted that is_first_run flips when the identity file is written, which is the defect itself. Rewritten, along with coverage for atomic claiming, upgrade detection and version changes. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/hook_runner.py | 13 +- .../agent-plugin-core/python/telemetry.py | 125 ++++++++++++++++-- .../antigravity-plugin/core/hook_runner.py | 13 +- .../antigravity-plugin/core/telemetry.py | 125 ++++++++++++++++-- .../claude-code-plugin/core/hook_runner.py | 13 +- .../claude-code-plugin/core/telemetry.py | 125 ++++++++++++++++-- .../tests/test_telemetry.py | 37 +++++- integrations/codex-plugin/core/hook_runner.py | 13 +- integrations/codex-plugin/core/telemetry.py | 125 ++++++++++++++++-- .../cursor-plugin/core/hook_runner.py | 13 +- integrations/cursor-plugin/core/telemetry.py | 125 ++++++++++++++++-- integrations/kimi-plugin/core/hook_runner.py | 13 +- integrations/kimi-plugin/core/telemetry.py | 125 ++++++++++++++++-- .../mem0-agent-plugin/core/telemetry.py | 125 ++++++++++++++++-- 14 files changed, 899 insertions(+), 91 deletions(-) diff --git a/integrations/agent-plugin-core/python/hook_runner.py b/integrations/agent-plugin-core/python/hook_runner.py index 2a2adb557..559702102 100644 --- a/integrations/agent-plugin-core/python/hook_runner.py +++ b/integrations/agent-plugin-core/python/hook_runner.py @@ -305,8 +305,19 @@ def run( return 0 if args.action == "session-start": - if telemetry.is_first_run(): + # Claims the marker atomically and says which event to record, so a + # second session starting alongside this one cannot record it too. + first_event = telemetry.claim_install() + if first_event == "install": telemetry.record("install") + elif first_event == "upgrade": + # First run after a build that never wrote the marker; the + # predecessor version was never recorded anywhere. + telemetry.record("upgrade", from_version="pre-0.3") + else: + previous = telemetry.claim_version_change() + if previous: + telemetry.record("upgrade", from_version=previous) recovered = recover_pending_handoffs() record_session_start(store, hook_input) if recovered: diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 55ee7c907..d7933bfbc 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _install_state_path() -> Path: + return memory_core.data_dir() / "install-state.json" + + def is_first_run() -> bool: - """Whether this machine has never recorded a plugin event before.""" - return not _identity_path().exists() + """Whether install has never been recorded on this machine. + + Deliberately NOT the identity file. That file is only written by a + successful flush, so an offline or firewalled user recorded code.install on + every single session, forever — and every 0.2.x user recorded one on their + first 0.3.x session because 0.2.x never wrote it at all. + """ + return not _install_state_path().exists() + + +def claim_install() -> str | None: + """Claim the one install/upgrade record for this machine, atomically. + + Returns the event to record ("install" or "upgrade"), or None if another + session already claimed it. O_CREAT|O_EXCL so two sessions starting together + cannot both win. + """ + path = _install_state_path() + # A fresh install has an empty data directory. Anything already there — + # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read + # before the marker is created, since creating it would itself be content. + upgrading = _data_dir_has_content() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + except FileExistsError: + return None + except OSError: + return None + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + json.dump( + { + "plugin_version": memory_core.PLUGIN_VERSION, + "installed_at": memory_core.utc_now(), + "upgraded": upgrading, + }, + stream, + ) + except OSError: + pass + return "upgrade" if upgrading else "install" + + +def _data_dir_has_content() -> bool: + """Whether anything predates this session in the plugin data directory.""" + try: + for entry in memory_core.data_dir().iterdir(): + if entry.name != "install-state.json": + return True + except OSError: + pass + return False + + +def claim_version_change() -> str | None: + """Return the previously recorded version if it differs, updating the marker. + + Only meaningful once the marker exists — the first transition into 0.3.x has + no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting + the marker means the next session sees no change and records nothing. + """ + path = _install_state_path() + try: + state = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return None + if not isinstance(state, dict): + return None + previous = str(state.get("plugin_version") or "") + if not previous or previous == memory_core.PLUGIN_VERSION: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION + state["upgraded_at"] = memory_core.utc_now() + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text(json.dumps(state), encoding="utf-8") + temporary.replace(path) + except OSError: + return None + return previous def record( @@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool: def resolve_distinct_id() -> tuple[str, str]: - """Return the PostHog distinct id and the anonymous id it replaced, if any.""" + """Return the PostHog distinct id and the anonymous id it replaced, if any. + + The second value becomes a PostHog $identify alias. It is ONLY ever an + anonymous id: aliasing one account email to another merges two real person + profiles and cannot be undone, so a key that now belongs to a different + account re-resolves with no alias. + """ identity = _read_identity() - email = identity.get("email", "") - if email: - return email, "" key = memory_core.api_key() + fingerprint = _digest(key) if key else "" + email = identity.get("email", "") + + if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: + return email, "" + if not key: + # No key to verify the account with; do not keep attributing to it. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + _write_identity(identity) return anonymous_id(identity), "" - email = _resolve_email(key) - if not email: - return anonymous_id(identity), "" - previous = identity.get("anonymous_id", "") - identity["email"] = email + + resolved = _resolve_email(key) + if not resolved: + return (email, "") if email else (anonymous_id(identity), "") + + # Alias only when going anonymous -> email for the first time. + previous = "" if email else identity.get("anonymous_id", "") + identity["email"] = resolved + identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, previous + return resolved, previous def flush() -> int: diff --git a/integrations/antigravity-plugin/core/hook_runner.py b/integrations/antigravity-plugin/core/hook_runner.py index 2a2adb557..559702102 100644 --- a/integrations/antigravity-plugin/core/hook_runner.py +++ b/integrations/antigravity-plugin/core/hook_runner.py @@ -305,8 +305,19 @@ def run( return 0 if args.action == "session-start": - if telemetry.is_first_run(): + # Claims the marker atomically and says which event to record, so a + # second session starting alongside this one cannot record it too. + first_event = telemetry.claim_install() + if first_event == "install": telemetry.record("install") + elif first_event == "upgrade": + # First run after a build that never wrote the marker; the + # predecessor version was never recorded anywhere. + telemetry.record("upgrade", from_version="pre-0.3") + else: + previous = telemetry.claim_version_change() + if previous: + telemetry.record("upgrade", from_version=previous) recovered = recover_pending_handoffs() record_session_start(store, hook_input) if recovered: diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 55ee7c907..d7933bfbc 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _install_state_path() -> Path: + return memory_core.data_dir() / "install-state.json" + + def is_first_run() -> bool: - """Whether this machine has never recorded a plugin event before.""" - return not _identity_path().exists() + """Whether install has never been recorded on this machine. + + Deliberately NOT the identity file. That file is only written by a + successful flush, so an offline or firewalled user recorded code.install on + every single session, forever — and every 0.2.x user recorded one on their + first 0.3.x session because 0.2.x never wrote it at all. + """ + return not _install_state_path().exists() + + +def claim_install() -> str | None: + """Claim the one install/upgrade record for this machine, atomically. + + Returns the event to record ("install" or "upgrade"), or None if another + session already claimed it. O_CREAT|O_EXCL so two sessions starting together + cannot both win. + """ + path = _install_state_path() + # A fresh install has an empty data directory. Anything already there — + # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read + # before the marker is created, since creating it would itself be content. + upgrading = _data_dir_has_content() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + except FileExistsError: + return None + except OSError: + return None + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + json.dump( + { + "plugin_version": memory_core.PLUGIN_VERSION, + "installed_at": memory_core.utc_now(), + "upgraded": upgrading, + }, + stream, + ) + except OSError: + pass + return "upgrade" if upgrading else "install" + + +def _data_dir_has_content() -> bool: + """Whether anything predates this session in the plugin data directory.""" + try: + for entry in memory_core.data_dir().iterdir(): + if entry.name != "install-state.json": + return True + except OSError: + pass + return False + + +def claim_version_change() -> str | None: + """Return the previously recorded version if it differs, updating the marker. + + Only meaningful once the marker exists — the first transition into 0.3.x has + no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting + the marker means the next session sees no change and records nothing. + """ + path = _install_state_path() + try: + state = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return None + if not isinstance(state, dict): + return None + previous = str(state.get("plugin_version") or "") + if not previous or previous == memory_core.PLUGIN_VERSION: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION + state["upgraded_at"] = memory_core.utc_now() + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text(json.dumps(state), encoding="utf-8") + temporary.replace(path) + except OSError: + return None + return previous def record( @@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool: def resolve_distinct_id() -> tuple[str, str]: - """Return the PostHog distinct id and the anonymous id it replaced, if any.""" + """Return the PostHog distinct id and the anonymous id it replaced, if any. + + The second value becomes a PostHog $identify alias. It is ONLY ever an + anonymous id: aliasing one account email to another merges two real person + profiles and cannot be undone, so a key that now belongs to a different + account re-resolves with no alias. + """ identity = _read_identity() - email = identity.get("email", "") - if email: - return email, "" key = memory_core.api_key() + fingerprint = _digest(key) if key else "" + email = identity.get("email", "") + + if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: + return email, "" + if not key: + # No key to verify the account with; do not keep attributing to it. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + _write_identity(identity) return anonymous_id(identity), "" - email = _resolve_email(key) - if not email: - return anonymous_id(identity), "" - previous = identity.get("anonymous_id", "") - identity["email"] = email + + resolved = _resolve_email(key) + if not resolved: + return (email, "") if email else (anonymous_id(identity), "") + + # Alias only when going anonymous -> email for the first time. + previous = "" if email else identity.get("anonymous_id", "") + identity["email"] = resolved + identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, previous + return resolved, previous def flush() -> int: diff --git a/integrations/claude-code-plugin/core/hook_runner.py b/integrations/claude-code-plugin/core/hook_runner.py index 2a2adb557..559702102 100644 --- a/integrations/claude-code-plugin/core/hook_runner.py +++ b/integrations/claude-code-plugin/core/hook_runner.py @@ -305,8 +305,19 @@ def run( return 0 if args.action == "session-start": - if telemetry.is_first_run(): + # Claims the marker atomically and says which event to record, so a + # second session starting alongside this one cannot record it too. + first_event = telemetry.claim_install() + if first_event == "install": telemetry.record("install") + elif first_event == "upgrade": + # First run after a build that never wrote the marker; the + # predecessor version was never recorded anywhere. + telemetry.record("upgrade", from_version="pre-0.3") + else: + previous = telemetry.claim_version_change() + if previous: + telemetry.record("upgrade", from_version=previous) recovered = recover_pending_handoffs() record_session_start(store, hook_input) if recovered: diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 55ee7c907..d7933bfbc 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _install_state_path() -> Path: + return memory_core.data_dir() / "install-state.json" + + def is_first_run() -> bool: - """Whether this machine has never recorded a plugin event before.""" - return not _identity_path().exists() + """Whether install has never been recorded on this machine. + + Deliberately NOT the identity file. That file is only written by a + successful flush, so an offline or firewalled user recorded code.install on + every single session, forever — and every 0.2.x user recorded one on their + first 0.3.x session because 0.2.x never wrote it at all. + """ + return not _install_state_path().exists() + + +def claim_install() -> str | None: + """Claim the one install/upgrade record for this machine, atomically. + + Returns the event to record ("install" or "upgrade"), or None if another + session already claimed it. O_CREAT|O_EXCL so two sessions starting together + cannot both win. + """ + path = _install_state_path() + # A fresh install has an empty data directory. Anything already there — + # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read + # before the marker is created, since creating it would itself be content. + upgrading = _data_dir_has_content() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + except FileExistsError: + return None + except OSError: + return None + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + json.dump( + { + "plugin_version": memory_core.PLUGIN_VERSION, + "installed_at": memory_core.utc_now(), + "upgraded": upgrading, + }, + stream, + ) + except OSError: + pass + return "upgrade" if upgrading else "install" + + +def _data_dir_has_content() -> bool: + """Whether anything predates this session in the plugin data directory.""" + try: + for entry in memory_core.data_dir().iterdir(): + if entry.name != "install-state.json": + return True + except OSError: + pass + return False + + +def claim_version_change() -> str | None: + """Return the previously recorded version if it differs, updating the marker. + + Only meaningful once the marker exists — the first transition into 0.3.x has + no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting + the marker means the next session sees no change and records nothing. + """ + path = _install_state_path() + try: + state = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return None + if not isinstance(state, dict): + return None + previous = str(state.get("plugin_version") or "") + if not previous or previous == memory_core.PLUGIN_VERSION: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION + state["upgraded_at"] = memory_core.utc_now() + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text(json.dumps(state), encoding="utf-8") + temporary.replace(path) + except OSError: + return None + return previous def record( @@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool: def resolve_distinct_id() -> tuple[str, str]: - """Return the PostHog distinct id and the anonymous id it replaced, if any.""" + """Return the PostHog distinct id and the anonymous id it replaced, if any. + + The second value becomes a PostHog $identify alias. It is ONLY ever an + anonymous id: aliasing one account email to another merges two real person + profiles and cannot be undone, so a key that now belongs to a different + account re-resolves with no alias. + """ identity = _read_identity() - email = identity.get("email", "") - if email: - return email, "" key = memory_core.api_key() + fingerprint = _digest(key) if key else "" + email = identity.get("email", "") + + if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: + return email, "" + if not key: + # No key to verify the account with; do not keep attributing to it. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + _write_identity(identity) return anonymous_id(identity), "" - email = _resolve_email(key) - if not email: - return anonymous_id(identity), "" - previous = identity.get("anonymous_id", "") - identity["email"] = email + + resolved = _resolve_email(key) + if not resolved: + return (email, "") if email else (anonymous_id(identity), "") + + # Alias only when going anonymous -> email for the first time. + previous = "" if email else identity.get("anonymous_id", "") + identity["email"] = resolved + identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, previous + return resolved, previous def flush() -> int: diff --git a/integrations/claude-code-plugin/tests/test_telemetry.py b/integrations/claude-code-plugin/tests/test_telemetry.py index 580bc1100..4476a9dd3 100644 --- a/integrations/claude-code-plugin/tests/test_telemetry.py +++ b/integrations/claude-code-plugin/tests/test_telemetry.py @@ -265,12 +265,47 @@ def test_an_unresolvable_key_falls_back_to_the_anonymous_id(isolated_env, monkey assert telemetry.resolve_distinct_id()[0].startswith("code-anon-") -def test_is_first_run_flips_after_the_first_identity_write(isolated_env): +def test_first_run_is_not_flipped_by_writing_the_identity_file(isolated_env): + """The identity file is written by a successful flush, not by recording. + + Keying first-run off it meant an offline user recorded code.install on every + session forever, and every 0.2.x user recorded one on their first 0.3.x run. + """ assert telemetry.is_first_run() telemetry.anonymous_id() + assert telemetry.is_first_run() + + +def test_claiming_install_ends_first_run(isolated_env): + assert telemetry.claim_install() == "install" assert not telemetry.is_first_run() +def test_install_can_only_be_claimed_once(isolated_env): + """Two sessions starting together must not both record an install.""" + assert telemetry.claim_install() == "install" + assert telemetry.claim_install() is None + + +def test_a_populated_data_dir_reads_as_an_upgrade(isolated_env): + """A fresh install has an empty data directory; anything else predates it.""" + data_dir = memory_core.data_dir() + data_dir.mkdir(parents=True, exist_ok=True) + (data_dir / "requirements.txt").write_text("mem0ai\n", encoding="utf-8") + assert telemetry.claim_install() == "upgrade" + + +def test_a_version_change_is_claimed_once(isolated_env): + telemetry.claim_install() + state_path = memory_core.data_dir() / "install-state.json" + state = json.loads(state_path.read_text()) + state["plugin_version"] = "0.0.1-old" + state_path.write_text(json.dumps(state), encoding="utf-8") + + assert telemetry.claim_version_change() == "0.0.1-old" + assert telemetry.claim_version_change() is None + + def test_spawn_flush_does_nothing_without_a_spool(isolated_env): with patch.object(telemetry.subprocess, "Popen") as popen: assert telemetry.spawn_flush() is False diff --git a/integrations/codex-plugin/core/hook_runner.py b/integrations/codex-plugin/core/hook_runner.py index 2a2adb557..559702102 100644 --- a/integrations/codex-plugin/core/hook_runner.py +++ b/integrations/codex-plugin/core/hook_runner.py @@ -305,8 +305,19 @@ def run( return 0 if args.action == "session-start": - if telemetry.is_first_run(): + # Claims the marker atomically and says which event to record, so a + # second session starting alongside this one cannot record it too. + first_event = telemetry.claim_install() + if first_event == "install": telemetry.record("install") + elif first_event == "upgrade": + # First run after a build that never wrote the marker; the + # predecessor version was never recorded anywhere. + telemetry.record("upgrade", from_version="pre-0.3") + else: + previous = telemetry.claim_version_change() + if previous: + telemetry.record("upgrade", from_version=previous) recovered = recover_pending_handoffs() record_session_start(store, hook_input) if recovered: diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 55ee7c907..d7933bfbc 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _install_state_path() -> Path: + return memory_core.data_dir() / "install-state.json" + + def is_first_run() -> bool: - """Whether this machine has never recorded a plugin event before.""" - return not _identity_path().exists() + """Whether install has never been recorded on this machine. + + Deliberately NOT the identity file. That file is only written by a + successful flush, so an offline or firewalled user recorded code.install on + every single session, forever — and every 0.2.x user recorded one on their + first 0.3.x session because 0.2.x never wrote it at all. + """ + return not _install_state_path().exists() + + +def claim_install() -> str | None: + """Claim the one install/upgrade record for this machine, atomically. + + Returns the event to record ("install" or "upgrade"), or None if another + session already claimed it. O_CREAT|O_EXCL so two sessions starting together + cannot both win. + """ + path = _install_state_path() + # A fresh install has an empty data directory. Anything already there — + # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read + # before the marker is created, since creating it would itself be content. + upgrading = _data_dir_has_content() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + except FileExistsError: + return None + except OSError: + return None + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + json.dump( + { + "plugin_version": memory_core.PLUGIN_VERSION, + "installed_at": memory_core.utc_now(), + "upgraded": upgrading, + }, + stream, + ) + except OSError: + pass + return "upgrade" if upgrading else "install" + + +def _data_dir_has_content() -> bool: + """Whether anything predates this session in the plugin data directory.""" + try: + for entry in memory_core.data_dir().iterdir(): + if entry.name != "install-state.json": + return True + except OSError: + pass + return False + + +def claim_version_change() -> str | None: + """Return the previously recorded version if it differs, updating the marker. + + Only meaningful once the marker exists — the first transition into 0.3.x has + no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting + the marker means the next session sees no change and records nothing. + """ + path = _install_state_path() + try: + state = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return None + if not isinstance(state, dict): + return None + previous = str(state.get("plugin_version") or "") + if not previous or previous == memory_core.PLUGIN_VERSION: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION + state["upgraded_at"] = memory_core.utc_now() + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text(json.dumps(state), encoding="utf-8") + temporary.replace(path) + except OSError: + return None + return previous def record( @@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool: def resolve_distinct_id() -> tuple[str, str]: - """Return the PostHog distinct id and the anonymous id it replaced, if any.""" + """Return the PostHog distinct id and the anonymous id it replaced, if any. + + The second value becomes a PostHog $identify alias. It is ONLY ever an + anonymous id: aliasing one account email to another merges two real person + profiles and cannot be undone, so a key that now belongs to a different + account re-resolves with no alias. + """ identity = _read_identity() - email = identity.get("email", "") - if email: - return email, "" key = memory_core.api_key() + fingerprint = _digest(key) if key else "" + email = identity.get("email", "") + + if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: + return email, "" + if not key: + # No key to verify the account with; do not keep attributing to it. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + _write_identity(identity) return anonymous_id(identity), "" - email = _resolve_email(key) - if not email: - return anonymous_id(identity), "" - previous = identity.get("anonymous_id", "") - identity["email"] = email + + resolved = _resolve_email(key) + if not resolved: + return (email, "") if email else (anonymous_id(identity), "") + + # Alias only when going anonymous -> email for the first time. + previous = "" if email else identity.get("anonymous_id", "") + identity["email"] = resolved + identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, previous + return resolved, previous def flush() -> int: diff --git a/integrations/cursor-plugin/core/hook_runner.py b/integrations/cursor-plugin/core/hook_runner.py index 2a2adb557..559702102 100644 --- a/integrations/cursor-plugin/core/hook_runner.py +++ b/integrations/cursor-plugin/core/hook_runner.py @@ -305,8 +305,19 @@ def run( return 0 if args.action == "session-start": - if telemetry.is_first_run(): + # Claims the marker atomically and says which event to record, so a + # second session starting alongside this one cannot record it too. + first_event = telemetry.claim_install() + if first_event == "install": telemetry.record("install") + elif first_event == "upgrade": + # First run after a build that never wrote the marker; the + # predecessor version was never recorded anywhere. + telemetry.record("upgrade", from_version="pre-0.3") + else: + previous = telemetry.claim_version_change() + if previous: + telemetry.record("upgrade", from_version=previous) recovered = recover_pending_handoffs() record_session_start(store, hook_input) if recovered: diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 55ee7c907..d7933bfbc 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _install_state_path() -> Path: + return memory_core.data_dir() / "install-state.json" + + def is_first_run() -> bool: - """Whether this machine has never recorded a plugin event before.""" - return not _identity_path().exists() + """Whether install has never been recorded on this machine. + + Deliberately NOT the identity file. That file is only written by a + successful flush, so an offline or firewalled user recorded code.install on + every single session, forever — and every 0.2.x user recorded one on their + first 0.3.x session because 0.2.x never wrote it at all. + """ + return not _install_state_path().exists() + + +def claim_install() -> str | None: + """Claim the one install/upgrade record for this machine, atomically. + + Returns the event to record ("install" or "upgrade"), or None if another + session already claimed it. O_CREAT|O_EXCL so two sessions starting together + cannot both win. + """ + path = _install_state_path() + # A fresh install has an empty data directory. Anything already there — + # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read + # before the marker is created, since creating it would itself be content. + upgrading = _data_dir_has_content() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + except FileExistsError: + return None + except OSError: + return None + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + json.dump( + { + "plugin_version": memory_core.PLUGIN_VERSION, + "installed_at": memory_core.utc_now(), + "upgraded": upgrading, + }, + stream, + ) + except OSError: + pass + return "upgrade" if upgrading else "install" + + +def _data_dir_has_content() -> bool: + """Whether anything predates this session in the plugin data directory.""" + try: + for entry in memory_core.data_dir().iterdir(): + if entry.name != "install-state.json": + return True + except OSError: + pass + return False + + +def claim_version_change() -> str | None: + """Return the previously recorded version if it differs, updating the marker. + + Only meaningful once the marker exists — the first transition into 0.3.x has + no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting + the marker means the next session sees no change and records nothing. + """ + path = _install_state_path() + try: + state = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return None + if not isinstance(state, dict): + return None + previous = str(state.get("plugin_version") or "") + if not previous or previous == memory_core.PLUGIN_VERSION: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION + state["upgraded_at"] = memory_core.utc_now() + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text(json.dumps(state), encoding="utf-8") + temporary.replace(path) + except OSError: + return None + return previous def record( @@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool: def resolve_distinct_id() -> tuple[str, str]: - """Return the PostHog distinct id and the anonymous id it replaced, if any.""" + """Return the PostHog distinct id and the anonymous id it replaced, if any. + + The second value becomes a PostHog $identify alias. It is ONLY ever an + anonymous id: aliasing one account email to another merges two real person + profiles and cannot be undone, so a key that now belongs to a different + account re-resolves with no alias. + """ identity = _read_identity() - email = identity.get("email", "") - if email: - return email, "" key = memory_core.api_key() + fingerprint = _digest(key) if key else "" + email = identity.get("email", "") + + if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: + return email, "" + if not key: + # No key to verify the account with; do not keep attributing to it. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + _write_identity(identity) return anonymous_id(identity), "" - email = _resolve_email(key) - if not email: - return anonymous_id(identity), "" - previous = identity.get("anonymous_id", "") - identity["email"] = email + + resolved = _resolve_email(key) + if not resolved: + return (email, "") if email else (anonymous_id(identity), "") + + # Alias only when going anonymous -> email for the first time. + previous = "" if email else identity.get("anonymous_id", "") + identity["email"] = resolved + identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, previous + return resolved, previous def flush() -> int: diff --git a/integrations/kimi-plugin/core/hook_runner.py b/integrations/kimi-plugin/core/hook_runner.py index 2a2adb557..559702102 100644 --- a/integrations/kimi-plugin/core/hook_runner.py +++ b/integrations/kimi-plugin/core/hook_runner.py @@ -305,8 +305,19 @@ def run( return 0 if args.action == "session-start": - if telemetry.is_first_run(): + # Claims the marker atomically and says which event to record, so a + # second session starting alongside this one cannot record it too. + first_event = telemetry.claim_install() + if first_event == "install": telemetry.record("install") + elif first_event == "upgrade": + # First run after a build that never wrote the marker; the + # predecessor version was never recorded anywhere. + telemetry.record("upgrade", from_version="pre-0.3") + else: + previous = telemetry.claim_version_change() + if previous: + telemetry.record("upgrade", from_version=previous) recovered = recover_pending_handoffs() record_session_start(store, hook_input) if recovered: diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 55ee7c907..d7933bfbc 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _install_state_path() -> Path: + return memory_core.data_dir() / "install-state.json" + + def is_first_run() -> bool: - """Whether this machine has never recorded a plugin event before.""" - return not _identity_path().exists() + """Whether install has never been recorded on this machine. + + Deliberately NOT the identity file. That file is only written by a + successful flush, so an offline or firewalled user recorded code.install on + every single session, forever — and every 0.2.x user recorded one on their + first 0.3.x session because 0.2.x never wrote it at all. + """ + return not _install_state_path().exists() + + +def claim_install() -> str | None: + """Claim the one install/upgrade record for this machine, atomically. + + Returns the event to record ("install" or "upgrade"), or None if another + session already claimed it. O_CREAT|O_EXCL so two sessions starting together + cannot both win. + """ + path = _install_state_path() + # A fresh install has an empty data directory. Anything already there — + # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read + # before the marker is created, since creating it would itself be content. + upgrading = _data_dir_has_content() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + except FileExistsError: + return None + except OSError: + return None + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + json.dump( + { + "plugin_version": memory_core.PLUGIN_VERSION, + "installed_at": memory_core.utc_now(), + "upgraded": upgrading, + }, + stream, + ) + except OSError: + pass + return "upgrade" if upgrading else "install" + + +def _data_dir_has_content() -> bool: + """Whether anything predates this session in the plugin data directory.""" + try: + for entry in memory_core.data_dir().iterdir(): + if entry.name != "install-state.json": + return True + except OSError: + pass + return False + + +def claim_version_change() -> str | None: + """Return the previously recorded version if it differs, updating the marker. + + Only meaningful once the marker exists — the first transition into 0.3.x has + no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting + the marker means the next session sees no change and records nothing. + """ + path = _install_state_path() + try: + state = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return None + if not isinstance(state, dict): + return None + previous = str(state.get("plugin_version") or "") + if not previous or previous == memory_core.PLUGIN_VERSION: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION + state["upgraded_at"] = memory_core.utc_now() + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text(json.dumps(state), encoding="utf-8") + temporary.replace(path) + except OSError: + return None + return previous def record( @@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool: def resolve_distinct_id() -> tuple[str, str]: - """Return the PostHog distinct id and the anonymous id it replaced, if any.""" + """Return the PostHog distinct id and the anonymous id it replaced, if any. + + The second value becomes a PostHog $identify alias. It is ONLY ever an + anonymous id: aliasing one account email to another merges two real person + profiles and cannot be undone, so a key that now belongs to a different + account re-resolves with no alias. + """ identity = _read_identity() - email = identity.get("email", "") - if email: - return email, "" key = memory_core.api_key() + fingerprint = _digest(key) if key else "" + email = identity.get("email", "") + + if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: + return email, "" + if not key: + # No key to verify the account with; do not keep attributing to it. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + _write_identity(identity) return anonymous_id(identity), "" - email = _resolve_email(key) - if not email: - return anonymous_id(identity), "" - previous = identity.get("anonymous_id", "") - identity["email"] = email + + resolved = _resolve_email(key) + if not resolved: + return (email, "") if email else (anonymous_id(identity), "") + + # Alias only when going anonymous -> email for the first time. + previous = "" if email else identity.get("anonymous_id", "") + identity["email"] = resolved + identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, previous + return resolved, previous def flush() -> int: diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 55ee7c907..d7933bfbc 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -206,9 +206,92 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _install_state_path() -> Path: + return memory_core.data_dir() / "install-state.json" + + def is_first_run() -> bool: - """Whether this machine has never recorded a plugin event before.""" - return not _identity_path().exists() + """Whether install has never been recorded on this machine. + + Deliberately NOT the identity file. That file is only written by a + successful flush, so an offline or firewalled user recorded code.install on + every single session, forever — and every 0.2.x user recorded one on their + first 0.3.x session because 0.2.x never wrote it at all. + """ + return not _install_state_path().exists() + + +def claim_install() -> str | None: + """Claim the one install/upgrade record for this machine, atomically. + + Returns the event to record ("install" or "upgrade"), or None if another + session already claimed it. O_CREAT|O_EXCL so two sessions starting together + cannot both win. + """ + path = _install_state_path() + # A fresh install has an empty data directory. Anything already there — + # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read + # before the marker is created, since creating it would itself be content. + upgrading = _data_dir_has_content() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + except FileExistsError: + return None + except OSError: + return None + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + json.dump( + { + "plugin_version": memory_core.PLUGIN_VERSION, + "installed_at": memory_core.utc_now(), + "upgraded": upgrading, + }, + stream, + ) + except OSError: + pass + return "upgrade" if upgrading else "install" + + +def _data_dir_has_content() -> bool: + """Whether anything predates this session in the plugin data directory.""" + try: + for entry in memory_core.data_dir().iterdir(): + if entry.name != "install-state.json": + return True + except OSError: + pass + return False + + +def claim_version_change() -> str | None: + """Return the previously recorded version if it differs, updating the marker. + + Only meaningful once the marker exists — the first transition into 0.3.x has + no recorded predecessor and reports "pre-0.3" instead. Claiming by rewriting + the marker means the next session sees no change and records nothing. + """ + path = _install_state_path() + try: + state = json.loads(path.read_text(encoding="utf-8")) + except (OSError, json.JSONDecodeError): + return None + if not isinstance(state, dict): + return None + previous = str(state.get("plugin_version") or "") + if not previous or previous == memory_core.PLUGIN_VERSION: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION + state["upgraded_at"] = memory_core.utc_now() + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text(json.dumps(state), encoding="utf-8") + temporary.replace(path) + except OSError: + return None + return previous def record( @@ -468,21 +551,39 @@ def _post(payload: dict[str, Any], url: str) -> bool: def resolve_distinct_id() -> tuple[str, str]: - """Return the PostHog distinct id and the anonymous id it replaced, if any.""" + """Return the PostHog distinct id and the anonymous id it replaced, if any. + + The second value becomes a PostHog $identify alias. It is ONLY ever an + anonymous id: aliasing one account email to another merges two real person + profiles and cannot be undone, so a key that now belongs to a different + account re-resolves with no alias. + """ identity = _read_identity() - email = identity.get("email", "") - if email: - return email, "" key = memory_core.api_key() + fingerprint = _digest(key) if key else "" + email = identity.get("email", "") + + if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: + return email, "" + if not key: + # No key to verify the account with; do not keep attributing to it. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + _write_identity(identity) return anonymous_id(identity), "" - email = _resolve_email(key) - if not email: - return anonymous_id(identity), "" - previous = identity.get("anonymous_id", "") - identity["email"] = email + + resolved = _resolve_email(key) + if not resolved: + return (email, "") if email else (anonymous_id(identity), "") + + # Alias only when going anonymous -> email for the first time. + previous = "" if email else identity.get("anonymous_id", "") + identity["email"] = resolved + identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, previous + return resolved, previous def flush() -> int: From bc5526f13d2fc7fadf630652381cbd9e5efa99e5 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:19:00 +0530 Subject: [PATCH 05/30] feat(integrations): declare which surface each client is, and its version MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Nothing on the wire said which Mem0 surface made a call. Both SDKs sent only an auth header, so the platform saw python-httpx and axios and attributed every plugin, wrapper and direct API user to one undifferentiated bucket. Version was unknowable, which is what gates every deprecation decision. Three headers, and the rules on them are the point: - X-Mem0-Source and X-Application are SET-ONCE. Whichever layer is outermost sets them; nothing below overwrites. A plugin wrapping the SDK keeps its own identity instead of being renamed by the transport underneath it. - X-Mem0-Client is APPEND-ONLY. A plugin calling the Python SDK produces `mem0-plugin/0.3.1, mem0-python/2.0.19`, so neither layer can erase the other. Deliberately not User-Agent: proxies rewrite it, and we have already met a WAF that 403s on it. The plugin core also hoists `source` out of metadata to the top level, which is where the backend actually reads it. It sat in metadata, which get_event_source never consults, so all six plugins arrived indistinguishable from a raw SDK call no matter what they set. The harness tag stays in metadata as hook provenance. pi-agent had PI_AGENT as a PostHog property only and never sent it on the wire. vercel-ai-sdk sent nothing at all from its raw fetch calls. Values must exist in the platform's EventSource enum or they bucket to OTHERS, so integrations/AGENTS.md now states the contract and the "adding an integration" checklist requires landing the platform value in the same week. Pairs with mem0ai/platform#3602, which recognizes these values. TypeScript changes are not typechecked locally — deps are not installed for those packages. CI covers them. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- cli/node/src/backend/platform.ts | 3 +- cli/python/src/mem0_cli/backend/platform.py | 3 +- integrations/AGENTS.md | 24 +++++++ .../agent-plugin-core/python/memory_core.py | 38 ++++++++++- .../antigravity-plugin/core/memory_core.py | 38 ++++++++++- .../claude-code-plugin/core/memory_core.py | 38 ++++++++++- integrations/codex-plugin/core/memory_core.py | 38 ++++++++++- .../cursor-plugin/core/memory_core.py | 38 ++++++++++- integrations/kimi-plugin/core/memory_core.py | 38 ++++++++++- .../mem0-agent-plugin/core/memory_core.py | 38 ++++++++++- integrations/pi-agent-plugin/src/commands.ts | 9 ++- integrations/vercel-ai-sdk/src/mem0-utils.ts | 14 +++- mem0-ts/src/client/mem0.ts | 33 ++++++++++ mem0/client/main.py | 66 ++++++++++++++----- 14 files changed, 373 insertions(+), 45 deletions(-) diff --git a/cli/node/src/backend/platform.ts b/cli/node/src/backend/platform.ts index 705a3d470..65a4b6228 100644 --- a/cli/node/src/backend/platform.ts +++ b/cli/node/src/backend/platform.ts @@ -31,7 +31,8 @@ export class PlatformBackend implements Backend { this.headers = { Authorization: `Token ${config.apiKey}`, "Content-Type": "application/json", - "X-Mem0-Source": "cli", + "X-Mem0-Source": "CLI", + "X-Mem0-Client": `mem0-cli-node/${CLI_VERSION}`, "X-Mem0-Client-Language": "node", "X-Mem0-Client-Version": CLI_VERSION, }; diff --git a/cli/python/src/mem0_cli/backend/platform.py b/cli/python/src/mem0_cli/backend/platform.py index 1d153da9c..a9ce60df1 100644 --- a/cli/python/src/mem0_cli/backend/platform.py +++ b/cli/python/src/mem0_cli/backend/platform.py @@ -27,7 +27,8 @@ class PlatformBackend(Backend): headers={ "Authorization": f"Token {config.api_key}", "Content-Type": "application/json", - "X-Mem0-Source": "cli", + "X-Mem0-Source": "CLI", + "X-Mem0-Client": f"mem0-cli-python/{__version__}", "X-Mem0-Client-Language": "python", "X-Mem0-Client-Version": __version__, }, diff --git a/integrations/AGENTS.md b/integrations/AGENTS.md index c129dd48b..75b60009e 100644 --- a/integrations/AGENTS.md +++ b/integrations/AGENTS.md @@ -49,6 +49,29 @@ Run the type check after every TypeScript change: `pnpm run typecheck` or `tsc - - **`zapier-mem0/`** is a Zapier Platform CLI app: add, search, get, delete. It deploys to Zapier, not npm, so it is **not** in the release router. Deploy it with `gh workflow run zapier-mem0-cd.yml --ref main` (needs the `ZAPIER_DEPLOY_KEY` secret). - **`mem0-strands/`** is a native Strands `MemoryStore` (Python, published to PyPI as `mem0-strands`). It plugs into the Strands `MemoryManager` for automatic recall and server-side extraction, over the hosted Mem0 platform or self-hosted Mem0 OSS. The package lives under `mem0-strands/python/`. +## Surface attribution + +Every integration tells the Mem0 platform which surface it is. Three headers, +and the rules on them are what keep one layer from erasing another: + +| Header | Carries | Rule | +|--------|---------|------| +| `X-Mem0-Source` | one canonical source value | **set-once** — write only if absent | +| `X-Application` | the host app it runs inside | **set-once** — write only if absent | +| `X-Mem0-Client` | `name/version`, outermost first | **append-only** — add yourself, never replace | + +Set-once means `setdefault`, never assignment. An integration that wraps the +SDK is the outermost layer and sets the source; the SDK underneath must defer to +it. Assignment is exactly how every agent plugin came to be indistinguishable +from every other one at the platform. + +Append-only means a plugin calling the Python SDK produces +`mem0-plugin/0.3.1, mem0-python/2.0.19`, so neither layer can erase the other. + +The backend recognizes a fixed list of source values and buckets everything else +into `OTHERS`. A new value has to land in the platform's `EventSource` enum, so +do not invent one without that change going in too. + ## Adding an integration 1. For a native coding-agent host, add `integrations/-plugin/` with `plugin-build.json`, its manifest, and a thin adapter, then generate its shared runtime. Portable clients use the single `mem0-agent-plugin/` package. Independent TypeScript integrations stay self-contained and import shared lifecycle behavior from `agent-plugin-core/typescript/`. @@ -59,3 +82,4 @@ Run the type check after every TypeScript change: `pnpm run typecheck` or `tsc - 5. If it is a Claude Code or editor marketplace plugin, register the generated native bundle path in the applicable marketplace files. Preserve the existing public plugin name. 6. Document it under `docs/integrations/` and add the page to `docs/docs.json` and `docs/llms.txt`. 7. Add rows to the table above and to the CI/CD tables in [`../.github/AGENTS.md`](../.github/AGENTS.md). +8. Send the three headers in [Surface attribution](#surface-attribution), and land the matching `EventSource` value on the platform in the same week. Until it exists, your traffic reports as `OTHERS`. diff --git a/integrations/agent-plugin-core/python/memory_core.py b/integrations/agent-plugin-core/python/memory_core.py index 77d7a2b80..31a08ec37 100644 --- a/integrations/agent-plugin-core/python/memory_core.py +++ b/integrations/agent-plugin-core/python/memory_core.py @@ -1800,6 +1800,34 @@ def extraction_message_batches( return batches +# Platform surface attribution. Read from the generated per-host module so a new +# entrypoint is correct without remembering to configure anything. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE +except ImportError: + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + + +def platform_headers(key: str) -> dict[str, str]: + """Auth plus the three surface-identity headers. + + X-Mem0-Source and X-Application are set-once by contract: this is the + outermost layer, so it sets them, and nothing below may overwrite them. + X-Mem0-Client is append-only — anything downstream adds itself to the tail. + """ + headers = { + "Authorization": f"Token {key}", + "Content-Type": "application/json", + "X-Mem0-Source": _PLATFORM_SOURCE, + "X-Mem0-Client": f"mem0-plugin/{PLUGIN_VERSION}", + } + if _PLATFORM_APPLICATION: + headers["X-Application"] = _PLATFORM_APPLICATION + return headers + + def _request_json( url: str, key: str, payload: dict[str, Any], timeout: float ) -> tuple[dict[str, Any] | list[Any], int, int]: @@ -1807,7 +1835,7 @@ def _request_json( request = urllib.request.Request( url, data=raw, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="POST", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1834,7 +1862,7 @@ def _get_json( ) -> tuple[dict[str, Any] | list[Any], int]: request = urllib.request.Request( url, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="GET", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1980,6 +2008,10 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, + # Top level, not metadata: the backend reads `source` from the body, + # query string or X-Mem0-Source header, never from metadata. The + # harness tag stays in metadata as hook provenance. + "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, "custom_instructions": PERSONAL_MEMORY_INSTRUCTIONS, @@ -2523,7 +2555,7 @@ def _collect_memory_ids( def _delete_memory(api_url: str, key: str, memory_id: str) -> bool: request = urllib.request.Request( f"{api_url}/v1/memories/{urllib.parse.quote(memory_id)}/", - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="DELETE", ) try: diff --git a/integrations/antigravity-plugin/core/memory_core.py b/integrations/antigravity-plugin/core/memory_core.py index 77d7a2b80..31a08ec37 100644 --- a/integrations/antigravity-plugin/core/memory_core.py +++ b/integrations/antigravity-plugin/core/memory_core.py @@ -1800,6 +1800,34 @@ def extraction_message_batches( return batches +# Platform surface attribution. Read from the generated per-host module so a new +# entrypoint is correct without remembering to configure anything. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE +except ImportError: + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + + +def platform_headers(key: str) -> dict[str, str]: + """Auth plus the three surface-identity headers. + + X-Mem0-Source and X-Application are set-once by contract: this is the + outermost layer, so it sets them, and nothing below may overwrite them. + X-Mem0-Client is append-only — anything downstream adds itself to the tail. + """ + headers = { + "Authorization": f"Token {key}", + "Content-Type": "application/json", + "X-Mem0-Source": _PLATFORM_SOURCE, + "X-Mem0-Client": f"mem0-plugin/{PLUGIN_VERSION}", + } + if _PLATFORM_APPLICATION: + headers["X-Application"] = _PLATFORM_APPLICATION + return headers + + def _request_json( url: str, key: str, payload: dict[str, Any], timeout: float ) -> tuple[dict[str, Any] | list[Any], int, int]: @@ -1807,7 +1835,7 @@ def _request_json( request = urllib.request.Request( url, data=raw, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="POST", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1834,7 +1862,7 @@ def _get_json( ) -> tuple[dict[str, Any] | list[Any], int]: request = urllib.request.Request( url, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="GET", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1980,6 +2008,10 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, + # Top level, not metadata: the backend reads `source` from the body, + # query string or X-Mem0-Source header, never from metadata. The + # harness tag stays in metadata as hook provenance. + "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, "custom_instructions": PERSONAL_MEMORY_INSTRUCTIONS, @@ -2523,7 +2555,7 @@ def _collect_memory_ids( def _delete_memory(api_url: str, key: str, memory_id: str) -> bool: request = urllib.request.Request( f"{api_url}/v1/memories/{urllib.parse.quote(memory_id)}/", - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="DELETE", ) try: diff --git a/integrations/claude-code-plugin/core/memory_core.py b/integrations/claude-code-plugin/core/memory_core.py index 77d7a2b80..31a08ec37 100644 --- a/integrations/claude-code-plugin/core/memory_core.py +++ b/integrations/claude-code-plugin/core/memory_core.py @@ -1800,6 +1800,34 @@ def extraction_message_batches( return batches +# Platform surface attribution. Read from the generated per-host module so a new +# entrypoint is correct without remembering to configure anything. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE +except ImportError: + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + + +def platform_headers(key: str) -> dict[str, str]: + """Auth plus the three surface-identity headers. + + X-Mem0-Source and X-Application are set-once by contract: this is the + outermost layer, so it sets them, and nothing below may overwrite them. + X-Mem0-Client is append-only — anything downstream adds itself to the tail. + """ + headers = { + "Authorization": f"Token {key}", + "Content-Type": "application/json", + "X-Mem0-Source": _PLATFORM_SOURCE, + "X-Mem0-Client": f"mem0-plugin/{PLUGIN_VERSION}", + } + if _PLATFORM_APPLICATION: + headers["X-Application"] = _PLATFORM_APPLICATION + return headers + + def _request_json( url: str, key: str, payload: dict[str, Any], timeout: float ) -> tuple[dict[str, Any] | list[Any], int, int]: @@ -1807,7 +1835,7 @@ def _request_json( request = urllib.request.Request( url, data=raw, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="POST", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1834,7 +1862,7 @@ def _get_json( ) -> tuple[dict[str, Any] | list[Any], int]: request = urllib.request.Request( url, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="GET", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1980,6 +2008,10 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, + # Top level, not metadata: the backend reads `source` from the body, + # query string or X-Mem0-Source header, never from metadata. The + # harness tag stays in metadata as hook provenance. + "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, "custom_instructions": PERSONAL_MEMORY_INSTRUCTIONS, @@ -2523,7 +2555,7 @@ def _collect_memory_ids( def _delete_memory(api_url: str, key: str, memory_id: str) -> bool: request = urllib.request.Request( f"{api_url}/v1/memories/{urllib.parse.quote(memory_id)}/", - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="DELETE", ) try: diff --git a/integrations/codex-plugin/core/memory_core.py b/integrations/codex-plugin/core/memory_core.py index 77d7a2b80..31a08ec37 100644 --- a/integrations/codex-plugin/core/memory_core.py +++ b/integrations/codex-plugin/core/memory_core.py @@ -1800,6 +1800,34 @@ def extraction_message_batches( return batches +# Platform surface attribution. Read from the generated per-host module so a new +# entrypoint is correct without remembering to configure anything. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE +except ImportError: + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + + +def platform_headers(key: str) -> dict[str, str]: + """Auth plus the three surface-identity headers. + + X-Mem0-Source and X-Application are set-once by contract: this is the + outermost layer, so it sets them, and nothing below may overwrite them. + X-Mem0-Client is append-only — anything downstream adds itself to the tail. + """ + headers = { + "Authorization": f"Token {key}", + "Content-Type": "application/json", + "X-Mem0-Source": _PLATFORM_SOURCE, + "X-Mem0-Client": f"mem0-plugin/{PLUGIN_VERSION}", + } + if _PLATFORM_APPLICATION: + headers["X-Application"] = _PLATFORM_APPLICATION + return headers + + def _request_json( url: str, key: str, payload: dict[str, Any], timeout: float ) -> tuple[dict[str, Any] | list[Any], int, int]: @@ -1807,7 +1835,7 @@ def _request_json( request = urllib.request.Request( url, data=raw, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="POST", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1834,7 +1862,7 @@ def _get_json( ) -> tuple[dict[str, Any] | list[Any], int]: request = urllib.request.Request( url, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="GET", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1980,6 +2008,10 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, + # Top level, not metadata: the backend reads `source` from the body, + # query string or X-Mem0-Source header, never from metadata. The + # harness tag stays in metadata as hook provenance. + "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, "custom_instructions": PERSONAL_MEMORY_INSTRUCTIONS, @@ -2523,7 +2555,7 @@ def _collect_memory_ids( def _delete_memory(api_url: str, key: str, memory_id: str) -> bool: request = urllib.request.Request( f"{api_url}/v1/memories/{urllib.parse.quote(memory_id)}/", - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="DELETE", ) try: diff --git a/integrations/cursor-plugin/core/memory_core.py b/integrations/cursor-plugin/core/memory_core.py index 77d7a2b80..31a08ec37 100644 --- a/integrations/cursor-plugin/core/memory_core.py +++ b/integrations/cursor-plugin/core/memory_core.py @@ -1800,6 +1800,34 @@ def extraction_message_batches( return batches +# Platform surface attribution. Read from the generated per-host module so a new +# entrypoint is correct without remembering to configure anything. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE +except ImportError: + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + + +def platform_headers(key: str) -> dict[str, str]: + """Auth plus the three surface-identity headers. + + X-Mem0-Source and X-Application are set-once by contract: this is the + outermost layer, so it sets them, and nothing below may overwrite them. + X-Mem0-Client is append-only — anything downstream adds itself to the tail. + """ + headers = { + "Authorization": f"Token {key}", + "Content-Type": "application/json", + "X-Mem0-Source": _PLATFORM_SOURCE, + "X-Mem0-Client": f"mem0-plugin/{PLUGIN_VERSION}", + } + if _PLATFORM_APPLICATION: + headers["X-Application"] = _PLATFORM_APPLICATION + return headers + + def _request_json( url: str, key: str, payload: dict[str, Any], timeout: float ) -> tuple[dict[str, Any] | list[Any], int, int]: @@ -1807,7 +1835,7 @@ def _request_json( request = urllib.request.Request( url, data=raw, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="POST", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1834,7 +1862,7 @@ def _get_json( ) -> tuple[dict[str, Any] | list[Any], int]: request = urllib.request.Request( url, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="GET", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1980,6 +2008,10 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, + # Top level, not metadata: the backend reads `source` from the body, + # query string or X-Mem0-Source header, never from metadata. The + # harness tag stays in metadata as hook provenance. + "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, "custom_instructions": PERSONAL_MEMORY_INSTRUCTIONS, @@ -2523,7 +2555,7 @@ def _collect_memory_ids( def _delete_memory(api_url: str, key: str, memory_id: str) -> bool: request = urllib.request.Request( f"{api_url}/v1/memories/{urllib.parse.quote(memory_id)}/", - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="DELETE", ) try: diff --git a/integrations/kimi-plugin/core/memory_core.py b/integrations/kimi-plugin/core/memory_core.py index 77d7a2b80..31a08ec37 100644 --- a/integrations/kimi-plugin/core/memory_core.py +++ b/integrations/kimi-plugin/core/memory_core.py @@ -1800,6 +1800,34 @@ def extraction_message_batches( return batches +# Platform surface attribution. Read from the generated per-host module so a new +# entrypoint is correct without remembering to configure anything. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE +except ImportError: + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + + +def platform_headers(key: str) -> dict[str, str]: + """Auth plus the three surface-identity headers. + + X-Mem0-Source and X-Application are set-once by contract: this is the + outermost layer, so it sets them, and nothing below may overwrite them. + X-Mem0-Client is append-only — anything downstream adds itself to the tail. + """ + headers = { + "Authorization": f"Token {key}", + "Content-Type": "application/json", + "X-Mem0-Source": _PLATFORM_SOURCE, + "X-Mem0-Client": f"mem0-plugin/{PLUGIN_VERSION}", + } + if _PLATFORM_APPLICATION: + headers["X-Application"] = _PLATFORM_APPLICATION + return headers + + def _request_json( url: str, key: str, payload: dict[str, Any], timeout: float ) -> tuple[dict[str, Any] | list[Any], int, int]: @@ -1807,7 +1835,7 @@ def _request_json( request = urllib.request.Request( url, data=raw, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="POST", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1834,7 +1862,7 @@ def _get_json( ) -> tuple[dict[str, Any] | list[Any], int]: request = urllib.request.Request( url, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="GET", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1980,6 +2008,10 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, + # Top level, not metadata: the backend reads `source` from the body, + # query string or X-Mem0-Source header, never from metadata. The + # harness tag stays in metadata as hook provenance. + "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, "custom_instructions": PERSONAL_MEMORY_INSTRUCTIONS, @@ -2523,7 +2555,7 @@ def _collect_memory_ids( def _delete_memory(api_url: str, key: str, memory_id: str) -> bool: request = urllib.request.Request( f"{api_url}/v1/memories/{urllib.parse.quote(memory_id)}/", - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="DELETE", ) try: diff --git a/integrations/mem0-agent-plugin/core/memory_core.py b/integrations/mem0-agent-plugin/core/memory_core.py index 77d7a2b80..31a08ec37 100644 --- a/integrations/mem0-agent-plugin/core/memory_core.py +++ b/integrations/mem0-agent-plugin/core/memory_core.py @@ -1800,6 +1800,34 @@ def extraction_message_batches( return batches +# Platform surface attribution. Read from the generated per-host module so a new +# entrypoint is correct without remembering to configure anything. +try: # pragma: no cover - absent only in the un-built shared source tree + from _harness_id import PLATFORM_APPLICATION as _PLATFORM_APPLICATION + from _harness_id import PLATFORM_SOURCE as _PLATFORM_SOURCE +except ImportError: + _PLATFORM_SOURCE = "MEM0_PLUGIN" + _PLATFORM_APPLICATION = "" + + +def platform_headers(key: str) -> dict[str, str]: + """Auth plus the three surface-identity headers. + + X-Mem0-Source and X-Application are set-once by contract: this is the + outermost layer, so it sets them, and nothing below may overwrite them. + X-Mem0-Client is append-only — anything downstream adds itself to the tail. + """ + headers = { + "Authorization": f"Token {key}", + "Content-Type": "application/json", + "X-Mem0-Source": _PLATFORM_SOURCE, + "X-Mem0-Client": f"mem0-plugin/{PLUGIN_VERSION}", + } + if _PLATFORM_APPLICATION: + headers["X-Application"] = _PLATFORM_APPLICATION + return headers + + def _request_json( url: str, key: str, payload: dict[str, Any], timeout: float ) -> tuple[dict[str, Any] | list[Any], int, int]: @@ -1807,7 +1835,7 @@ def _request_json( request = urllib.request.Request( url, data=raw, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="POST", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1834,7 +1862,7 @@ def _get_json( ) -> tuple[dict[str, Any] | list[Any], int]: request = urllib.request.Request( url, - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="GET", ) with urllib.request.urlopen(request, timeout=timeout) as response: @@ -1980,6 +2008,10 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, + # Top level, not metadata: the backend reads `source` from the body, + # query string or X-Mem0-Source header, never from metadata. The + # harness tag stays in metadata as hook provenance. + "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, "custom_instructions": PERSONAL_MEMORY_INSTRUCTIONS, @@ -2523,7 +2555,7 @@ def _collect_memory_ids( def _delete_memory(api_url: str, key: str, memory_id: str) -> bool: request = urllib.request.Request( f"{api_url}/v1/memories/{urllib.parse.quote(memory_id)}/", - headers={"Authorization": f"Token {key}", "Content-Type": "application/json"}, + headers=platform_headers(key), method="DELETE", ) try: diff --git a/integrations/pi-agent-plugin/src/commands.ts b/integrations/pi-agent-plugin/src/commands.ts index 9379bed9a..e90f8833b 100644 --- a/integrations/pi-agent-plugin/src/commands.ts +++ b/integrations/pi-agent-plugin/src/commands.ts @@ -22,6 +22,10 @@ export function registerCommands( const pluralize = (n: number, one: string, many: string): string => `${n} ${n === 1 ? one : many}`; +// Surface attribution on the wire. This was previously only a PostHog property, +// so the platform saw these calls as generic SDK traffic. +const PLATFORM_SOURCE = "PI_AGENT"; + const searchMemories = async (query: string, scope: Scope) => { const filters = resolveSearchFilters(scope, getScopeCtx()); const result = await mem0.search(query, { @@ -29,7 +33,8 @@ export function registerCommands( threshold: config.searchThreshold, topK: SEARCH_TOP_K, rerank: true, - }); + source: PLATFORM_SOURCE, + } as never); return result.results ?? []; }; @@ -45,7 +50,7 @@ export function registerCommands( const addParams = resolveAddParams(config.defaultScope, getScopeCtx()); const result = await mem0.add( [{ role: "user", content: text }], - { ...addParams, customCategories: DEFAULT_CUSTOM_CATEGORIES, infer: false }, + { ...addParams, customCategories: DEFAULT_CUSTOM_CATEGORIES, infer: false, source: PLATFORM_SOURCE } as never, ); captureCommandEvent("mem0-remember", {}, telemetryCtx); diff --git a/integrations/vercel-ai-sdk/src/mem0-utils.ts b/integrations/vercel-ai-sdk/src/mem0-utils.ts index 55d485cbc..8fa20440c 100644 --- a/integrations/vercel-ai-sdk/src/mem0-utils.ts +++ b/integrations/vercel-ai-sdk/src/mem0-utils.ts @@ -1,3 +1,5 @@ +const PROVIDER_VERSION = "3.0.2"; + import { LanguageModelV3Prompt } from '@ai-sdk/provider'; import { Mem0ConfigSettings } from './mem0-types'; import { loadApiKey } from '@ai-sdk/provider-utils'; @@ -277,7 +279,11 @@ const searchInternalMemories = async (query: string, config?: Mem0ConfigSettings method: 'POST', headers: { Authorization: `Token ${apiKey}`, - 'Content-Type': 'application/json' + 'Content-Type': 'application/json', + // Surface attribution. Set-once by contract: this wrapper is the + // outermost layer on these raw fetch calls. + 'X-Mem0-Source': 'VERCEL_AI_SDK', + 'X-Mem0-Client': `mem0-vercel-ai-provider/${PROVIDER_VERSION}` }, body: JSON.stringify(body), }; @@ -331,7 +337,11 @@ const updateMemories = async (messages: Array, config?: Mem0ConfigSetti method: 'POST', headers: { Authorization: `Token ${apiKey}`, - 'Content-Type': 'application/json' + 'Content-Type': 'application/json', + // Surface attribution. Set-once by contract: this wrapper is the + // outermost layer on these raw fetch calls. + 'X-Mem0-Source': 'VERCEL_AI_SDK', + 'X-Mem0-Client': `mem0-vercel-ai-provider/${PROVIDER_VERSION}` }, body: JSON.stringify(body), }; diff --git a/mem0-ts/src/client/mem0.ts b/mem0-ts/src/client/mem0.ts index ff259f2fe..6327acffa 100644 --- a/mem0-ts/src/client/mem0.ts +++ b/mem0-ts/src/client/mem0.ts @@ -95,6 +95,38 @@ interface ClientIdentity { const IDENTITY_CACHE_MAX_DEFAULT = 50; const identityByCredentials = new Map>(); +const SDK_VERSION = "3.1.8"; + +/** + * Surface-identity headers. + * + * X-Mem0-Source and X-Application are SET-ONCE by contract: whichever layer is + * outermost sets them and nothing below overwrites, so a plugin wrapping this + * SDK keeps its own identity. X-Mem0-Client is APPEND-ONLY - every layer adds + * itself, so the platform sees the whole stack and not just the last speaker. + */ +function surfaceHeaders(): Record { + const env: Record = + typeof process !== "undefined" && process.env ? process.env : {}; + const existing = (env.MEM0_CLIENT_STACK ?? "").trim(); + const entries = existing + ? existing + .split(",") + .map((part) => part.trim()) + .filter(Boolean) + : []; + entries.push(`mem0-js/${SDK_VERSION}`); + + const headers: Record = { + "X-Mem0-Client": entries.slice(0, 4).join(", ").slice(0, 200), + }; + const source = (env.MEM0_SOURCE ?? "").trim(); + if (source) headers["X-Mem0-Source"] = source; + const application = (env.MEM0_APPLICATION ?? "").trim(); + if (application) headers["X-Application"] = application; + return headers; +} + export default class MemoryClient { apiKey: string; host: string; @@ -129,6 +161,7 @@ export default class MemoryClient { this.headers = { Authorization: `Token ${this.apiKey}`, "Content-Type": "application/json", + ...surfaceHeaders(), }; this.client = axios.create({ diff --git a/mem0/client/main.py b/mem0/client/main.py index a52986dcd..d118bc340 100644 --- a/mem0/client/main.py +++ b/mem0/client/main.py @@ -79,6 +79,50 @@ def _maybe_alias_anon_to_email(user_email): logger.debug("Failed to alias anon telemetry to %r: %s", user_email, e) +def _sdk_version() -> str: + """Resolved here rather than imported from the package root, which would cycle.""" + try: + import importlib.metadata + + return importlib.metadata.version("mem0ai") + except Exception: + return "unknown" + + +def _client_headers(api_key: str, user_id: str) -> Dict[str, str]: + """Auth plus surface-identity headers. + + X-Mem0-Source and X-Application are SET-ONCE by contract: whichever layer is + outermost sets them, and nothing below overwrites. A plugin or harness that + wraps this SDK therefore keeps its own identity — it declares via MEM0_SOURCE + / MEM0_APPLICATION and the SDK defers. + + X-Mem0-Client is APPEND-ONLY: every layer adds itself, so the platform sees + the whole stack rather than only whoever spoke last. + """ + headers = { + "Authorization": f"Token {api_key}", + "Mem0-User-ID": user_id, + "X-Mem0-Client": _client_stack(), + } + source = os.getenv("MEM0_SOURCE", "").strip() + if source: + headers["X-Mem0-Source"] = source + application = os.getenv("MEM0_APPLICATION", "").strip() + if application: + headers["X-Application"] = application + return headers + + +def _client_stack() -> str: + """This SDK appended to any stack an outer layer already declared.""" + existing = os.getenv("MEM0_CLIENT_STACK", "").strip() + mine = f"mem0-python/{_sdk_version()}" + entries = [part.strip() for part in existing.split(",") if part.strip()] if existing else [] + entries.append(mine) + return ", ".join(entries[:4])[:200] + + class MemoryClient: """Client for interacting with the Mem0 API. @@ -129,19 +173,11 @@ class MemoryClient: self.client = client # Ensure the client has the correct base_url and headers self.client.base_url = httpx.URL(self.host) - self.client.headers.update( - { - "Authorization": f"Token {self.api_key}", - "Mem0-User-ID": self.user_id, - } - ) + self.client.headers.update(_client_headers(self.api_key, self.user_id)) else: self.client = httpx.Client( base_url=self.host, - headers={ - "Authorization": f"Token {self.api_key}", - "Mem0-User-ID": self.user_id, - }, + headers=_client_headers(self.api_key, self.user_id), timeout=300, ) self.user_email = self._validate_api_key() @@ -1027,10 +1063,7 @@ class AsyncMemoryClient: else: self.async_client = httpx.AsyncClient( base_url=self.host, - headers={ - "Authorization": f"Token {self.api_key}", - "Mem0-User-ID": self.user_id, - }, + headers=_client_headers(self.api_key, self.user_id), timeout=300, ) @@ -1053,10 +1086,7 @@ class AsyncMemoryClient: params = self._prepare_params() response = requests.get( f"{self.host}/v1/ping/", - headers={ - "Authorization": f"Token {self.api_key}", - "Mem0-User-ID": self.user_id, - }, + headers=_client_headers(self.api_key, self.user_id), params=params, ) response.raise_for_status() From 95d4fc27e23c1e05888915c142051c7c28235a95 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:25:12 +0530 Subject: [PATCH 06/30] fix(plugins): make the telemetry salt stable, its own file, and memoized MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review found three ways the first cut produced worse data than no salt at all. All three came from keeping the salt as a key in the identity dict and doing an unlocked read-modify-write. Hooks are short-lived separate processes firing on every tool call, and people run more than one agent window, so several processes would read {}, each mint its own uuid4, and each hash with it. One repository hashed several ways in the window before a writer won. resolve_distinct_id holds a copy of that same dict across a network call to /v1/ping/ with a 5s timeout, so whichever write landed second erased the other's key: losing the salt changes repo_hash mid-stream, losing the email fires a second $identify and splits the person. _write_identity swallows OSError, and nothing memoized, so on a read-only or full data directory every single event got a brand-new random salt — unbounded cardinality in PostHog, which is strictly worse than the unsalted value it replaced. The salt now lives in its own file claimed with O_CREAT|O_EXCL, so exactly one process wins and the losers read the winner's value, and it is memoized per process. When it cannot be persisted the fallback is derived from the data directory path: stable for the machine rather than random per call. Its own file also means record() no longer creates telemetry-identity.json as a side effect. is_first_run keys off that file, so the first cut would have silently suppressed the install event — a production metric change hidden in a docs PR. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/telemetry.py | 62 ++++++++++++++++--- .../antigravity-plugin/core/telemetry.py | 62 ++++++++++++++++--- .../claude-code-plugin/core/telemetry.py | 62 ++++++++++++++++--- .../tests/test_telemetry.py | 47 ++++++++++++++ integrations/codex-plugin/core/telemetry.py | 62 ++++++++++++++++--- integrations/cursor-plugin/core/telemetry.py | 62 ++++++++++++++++--- integrations/kimi-plugin/core/telemetry.py | 62 ++++++++++++++++--- .../mem0-agent-plugin/core/telemetry.py | 62 ++++++++++++++++--- 8 files changed, 425 insertions(+), 56 deletions(-) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 1b6bd854e..239836604 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -34,6 +34,7 @@ from typing import Any import memory_core +_salt_cache: str = "" _harness: str = "generic" _source_tag: str = "MEM0_PLUGIN" _PRIVATE_KEYS = { @@ -92,15 +93,60 @@ def _digest(value: str, length: int = 16) -> str: return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _salt_path() -> Path: + return memory_core.data_dir() / "telemetry-salt" + + def _install_salt() -> str: - """Random per-install salt, created on first use and kept in the identity file.""" - identity = _read_identity() - salt = identity.get("salt") - if not salt: - salt = uuid.uuid4().hex - identity["salt"] = salt - _write_identity(identity) - return salt + """Random per-install salt, created once and memoized for the process. + + Deliberately its own file, claimed with O_CREAT|O_EXCL, rather than a key in + the identity file. Three reasons, all of which produced wrong data when this + lived in the identity dict: + + - Hooks are short-lived separate processes firing on every tool call, and + people run more than one agent window. A read-modify-write would let each + process mint its own salt, so one repository would hash several ways in the + window before a writer won. + - resolve_distinct_id holds a copy of the identity dict across a network call + to /v1/ping/, so whichever write landed second erased the other's key — + losing either the salt (repo_hash changes mid-stream) or the email (a + second $identify, splitting the person). + - Touching the identity file from record() would create it, and is_first_run + keys off that file, so recording an event would silently suppress the + install event. + + On a read-only or full data directory the fallback is derived from the data + directory path: stable for the machine rather than random per call, so the + failure mode is a weaker salt and not unbounded cardinality in PostHog. + """ + global _salt_cache + if _salt_cache: + return _salt_cache + + path = _salt_path() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + except OSError: + pass + except FileExistsError: + pass + except OSError: + # Cannot persist. Stable-per-machine beats random-per-call. + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache + + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + except OSError: + _salt_cache = "" + if not _salt_cache: + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache def _scoped_digest(value: str, length: int = 16) -> str: diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 1b6bd854e..239836604 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -34,6 +34,7 @@ from typing import Any import memory_core +_salt_cache: str = "" _harness: str = "generic" _source_tag: str = "MEM0_PLUGIN" _PRIVATE_KEYS = { @@ -92,15 +93,60 @@ def _digest(value: str, length: int = 16) -> str: return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _salt_path() -> Path: + return memory_core.data_dir() / "telemetry-salt" + + def _install_salt() -> str: - """Random per-install salt, created on first use and kept in the identity file.""" - identity = _read_identity() - salt = identity.get("salt") - if not salt: - salt = uuid.uuid4().hex - identity["salt"] = salt - _write_identity(identity) - return salt + """Random per-install salt, created once and memoized for the process. + + Deliberately its own file, claimed with O_CREAT|O_EXCL, rather than a key in + the identity file. Three reasons, all of which produced wrong data when this + lived in the identity dict: + + - Hooks are short-lived separate processes firing on every tool call, and + people run more than one agent window. A read-modify-write would let each + process mint its own salt, so one repository would hash several ways in the + window before a writer won. + - resolve_distinct_id holds a copy of the identity dict across a network call + to /v1/ping/, so whichever write landed second erased the other's key — + losing either the salt (repo_hash changes mid-stream) or the email (a + second $identify, splitting the person). + - Touching the identity file from record() would create it, and is_first_run + keys off that file, so recording an event would silently suppress the + install event. + + On a read-only or full data directory the fallback is derived from the data + directory path: stable for the machine rather than random per call, so the + failure mode is a weaker salt and not unbounded cardinality in PostHog. + """ + global _salt_cache + if _salt_cache: + return _salt_cache + + path = _salt_path() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + except OSError: + pass + except FileExistsError: + pass + except OSError: + # Cannot persist. Stable-per-machine beats random-per-call. + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache + + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + except OSError: + _salt_cache = "" + if not _salt_cache: + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache def _scoped_digest(value: str, length: int = 16) -> str: diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 1b6bd854e..239836604 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -34,6 +34,7 @@ from typing import Any import memory_core +_salt_cache: str = "" _harness: str = "generic" _source_tag: str = "MEM0_PLUGIN" _PRIVATE_KEYS = { @@ -92,15 +93,60 @@ def _digest(value: str, length: int = 16) -> str: return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _salt_path() -> Path: + return memory_core.data_dir() / "telemetry-salt" + + def _install_salt() -> str: - """Random per-install salt, created on first use and kept in the identity file.""" - identity = _read_identity() - salt = identity.get("salt") - if not salt: - salt = uuid.uuid4().hex - identity["salt"] = salt - _write_identity(identity) - return salt + """Random per-install salt, created once and memoized for the process. + + Deliberately its own file, claimed with O_CREAT|O_EXCL, rather than a key in + the identity file. Three reasons, all of which produced wrong data when this + lived in the identity dict: + + - Hooks are short-lived separate processes firing on every tool call, and + people run more than one agent window. A read-modify-write would let each + process mint its own salt, so one repository would hash several ways in the + window before a writer won. + - resolve_distinct_id holds a copy of the identity dict across a network call + to /v1/ping/, so whichever write landed second erased the other's key — + losing either the salt (repo_hash changes mid-stream) or the email (a + second $identify, splitting the person). + - Touching the identity file from record() would create it, and is_first_run + keys off that file, so recording an event would silently suppress the + install event. + + On a read-only or full data directory the fallback is derived from the data + directory path: stable for the machine rather than random per call, so the + failure mode is a weaker salt and not unbounded cardinality in PostHog. + """ + global _salt_cache + if _salt_cache: + return _salt_cache + + path = _salt_path() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + except OSError: + pass + except FileExistsError: + pass + except OSError: + # Cannot persist. Stable-per-machine beats random-per-call. + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache + + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + except OSError: + _salt_cache = "" + if not _salt_cache: + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache def _scoped_digest(value: str, length: int = 16) -> str: diff --git a/integrations/claude-code-plugin/tests/test_telemetry.py b/integrations/claude-code-plugin/tests/test_telemetry.py index 0ae280b19..eaa741ac5 100644 --- a/integrations/claude-code-plugin/tests/test_telemetry.py +++ b/integrations/claude-code-plugin/tests/test_telemetry.py @@ -1,6 +1,7 @@ from __future__ import annotations import json +import os import sys from pathlib import Path from unittest.mock import patch @@ -273,3 +274,49 @@ def test_spawn_flush_does_nothing_without_a_spool(isolated_env): with patch.object(telemetry.subprocess, "Popen") as popen: assert telemetry.spawn_flush() is True popen.assert_called_once() + + +def test_salt_is_stable_across_processes(isolated_env): + """Hooks are separate short-lived processes; one repo must hash one way. + + An unlocked read-modify-write let each process mint its own salt, so a + repository hashed several ways in the window before one writer won. + """ + import subprocess as sp + + core = str(Path(__file__).resolve().parents[1] / "core") + script = ( + f"import sys; sys.path.insert(0, {core!r})\n" + "import telemetry\n" + "print(telemetry._install_salt())" + ) + env = {**os.environ, "MEM0_CODE_DATA_DIR": str(memory_core.data_dir())} + salts = { + sp.run([sys.executable, "-c", script], capture_output=True, text=True, env=env).stdout.strip() + for _ in range(4) + } + assert len(salts) == 1, f"one repo hashed {len(salts)} ways: {salts}" + + +def test_salt_does_not_touch_the_identity_file(isolated_env): + """The identity file is is_first_run's marker and the sender's email store. + + Writing the salt into it would create it from record(), suppressing the + install event, and would race resolve_distinct_id, which holds a stale copy + of that dict across a network call. + """ + telemetry._install_salt() + assert not telemetry._identity_path().exists() + + +def test_salt_is_stable_when_it_cannot_be_persisted(isolated_env, monkeypatch): + """A read-only data dir must degrade to a weaker salt, not to random-per-call. + + Random per call is unbounded cardinality in PostHog, which is worse than no + salt at all. + """ + telemetry._salt_cache = "" + monkeypatch.setattr(telemetry.os, "open", lambda *a, **k: (_ for _ in ()).throw(OSError("read-only"))) + first = telemetry._install_salt() + telemetry._salt_cache = "" + assert telemetry._install_salt() == first diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 1b6bd854e..239836604 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -34,6 +34,7 @@ from typing import Any import memory_core +_salt_cache: str = "" _harness: str = "generic" _source_tag: str = "MEM0_PLUGIN" _PRIVATE_KEYS = { @@ -92,15 +93,60 @@ def _digest(value: str, length: int = 16) -> str: return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _salt_path() -> Path: + return memory_core.data_dir() / "telemetry-salt" + + def _install_salt() -> str: - """Random per-install salt, created on first use and kept in the identity file.""" - identity = _read_identity() - salt = identity.get("salt") - if not salt: - salt = uuid.uuid4().hex - identity["salt"] = salt - _write_identity(identity) - return salt + """Random per-install salt, created once and memoized for the process. + + Deliberately its own file, claimed with O_CREAT|O_EXCL, rather than a key in + the identity file. Three reasons, all of which produced wrong data when this + lived in the identity dict: + + - Hooks are short-lived separate processes firing on every tool call, and + people run more than one agent window. A read-modify-write would let each + process mint its own salt, so one repository would hash several ways in the + window before a writer won. + - resolve_distinct_id holds a copy of the identity dict across a network call + to /v1/ping/, so whichever write landed second erased the other's key — + losing either the salt (repo_hash changes mid-stream) or the email (a + second $identify, splitting the person). + - Touching the identity file from record() would create it, and is_first_run + keys off that file, so recording an event would silently suppress the + install event. + + On a read-only or full data directory the fallback is derived from the data + directory path: stable for the machine rather than random per call, so the + failure mode is a weaker salt and not unbounded cardinality in PostHog. + """ + global _salt_cache + if _salt_cache: + return _salt_cache + + path = _salt_path() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + except OSError: + pass + except FileExistsError: + pass + except OSError: + # Cannot persist. Stable-per-machine beats random-per-call. + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache + + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + except OSError: + _salt_cache = "" + if not _salt_cache: + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache def _scoped_digest(value: str, length: int = 16) -> str: diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 1b6bd854e..239836604 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -34,6 +34,7 @@ from typing import Any import memory_core +_salt_cache: str = "" _harness: str = "generic" _source_tag: str = "MEM0_PLUGIN" _PRIVATE_KEYS = { @@ -92,15 +93,60 @@ def _digest(value: str, length: int = 16) -> str: return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _salt_path() -> Path: + return memory_core.data_dir() / "telemetry-salt" + + def _install_salt() -> str: - """Random per-install salt, created on first use and kept in the identity file.""" - identity = _read_identity() - salt = identity.get("salt") - if not salt: - salt = uuid.uuid4().hex - identity["salt"] = salt - _write_identity(identity) - return salt + """Random per-install salt, created once and memoized for the process. + + Deliberately its own file, claimed with O_CREAT|O_EXCL, rather than a key in + the identity file. Three reasons, all of which produced wrong data when this + lived in the identity dict: + + - Hooks are short-lived separate processes firing on every tool call, and + people run more than one agent window. A read-modify-write would let each + process mint its own salt, so one repository would hash several ways in the + window before a writer won. + - resolve_distinct_id holds a copy of the identity dict across a network call + to /v1/ping/, so whichever write landed second erased the other's key — + losing either the salt (repo_hash changes mid-stream) or the email (a + second $identify, splitting the person). + - Touching the identity file from record() would create it, and is_first_run + keys off that file, so recording an event would silently suppress the + install event. + + On a read-only or full data directory the fallback is derived from the data + directory path: stable for the machine rather than random per call, so the + failure mode is a weaker salt and not unbounded cardinality in PostHog. + """ + global _salt_cache + if _salt_cache: + return _salt_cache + + path = _salt_path() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + except OSError: + pass + except FileExistsError: + pass + except OSError: + # Cannot persist. Stable-per-machine beats random-per-call. + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache + + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + except OSError: + _salt_cache = "" + if not _salt_cache: + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache def _scoped_digest(value: str, length: int = 16) -> str: diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 1b6bd854e..239836604 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -34,6 +34,7 @@ from typing import Any import memory_core +_salt_cache: str = "" _harness: str = "generic" _source_tag: str = "MEM0_PLUGIN" _PRIVATE_KEYS = { @@ -92,15 +93,60 @@ def _digest(value: str, length: int = 16) -> str: return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _salt_path() -> Path: + return memory_core.data_dir() / "telemetry-salt" + + def _install_salt() -> str: - """Random per-install salt, created on first use and kept in the identity file.""" - identity = _read_identity() - salt = identity.get("salt") - if not salt: - salt = uuid.uuid4().hex - identity["salt"] = salt - _write_identity(identity) - return salt + """Random per-install salt, created once and memoized for the process. + + Deliberately its own file, claimed with O_CREAT|O_EXCL, rather than a key in + the identity file. Three reasons, all of which produced wrong data when this + lived in the identity dict: + + - Hooks are short-lived separate processes firing on every tool call, and + people run more than one agent window. A read-modify-write would let each + process mint its own salt, so one repository would hash several ways in the + window before a writer won. + - resolve_distinct_id holds a copy of the identity dict across a network call + to /v1/ping/, so whichever write landed second erased the other's key — + losing either the salt (repo_hash changes mid-stream) or the email (a + second $identify, splitting the person). + - Touching the identity file from record() would create it, and is_first_run + keys off that file, so recording an event would silently suppress the + install event. + + On a read-only or full data directory the fallback is derived from the data + directory path: stable for the machine rather than random per call, so the + failure mode is a weaker salt and not unbounded cardinality in PostHog. + """ + global _salt_cache + if _salt_cache: + return _salt_cache + + path = _salt_path() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + except OSError: + pass + except FileExistsError: + pass + except OSError: + # Cannot persist. Stable-per-machine beats random-per-call. + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache + + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + except OSError: + _salt_cache = "" + if not _salt_cache: + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache def _scoped_digest(value: str, length: int = 16) -> str: diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 1b6bd854e..239836604 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -34,6 +34,7 @@ from typing import Any import memory_core +_salt_cache: str = "" _harness: str = "generic" _source_tag: str = "MEM0_PLUGIN" _PRIVATE_KEYS = { @@ -92,15 +93,60 @@ def _digest(value: str, length: int = 16) -> str: return hashlib.sha256(value.encode("utf-8")).hexdigest()[:length] +def _salt_path() -> Path: + return memory_core.data_dir() / "telemetry-salt" + + def _install_salt() -> str: - """Random per-install salt, created on first use and kept in the identity file.""" - identity = _read_identity() - salt = identity.get("salt") - if not salt: - salt = uuid.uuid4().hex - identity["salt"] = salt - _write_identity(identity) - return salt + """Random per-install salt, created once and memoized for the process. + + Deliberately its own file, claimed with O_CREAT|O_EXCL, rather than a key in + the identity file. Three reasons, all of which produced wrong data when this + lived in the identity dict: + + - Hooks are short-lived separate processes firing on every tool call, and + people run more than one agent window. A read-modify-write would let each + process mint its own salt, so one repository would hash several ways in the + window before a writer won. + - resolve_distinct_id holds a copy of the identity dict across a network call + to /v1/ping/, so whichever write landed second erased the other's key — + losing either the salt (repo_hash changes mid-stream) or the email (a + second $identify, splitting the person). + - Touching the identity file from record() would create it, and is_first_run + keys off that file, so recording an event would silently suppress the + install event. + + On a read-only or full data directory the fallback is derived from the data + directory path: stable for the machine rather than random per call, so the + failure mode is a weaker salt and not unbounded cardinality in PostHog. + """ + global _salt_cache + if _salt_cache: + return _salt_cache + + path = _salt_path() + try: + path.parent.mkdir(parents=True, exist_ok=True) + handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + try: + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + except OSError: + pass + except FileExistsError: + pass + except OSError: + # Cannot persist. Stable-per-machine beats random-per-call. + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache + + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + except OSError: + _salt_cache = "" + if not _salt_cache: + _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() + return _salt_cache def _scoped_digest(value: str, length: int = 16) -> str: From bd17f2b8c92c315c0250336211725c91f9bcd817 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:30:58 +0530 Subject: [PATCH 07/30] fix(plugins): make the retry budget reachable and the rewrite durable MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review found that the first cut traded the duplicate-delivery bug for a worse one, and disproved its own load-bearing safety claim by experiment. Expiry was unreachable. _claim_parked touched the mtime on every re-claim and _release_claim backdated to exactly now minus the stale threshold, so a file's age hovered around 121 seconds and never approached the 7-day expiry. The attempt count in the filename therefore bounded nothing: an undeliverable batch (revoked key, proxy 403, oversized event) lived on disk forever, and because spawn_flush starts a sender whenever a .sending file exists, it spawned a detached Python process on every hook, MCP call and CLI invocation, forever. The old code self-healed here, so this was a regression. Expiry now gates on the attempt budget, which is the thing that actually accumulates; age stays only as a backstop for files that never carried an attempt marker. The attempt parser sniffed for a leading "a", which also matches a hex id like a1234567, so a legacy telemetry--.sending file parsed as attempt 1234567 and was deleted unsent on the first flush after upgrade — precisely the population this PR is meant to protect. Anchored on field position instead. The rewrite was not durable: no fsync before the rename, and _drain unlinked any claim that parsed to zero events. A crash between write and rename left the claim empty, and the next flush deleted it. Now fsynced, and a non-empty file that parses to nothing is quarantined as .corrupt rather than destroyed. read_text raises UnicodeDecodeError on a torn file, which `except OSError` does not catch. flush() runs from a bare `finally:` in flush_worker, so the exception also skipped the handoff cleanup and left it stuck in .running. The per-batch rewrite's return value was discarded, so a failed rewrite let the loop continue as though progress had been recorded — reintroducing the exact duplicate delivery this PR exists to fix. .partial files orphaned by a crash between write and rename matched no glob in the module and were never cleaned up. Also replaces the heartbeat test, which asserted `SEND_TIMEOUT * 4 < CLAIM_STALE_SECONDS` — two constants, executing none of the code under test. It now drives the real rewrite and watches the mtime move. New tests cover expiry being reachable, legacy filename parsing, torn-claim quarantine, failed-rewrite behaviour and debris sweeping. 64 core tests, 199 host tests. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/telemetry.py | 78 ++++++++++++--- .../tests/test_spool_delivery.py | 98 +++++++++++++++++-- .../antigravity-plugin/core/telemetry.py | 78 ++++++++++++--- .../claude-code-plugin/core/telemetry.py | 78 ++++++++++++--- integrations/codex-plugin/core/telemetry.py | 78 ++++++++++++--- integrations/cursor-plugin/core/telemetry.py | 78 ++++++++++++--- integrations/kimi-plugin/core/telemetry.py | 78 ++++++++++++--- .../mem0-agent-plugin/core/telemetry.py | 78 ++++++++++++--- 8 files changed, 558 insertions(+), 86 deletions(-) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 55ee7c907..fa26cc9a6 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -313,9 +313,18 @@ def _claim_name(attempt: int = 0) -> str: def _claim_attempt(claim: Path) -> int: - """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape. + + Anchored on field position, not on a leading "a": the legacy shape is + ``telemetry--.sending`` and a hex id such as ``a1234567`` would + otherwise parse as attempt 1234567 and be discarded unsent on the first + flush after an upgrade. + """ stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name - tail = stem.rsplit("-", 1)[-1] + parts = stem.split("-") + if len(parts) != 4: + return 0 + tail = parts[3] if tail.startswith("a") and tail[1:].isdigit(): return int(tail[1:]) return 0 @@ -349,6 +358,21 @@ def _claim_spool() -> Path | None: return _claim_parked(directory) +def _sweep_debris(directory: Path) -> None: + """Remove temp files orphaned by a crash between write and rename. + + Neither glob in this module matches *.partial, so nothing else would ever + clean them up. + """ + now = time.time() + for debris in directory.glob("telemetry-*.partial"): + try: + if now - debris.stat().st_mtime > CLAIM_STALE_SECONDS: + debris.unlink() + except OSError: + continue + + def _claim_parked(directory: Path) -> Path | None: """Take the oldest abandoned claim, if any lease has actually expired. @@ -364,7 +388,11 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: + # Attempts, not age. Every re-claim touches the mtime and every release + # backdates it by a fixed amount, so age is pinned near the stale + # threshold and never reaches the expiry. Age stays only as a backstop + # for files that never carried an attempt marker. + if _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS or age > CLAIM_EXPIRY_SECONDS: try: orphan.unlink() except OSError: @@ -406,10 +434,14 @@ def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: return True temporary = claim.with_suffix(f".{os.getpid()}.partial") try: - temporary.write_text( - "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), - encoding="utf-8", - ) + payload = "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining) + # fsync before the rename: without it the rename can land while the + # bytes have not, and the claim comes back empty or truncated after a + # crash. _drain then reads zero events and unlinks it. + with open(temporary, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) temporary.replace(claim) _touch(claim) return True @@ -498,6 +530,7 @@ def flush() -> int: # Parked batches used to starve behind the live spool indefinitely. Bounded # per run so a long backlog cannot turn one flush into an unbounded loop. directory = memory_core.data_dir() + _sweep_debris(directory) for _ in range(MAX_PARKED_PER_RUN): parked = _claim_parked(directory) if parked is None: @@ -518,7 +551,18 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except OSError: + except (OSError, ValueError): + # ValueError covers UnicodeDecodeError from a torn write. Quarantine + # rather than retry: flush() runs from a bare `finally:` in + # flush_worker, so raising here also skips the handoff cleanup, and an + # undecodable file would otherwise be re-read on every flush forever. + try: + claim.replace(claim.with_suffix(".corrupt")) + except OSError: + try: + claim.unlink() + except OSError: + pass return 0, True events = [] for line in lines: @@ -529,8 +573,15 @@ def _drain(claim: Path | None) -> tuple[int, bool]: if isinstance(value, dict) and value.get("event"): events.append(value) if not events: + # Only delete when the file really is empty. A non-empty file that + # parses to nothing is a torn write, and its contents are the unsent + # remainder — deleting it is the data loss this PR exists to prevent. try: - claim.unlink() + empty = claim.stat().st_size == 0 + except OSError: + empty = True + try: + claim.replace(claim.with_suffix(".corrupt")) if not empty else claim.unlink() except OSError: pass return 0, True @@ -580,8 +631,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return sent, False sent += len(chunk) # Record progress and refresh the lease after each successful batch, so - # a crash repeats at most one batch instead of the entire file. - _rewrite_claim(claim, events[start + len(chunk) :]) + # a crash repeats at most one batch instead of the entire file. If the + # rewrite fails the claim still holds delivered events, so stop rather + # than carry on as though progress were recorded — continuing is how the + # duplicate delivery this PR fixes would come back. + if not _rewrite_claim(claim, events[start + len(chunk) :]): + _release_claim(claim, events[start + len(chunk) :]) + return sent, False return sent, True diff --git a/integrations/agent-plugin-core/tests/test_spool_delivery.py b/integrations/agent-plugin-core/tests/test_spool_delivery.py index 754307454..08266cc98 100644 --- a/integrations/agent-plugin-core/tests/test_spool_delivery.py +++ b/integrations/agent-plugin-core/tests/test_spool_delivery.py @@ -112,16 +112,19 @@ def test_a_parked_batch_is_drained_behind_the_live_spool(telemetry): assert names == {"code.parked", "code.fresh"} -def test_an_untried_batch_is_not_expired_by_age_alone(telemetry): - """Expiry should discard what failed, not what never got a turn.""" +def test_a_batch_is_retried_until_the_budget_is_spent_not_discarded(telemetry): + """Expiry discards what failed repeatedly, not what merely sat for a while. + + The budget is the attempt count, because age cannot be one: every re-claim + touches the mtime and every release backdates it, so age never accumulates. + """ telemetry.record("parked") telemetry._post = lambda payload, url: False telemetry.flush() parked = list(telemetry.memory_core.data_dir().glob("telemetry-*.sending")) assert len(parked) == 1 - ancient = time.time() - (telemetry.CLAIM_EXPIRY_SECONDS + 60) - os.utime(parked[0], (ancient, ancient)) + assert telemetry._claim_attempt(parked[0]) < telemetry.MAX_CLAIM_ATTEMPTS sent: list[dict] = [] telemetry._post = lambda payload, url: sent.append(payload) or True @@ -154,11 +157,88 @@ def test_progress_is_recorded_after_every_batch(telemetry): assert json.loads(remaining[0])["properties"]["index"] == 200 -def test_the_heartbeat_stays_well_inside_the_lease(telemetry): +def test_the_heartbeat_actually_refreshes_the_lease(telemetry): """The claim rewrite doubles as the lease heartbeat. - _post makes a single attempt with SEND_TIMEOUT and no retry, so a heartbeat - lands at least that often. If a retry loop is ever added to _post, this is - the assertion that catches a sender losing its claim mid-flight. + Previously asserted `SEND_TIMEOUT * 4 < CLAIM_STALE_SECONDS`, which compares + two constants and executes none of the code under test. Drive the real + rewrite and watch the mtime move instead. """ - assert telemetry.SEND_TIMEOUT * 4 < telemetry.CLAIM_STALE_SECONDS + for index in range(150): + telemetry.record("search", index=index) + claim = telemetry._claim_spool() + assert claim is not None + + stale = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(claim, (stale, stale)) + assert time.time() - claim.stat().st_mtime > telemetry.CLAIM_STALE_SECONDS + + telemetry._rewrite_claim(claim, [{"event": "code.x", "properties": {}}]) + assert time.time() - claim.stat().st_mtime < telemetry.CLAIM_STALE_SECONDS + + +def test_an_undeliverable_batch_is_eventually_given_up_on(telemetry): + """Expiry has to be reachable from a state the state machine can produce. + + It was not: every re-claim touched the mtime and every release backdated it + by a fixed amount, so age hovered near the stale threshold and the 7-day + expiry never fired. An undeliverable batch lived on disk forever, and + spawn_flush saw it and started a sender on every hook. + """ + telemetry.record("doomed") + telemetry._post = lambda payload, url: False + + for _ in range(telemetry.MAX_CLAIM_ATTEMPTS + 3): + telemetry.flush() + + leftover = list(telemetry.memory_core.data_dir().glob("telemetry-*.sending")) + assert leftover == [], f"batch never given up on: {[p.name for p in leftover]}" + + +def test_a_legacy_claim_filename_is_not_mistaken_for_a_huge_attempt_count(telemetry): + """The old shape is telemetry--.sending, and hex can start with 'a'.""" + assert telemetry._claim_attempt(Path("telemetry-999-deadbeef.sending")) == 0 + assert telemetry._claim_attempt(Path("telemetry-999-a1234567.sending")) == 0 + assert telemetry._claim_attempt(Path("telemetry-999-deadbeef-a2.sending")) == 2 + + +def test_a_torn_claim_is_quarantined_not_deleted(telemetry): + """A non-empty file that parses to nothing is the remainder, not garbage.""" + telemetry.record("search") + claim = telemetry._claim_spool() + claim.write_bytes(b"\xff\xfe not utf-8 at all") + stale = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(claim, (stale, stale)) + + sent = telemetry.flush() + + assert sent == 0 + assert not claim.exists() + quarantined = list(telemetry.memory_core.data_dir().glob("*.corrupt")) + assert len(quarantined) == 1, "torn claim was destroyed instead of kept" + + +def test_a_failed_rewrite_stops_instead_of_redelivering(telemetry): + """Ignoring the rewrite result reintroduced the duplicates this PR fixes.""" + for index in range(250): + telemetry.record("search", index=index) + + telemetry._rewrite_claim = lambda claim, remaining: False + delivered = [] + telemetry._post = lambda payload, url: delivered.extend(payload.get("batch", [])) or True + + telemetry.flush() + assert len(delivered) == 100, f"kept going after a failed rewrite: {len(delivered)}" + + +def test_partial_files_are_swept(telemetry): + """Nothing else globs *.partial, so a crash mid-rename orphans one forever.""" + data_dir = telemetry.memory_core.data_dir() + data_dir.mkdir(parents=True, exist_ok=True) + debris = data_dir / "telemetry-1-abc-a0.1.partial" + debris.write_text("x", encoding="utf-8") + old = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(debris, (old, old)) + + telemetry.flush() + assert not debris.exists() diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 55ee7c907..fa26cc9a6 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -313,9 +313,18 @@ def _claim_name(attempt: int = 0) -> str: def _claim_attempt(claim: Path) -> int: - """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape. + + Anchored on field position, not on a leading "a": the legacy shape is + ``telemetry--.sending`` and a hex id such as ``a1234567`` would + otherwise parse as attempt 1234567 and be discarded unsent on the first + flush after an upgrade. + """ stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name - tail = stem.rsplit("-", 1)[-1] + parts = stem.split("-") + if len(parts) != 4: + return 0 + tail = parts[3] if tail.startswith("a") and tail[1:].isdigit(): return int(tail[1:]) return 0 @@ -349,6 +358,21 @@ def _claim_spool() -> Path | None: return _claim_parked(directory) +def _sweep_debris(directory: Path) -> None: + """Remove temp files orphaned by a crash between write and rename. + + Neither glob in this module matches *.partial, so nothing else would ever + clean them up. + """ + now = time.time() + for debris in directory.glob("telemetry-*.partial"): + try: + if now - debris.stat().st_mtime > CLAIM_STALE_SECONDS: + debris.unlink() + except OSError: + continue + + def _claim_parked(directory: Path) -> Path | None: """Take the oldest abandoned claim, if any lease has actually expired. @@ -364,7 +388,11 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: + # Attempts, not age. Every re-claim touches the mtime and every release + # backdates it by a fixed amount, so age is pinned near the stale + # threshold and never reaches the expiry. Age stays only as a backstop + # for files that never carried an attempt marker. + if _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS or age > CLAIM_EXPIRY_SECONDS: try: orphan.unlink() except OSError: @@ -406,10 +434,14 @@ def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: return True temporary = claim.with_suffix(f".{os.getpid()}.partial") try: - temporary.write_text( - "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), - encoding="utf-8", - ) + payload = "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining) + # fsync before the rename: without it the rename can land while the + # bytes have not, and the claim comes back empty or truncated after a + # crash. _drain then reads zero events and unlinks it. + with open(temporary, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) temporary.replace(claim) _touch(claim) return True @@ -498,6 +530,7 @@ def flush() -> int: # Parked batches used to starve behind the live spool indefinitely. Bounded # per run so a long backlog cannot turn one flush into an unbounded loop. directory = memory_core.data_dir() + _sweep_debris(directory) for _ in range(MAX_PARKED_PER_RUN): parked = _claim_parked(directory) if parked is None: @@ -518,7 +551,18 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except OSError: + except (OSError, ValueError): + # ValueError covers UnicodeDecodeError from a torn write. Quarantine + # rather than retry: flush() runs from a bare `finally:` in + # flush_worker, so raising here also skips the handoff cleanup, and an + # undecodable file would otherwise be re-read on every flush forever. + try: + claim.replace(claim.with_suffix(".corrupt")) + except OSError: + try: + claim.unlink() + except OSError: + pass return 0, True events = [] for line in lines: @@ -529,8 +573,15 @@ def _drain(claim: Path | None) -> tuple[int, bool]: if isinstance(value, dict) and value.get("event"): events.append(value) if not events: + # Only delete when the file really is empty. A non-empty file that + # parses to nothing is a torn write, and its contents are the unsent + # remainder — deleting it is the data loss this PR exists to prevent. try: - claim.unlink() + empty = claim.stat().st_size == 0 + except OSError: + empty = True + try: + claim.replace(claim.with_suffix(".corrupt")) if not empty else claim.unlink() except OSError: pass return 0, True @@ -580,8 +631,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return sent, False sent += len(chunk) # Record progress and refresh the lease after each successful batch, so - # a crash repeats at most one batch instead of the entire file. - _rewrite_claim(claim, events[start + len(chunk) :]) + # a crash repeats at most one batch instead of the entire file. If the + # rewrite fails the claim still holds delivered events, so stop rather + # than carry on as though progress were recorded — continuing is how the + # duplicate delivery this PR fixes would come back. + if not _rewrite_claim(claim, events[start + len(chunk) :]): + _release_claim(claim, events[start + len(chunk) :]) + return sent, False return sent, True diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 55ee7c907..fa26cc9a6 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -313,9 +313,18 @@ def _claim_name(attempt: int = 0) -> str: def _claim_attempt(claim: Path) -> int: - """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape. + + Anchored on field position, not on a leading "a": the legacy shape is + ``telemetry--.sending`` and a hex id such as ``a1234567`` would + otherwise parse as attempt 1234567 and be discarded unsent on the first + flush after an upgrade. + """ stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name - tail = stem.rsplit("-", 1)[-1] + parts = stem.split("-") + if len(parts) != 4: + return 0 + tail = parts[3] if tail.startswith("a") and tail[1:].isdigit(): return int(tail[1:]) return 0 @@ -349,6 +358,21 @@ def _claim_spool() -> Path | None: return _claim_parked(directory) +def _sweep_debris(directory: Path) -> None: + """Remove temp files orphaned by a crash between write and rename. + + Neither glob in this module matches *.partial, so nothing else would ever + clean them up. + """ + now = time.time() + for debris in directory.glob("telemetry-*.partial"): + try: + if now - debris.stat().st_mtime > CLAIM_STALE_SECONDS: + debris.unlink() + except OSError: + continue + + def _claim_parked(directory: Path) -> Path | None: """Take the oldest abandoned claim, if any lease has actually expired. @@ -364,7 +388,11 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: + # Attempts, not age. Every re-claim touches the mtime and every release + # backdates it by a fixed amount, so age is pinned near the stale + # threshold and never reaches the expiry. Age stays only as a backstop + # for files that never carried an attempt marker. + if _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS or age > CLAIM_EXPIRY_SECONDS: try: orphan.unlink() except OSError: @@ -406,10 +434,14 @@ def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: return True temporary = claim.with_suffix(f".{os.getpid()}.partial") try: - temporary.write_text( - "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), - encoding="utf-8", - ) + payload = "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining) + # fsync before the rename: without it the rename can land while the + # bytes have not, and the claim comes back empty or truncated after a + # crash. _drain then reads zero events and unlinks it. + with open(temporary, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) temporary.replace(claim) _touch(claim) return True @@ -498,6 +530,7 @@ def flush() -> int: # Parked batches used to starve behind the live spool indefinitely. Bounded # per run so a long backlog cannot turn one flush into an unbounded loop. directory = memory_core.data_dir() + _sweep_debris(directory) for _ in range(MAX_PARKED_PER_RUN): parked = _claim_parked(directory) if parked is None: @@ -518,7 +551,18 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except OSError: + except (OSError, ValueError): + # ValueError covers UnicodeDecodeError from a torn write. Quarantine + # rather than retry: flush() runs from a bare `finally:` in + # flush_worker, so raising here also skips the handoff cleanup, and an + # undecodable file would otherwise be re-read on every flush forever. + try: + claim.replace(claim.with_suffix(".corrupt")) + except OSError: + try: + claim.unlink() + except OSError: + pass return 0, True events = [] for line in lines: @@ -529,8 +573,15 @@ def _drain(claim: Path | None) -> tuple[int, bool]: if isinstance(value, dict) and value.get("event"): events.append(value) if not events: + # Only delete when the file really is empty. A non-empty file that + # parses to nothing is a torn write, and its contents are the unsent + # remainder — deleting it is the data loss this PR exists to prevent. try: - claim.unlink() + empty = claim.stat().st_size == 0 + except OSError: + empty = True + try: + claim.replace(claim.with_suffix(".corrupt")) if not empty else claim.unlink() except OSError: pass return 0, True @@ -580,8 +631,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return sent, False sent += len(chunk) # Record progress and refresh the lease after each successful batch, so - # a crash repeats at most one batch instead of the entire file. - _rewrite_claim(claim, events[start + len(chunk) :]) + # a crash repeats at most one batch instead of the entire file. If the + # rewrite fails the claim still holds delivered events, so stop rather + # than carry on as though progress were recorded — continuing is how the + # duplicate delivery this PR fixes would come back. + if not _rewrite_claim(claim, events[start + len(chunk) :]): + _release_claim(claim, events[start + len(chunk) :]) + return sent, False return sent, True diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 55ee7c907..fa26cc9a6 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -313,9 +313,18 @@ def _claim_name(attempt: int = 0) -> str: def _claim_attempt(claim: Path) -> int: - """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape. + + Anchored on field position, not on a leading "a": the legacy shape is + ``telemetry--.sending`` and a hex id such as ``a1234567`` would + otherwise parse as attempt 1234567 and be discarded unsent on the first + flush after an upgrade. + """ stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name - tail = stem.rsplit("-", 1)[-1] + parts = stem.split("-") + if len(parts) != 4: + return 0 + tail = parts[3] if tail.startswith("a") and tail[1:].isdigit(): return int(tail[1:]) return 0 @@ -349,6 +358,21 @@ def _claim_spool() -> Path | None: return _claim_parked(directory) +def _sweep_debris(directory: Path) -> None: + """Remove temp files orphaned by a crash between write and rename. + + Neither glob in this module matches *.partial, so nothing else would ever + clean them up. + """ + now = time.time() + for debris in directory.glob("telemetry-*.partial"): + try: + if now - debris.stat().st_mtime > CLAIM_STALE_SECONDS: + debris.unlink() + except OSError: + continue + + def _claim_parked(directory: Path) -> Path | None: """Take the oldest abandoned claim, if any lease has actually expired. @@ -364,7 +388,11 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: + # Attempts, not age. Every re-claim touches the mtime and every release + # backdates it by a fixed amount, so age is pinned near the stale + # threshold and never reaches the expiry. Age stays only as a backstop + # for files that never carried an attempt marker. + if _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS or age > CLAIM_EXPIRY_SECONDS: try: orphan.unlink() except OSError: @@ -406,10 +434,14 @@ def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: return True temporary = claim.with_suffix(f".{os.getpid()}.partial") try: - temporary.write_text( - "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), - encoding="utf-8", - ) + payload = "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining) + # fsync before the rename: without it the rename can land while the + # bytes have not, and the claim comes back empty or truncated after a + # crash. _drain then reads zero events and unlinks it. + with open(temporary, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) temporary.replace(claim) _touch(claim) return True @@ -498,6 +530,7 @@ def flush() -> int: # Parked batches used to starve behind the live spool indefinitely. Bounded # per run so a long backlog cannot turn one flush into an unbounded loop. directory = memory_core.data_dir() + _sweep_debris(directory) for _ in range(MAX_PARKED_PER_RUN): parked = _claim_parked(directory) if parked is None: @@ -518,7 +551,18 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except OSError: + except (OSError, ValueError): + # ValueError covers UnicodeDecodeError from a torn write. Quarantine + # rather than retry: flush() runs from a bare `finally:` in + # flush_worker, so raising here also skips the handoff cleanup, and an + # undecodable file would otherwise be re-read on every flush forever. + try: + claim.replace(claim.with_suffix(".corrupt")) + except OSError: + try: + claim.unlink() + except OSError: + pass return 0, True events = [] for line in lines: @@ -529,8 +573,15 @@ def _drain(claim: Path | None) -> tuple[int, bool]: if isinstance(value, dict) and value.get("event"): events.append(value) if not events: + # Only delete when the file really is empty. A non-empty file that + # parses to nothing is a torn write, and its contents are the unsent + # remainder — deleting it is the data loss this PR exists to prevent. try: - claim.unlink() + empty = claim.stat().st_size == 0 + except OSError: + empty = True + try: + claim.replace(claim.with_suffix(".corrupt")) if not empty else claim.unlink() except OSError: pass return 0, True @@ -580,8 +631,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return sent, False sent += len(chunk) # Record progress and refresh the lease after each successful batch, so - # a crash repeats at most one batch instead of the entire file. - _rewrite_claim(claim, events[start + len(chunk) :]) + # a crash repeats at most one batch instead of the entire file. If the + # rewrite fails the claim still holds delivered events, so stop rather + # than carry on as though progress were recorded — continuing is how the + # duplicate delivery this PR fixes would come back. + if not _rewrite_claim(claim, events[start + len(chunk) :]): + _release_claim(claim, events[start + len(chunk) :]) + return sent, False return sent, True diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 55ee7c907..fa26cc9a6 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -313,9 +313,18 @@ def _claim_name(attempt: int = 0) -> str: def _claim_attempt(claim: Path) -> int: - """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape. + + Anchored on field position, not on a leading "a": the legacy shape is + ``telemetry--.sending`` and a hex id such as ``a1234567`` would + otherwise parse as attempt 1234567 and be discarded unsent on the first + flush after an upgrade. + """ stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name - tail = stem.rsplit("-", 1)[-1] + parts = stem.split("-") + if len(parts) != 4: + return 0 + tail = parts[3] if tail.startswith("a") and tail[1:].isdigit(): return int(tail[1:]) return 0 @@ -349,6 +358,21 @@ def _claim_spool() -> Path | None: return _claim_parked(directory) +def _sweep_debris(directory: Path) -> None: + """Remove temp files orphaned by a crash between write and rename. + + Neither glob in this module matches *.partial, so nothing else would ever + clean them up. + """ + now = time.time() + for debris in directory.glob("telemetry-*.partial"): + try: + if now - debris.stat().st_mtime > CLAIM_STALE_SECONDS: + debris.unlink() + except OSError: + continue + + def _claim_parked(directory: Path) -> Path | None: """Take the oldest abandoned claim, if any lease has actually expired. @@ -364,7 +388,11 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: + # Attempts, not age. Every re-claim touches the mtime and every release + # backdates it by a fixed amount, so age is pinned near the stale + # threshold and never reaches the expiry. Age stays only as a backstop + # for files that never carried an attempt marker. + if _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS or age > CLAIM_EXPIRY_SECONDS: try: orphan.unlink() except OSError: @@ -406,10 +434,14 @@ def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: return True temporary = claim.with_suffix(f".{os.getpid()}.partial") try: - temporary.write_text( - "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), - encoding="utf-8", - ) + payload = "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining) + # fsync before the rename: without it the rename can land while the + # bytes have not, and the claim comes back empty or truncated after a + # crash. _drain then reads zero events and unlinks it. + with open(temporary, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) temporary.replace(claim) _touch(claim) return True @@ -498,6 +530,7 @@ def flush() -> int: # Parked batches used to starve behind the live spool indefinitely. Bounded # per run so a long backlog cannot turn one flush into an unbounded loop. directory = memory_core.data_dir() + _sweep_debris(directory) for _ in range(MAX_PARKED_PER_RUN): parked = _claim_parked(directory) if parked is None: @@ -518,7 +551,18 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except OSError: + except (OSError, ValueError): + # ValueError covers UnicodeDecodeError from a torn write. Quarantine + # rather than retry: flush() runs from a bare `finally:` in + # flush_worker, so raising here also skips the handoff cleanup, and an + # undecodable file would otherwise be re-read on every flush forever. + try: + claim.replace(claim.with_suffix(".corrupt")) + except OSError: + try: + claim.unlink() + except OSError: + pass return 0, True events = [] for line in lines: @@ -529,8 +573,15 @@ def _drain(claim: Path | None) -> tuple[int, bool]: if isinstance(value, dict) and value.get("event"): events.append(value) if not events: + # Only delete when the file really is empty. A non-empty file that + # parses to nothing is a torn write, and its contents are the unsent + # remainder — deleting it is the data loss this PR exists to prevent. try: - claim.unlink() + empty = claim.stat().st_size == 0 + except OSError: + empty = True + try: + claim.replace(claim.with_suffix(".corrupt")) if not empty else claim.unlink() except OSError: pass return 0, True @@ -580,8 +631,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return sent, False sent += len(chunk) # Record progress and refresh the lease after each successful batch, so - # a crash repeats at most one batch instead of the entire file. - _rewrite_claim(claim, events[start + len(chunk) :]) + # a crash repeats at most one batch instead of the entire file. If the + # rewrite fails the claim still holds delivered events, so stop rather + # than carry on as though progress were recorded — continuing is how the + # duplicate delivery this PR fixes would come back. + if not _rewrite_claim(claim, events[start + len(chunk) :]): + _release_claim(claim, events[start + len(chunk) :]) + return sent, False return sent, True diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 55ee7c907..fa26cc9a6 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -313,9 +313,18 @@ def _claim_name(attempt: int = 0) -> str: def _claim_attempt(claim: Path) -> int: - """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape. + + Anchored on field position, not on a leading "a": the legacy shape is + ``telemetry--.sending`` and a hex id such as ``a1234567`` would + otherwise parse as attempt 1234567 and be discarded unsent on the first + flush after an upgrade. + """ stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name - tail = stem.rsplit("-", 1)[-1] + parts = stem.split("-") + if len(parts) != 4: + return 0 + tail = parts[3] if tail.startswith("a") and tail[1:].isdigit(): return int(tail[1:]) return 0 @@ -349,6 +358,21 @@ def _claim_spool() -> Path | None: return _claim_parked(directory) +def _sweep_debris(directory: Path) -> None: + """Remove temp files orphaned by a crash between write and rename. + + Neither glob in this module matches *.partial, so nothing else would ever + clean them up. + """ + now = time.time() + for debris in directory.glob("telemetry-*.partial"): + try: + if now - debris.stat().st_mtime > CLAIM_STALE_SECONDS: + debris.unlink() + except OSError: + continue + + def _claim_parked(directory: Path) -> Path | None: """Take the oldest abandoned claim, if any lease has actually expired. @@ -364,7 +388,11 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: + # Attempts, not age. Every re-claim touches the mtime and every release + # backdates it by a fixed amount, so age is pinned near the stale + # threshold and never reaches the expiry. Age stays only as a backstop + # for files that never carried an attempt marker. + if _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS or age > CLAIM_EXPIRY_SECONDS: try: orphan.unlink() except OSError: @@ -406,10 +434,14 @@ def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: return True temporary = claim.with_suffix(f".{os.getpid()}.partial") try: - temporary.write_text( - "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), - encoding="utf-8", - ) + payload = "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining) + # fsync before the rename: without it the rename can land while the + # bytes have not, and the claim comes back empty or truncated after a + # crash. _drain then reads zero events and unlinks it. + with open(temporary, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) temporary.replace(claim) _touch(claim) return True @@ -498,6 +530,7 @@ def flush() -> int: # Parked batches used to starve behind the live spool indefinitely. Bounded # per run so a long backlog cannot turn one flush into an unbounded loop. directory = memory_core.data_dir() + _sweep_debris(directory) for _ in range(MAX_PARKED_PER_RUN): parked = _claim_parked(directory) if parked is None: @@ -518,7 +551,18 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except OSError: + except (OSError, ValueError): + # ValueError covers UnicodeDecodeError from a torn write. Quarantine + # rather than retry: flush() runs from a bare `finally:` in + # flush_worker, so raising here also skips the handoff cleanup, and an + # undecodable file would otherwise be re-read on every flush forever. + try: + claim.replace(claim.with_suffix(".corrupt")) + except OSError: + try: + claim.unlink() + except OSError: + pass return 0, True events = [] for line in lines: @@ -529,8 +573,15 @@ def _drain(claim: Path | None) -> tuple[int, bool]: if isinstance(value, dict) and value.get("event"): events.append(value) if not events: + # Only delete when the file really is empty. A non-empty file that + # parses to nothing is a torn write, and its contents are the unsent + # remainder — deleting it is the data loss this PR exists to prevent. try: - claim.unlink() + empty = claim.stat().st_size == 0 + except OSError: + empty = True + try: + claim.replace(claim.with_suffix(".corrupt")) if not empty else claim.unlink() except OSError: pass return 0, True @@ -580,8 +631,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return sent, False sent += len(chunk) # Record progress and refresh the lease after each successful batch, so - # a crash repeats at most one batch instead of the entire file. - _rewrite_claim(claim, events[start + len(chunk) :]) + # a crash repeats at most one batch instead of the entire file. If the + # rewrite fails the claim still holds delivered events, so stop rather + # than carry on as though progress were recorded — continuing is how the + # duplicate delivery this PR fixes would come back. + if not _rewrite_claim(claim, events[start + len(chunk) :]): + _release_claim(claim, events[start + len(chunk) :]) + return sent, False return sent, True diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 55ee7c907..fa26cc9a6 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -313,9 +313,18 @@ def _claim_name(attempt: int = 0) -> str: def _claim_attempt(claim: Path) -> int: - """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape.""" + """Attempts recorded in a claim filename; 0 for the pre-attempt-count shape. + + Anchored on field position, not on a leading "a": the legacy shape is + ``telemetry--.sending`` and a hex id such as ``a1234567`` would + otherwise parse as attempt 1234567 and be discarded unsent on the first + flush after an upgrade. + """ stem = claim.name[: -len(".sending")] if claim.name.endswith(".sending") else claim.name - tail = stem.rsplit("-", 1)[-1] + parts = stem.split("-") + if len(parts) != 4: + return 0 + tail = parts[3] if tail.startswith("a") and tail[1:].isdigit(): return int(tail[1:]) return 0 @@ -349,6 +358,21 @@ def _claim_spool() -> Path | None: return _claim_parked(directory) +def _sweep_debris(directory: Path) -> None: + """Remove temp files orphaned by a crash between write and rename. + + Neither glob in this module matches *.partial, so nothing else would ever + clean them up. + """ + now = time.time() + for debris in directory.glob("telemetry-*.partial"): + try: + if now - debris.stat().st_mtime > CLAIM_STALE_SECONDS: + debris.unlink() + except OSError: + continue + + def _claim_parked(directory: Path) -> Path | None: """Take the oldest abandoned claim, if any lease has actually expired. @@ -364,7 +388,11 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue - if age > CLAIM_EXPIRY_SECONDS and _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS: + # Attempts, not age. Every re-claim touches the mtime and every release + # backdates it by a fixed amount, so age is pinned near the stale + # threshold and never reaches the expiry. Age stays only as a backstop + # for files that never carried an attempt marker. + if _claim_attempt(orphan) >= MAX_CLAIM_ATTEMPTS or age > CLAIM_EXPIRY_SECONDS: try: orphan.unlink() except OSError: @@ -406,10 +434,14 @@ def _rewrite_claim(claim: Path, remaining: list[dict[str, Any]]) -> bool: return True temporary = claim.with_suffix(f".{os.getpid()}.partial") try: - temporary.write_text( - "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining), - encoding="utf-8", - ) + payload = "".join(json.dumps(event, separators=(",", ":"), default=str) + "\n" for event in remaining) + # fsync before the rename: without it the rename can land while the + # bytes have not, and the claim comes back empty or truncated after a + # crash. _drain then reads zero events and unlinks it. + with open(temporary, "w", encoding="utf-8") as handle: + handle.write(payload) + handle.flush() + os.fsync(handle.fileno()) temporary.replace(claim) _touch(claim) return True @@ -498,6 +530,7 @@ def flush() -> int: # Parked batches used to starve behind the live spool indefinitely. Bounded # per run so a long backlog cannot turn one flush into an unbounded loop. directory = memory_core.data_dir() + _sweep_debris(directory) for _ in range(MAX_PARKED_PER_RUN): parked = _claim_parked(directory) if parked is None: @@ -518,7 +551,18 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except OSError: + except (OSError, ValueError): + # ValueError covers UnicodeDecodeError from a torn write. Quarantine + # rather than retry: flush() runs from a bare `finally:` in + # flush_worker, so raising here also skips the handoff cleanup, and an + # undecodable file would otherwise be re-read on every flush forever. + try: + claim.replace(claim.with_suffix(".corrupt")) + except OSError: + try: + claim.unlink() + except OSError: + pass return 0, True events = [] for line in lines: @@ -529,8 +573,15 @@ def _drain(claim: Path | None) -> tuple[int, bool]: if isinstance(value, dict) and value.get("event"): events.append(value) if not events: + # Only delete when the file really is empty. A non-empty file that + # parses to nothing is a torn write, and its contents are the unsent + # remainder — deleting it is the data loss this PR exists to prevent. try: - claim.unlink() + empty = claim.stat().st_size == 0 + except OSError: + empty = True + try: + claim.replace(claim.with_suffix(".corrupt")) if not empty else claim.unlink() except OSError: pass return 0, True @@ -580,8 +631,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return sent, False sent += len(chunk) # Record progress and refresh the lease after each successful batch, so - # a crash repeats at most one batch instead of the entire file. - _rewrite_claim(claim, events[start + len(chunk) :]) + # a crash repeats at most one batch instead of the entire file. If the + # rewrite fails the claim still holds delivered events, so stop rather + # than carry on as though progress were recorded — continuing is how the + # duplicate delivery this PR fixes would come back. + if not _rewrite_claim(claim, events[start + len(chunk) :]): + _release_claim(claim, events[start + len(chunk) :]) + return sent, False return sent, True From 2c885fdcd7c246f59011ba517e35729bf6606a04 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:31:52 +0530 Subject: [PATCH 08/30] fix(plugins): make code.install reachable, and stop pinging on every flush MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review found the headline fix inverted: code.install could never fire, so every fresh install reported an upgrade and the two cohorts became indistinguishable — strictly worse than the bug being fixed. hook_runner reaches claim_install() only after cache_plugin_api_key() has written `api-key` and EvidenceStore() has created `evidence.sqlite3` and its WAL files. Asking "is the data directory empty" at that point always saw content. The caller now snapshots emptiness at the top of the run, before anything writes, and passes it in. Also caught by review, all in the same file: - claim_version_change was an unsynchronized read-modify-write, so several concurrently starting sessions each observed the old version and each recorded an upgrade. The first session after a version bump is exactly when a user's open agent windows all restart together. The transition is now claimed with an exclusive per-version sentinel. - A crash between O_EXCL and the write left an empty marker, which disabled every future upgrade event on that machine: claim_install saw the file and claim_version_change could not parse it. An unparseable marker is now repaired. - claim_install consumed the one-shot claim even under MEM0_TELEMETRY=false, so a user who opted out for their first sessions would never report install after opting in. - Existing users have an email but no key fingerprint, so the fast path always missed and every flush paid an uncached /v1/ping/ — a 5s timeout each time for the offline users this stack keeps citing. Legacy rows now adopt the current key's fingerprint instead of re-resolving. - A key that will not resolve (revoked, offline) kept attributing to the previous account's email, which is the bug this was meant to fix. It now falls back to the anonymous id. - The anonymous id was never rotated, so once it had been merged into one account it was still offered as the alias for the next one. An alias naming an already-identified id is what could link two real people; it is now offered once. The gap that let this ship was that no test drove hook_runner's session-start path — the decision was only ever tested by calling claim_install() directly on a directory nothing had touched. Adds subprocess tests that run the real entrypoint: fresh install, exactly-once, and an existing data dir. 62 core tests, 203 host tests. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/hook_runner.py | 7 +- .../agent-plugin-core/python/telemetry.py | 87 ++++++++++++++++--- .../tests/test_uninitialised_identity.py | 68 +++++++++++++++ .../antigravity-plugin/core/hook_runner.py | 7 +- .../antigravity-plugin/core/telemetry.py | 87 ++++++++++++++++--- .../claude-code-plugin/core/hook_runner.py | 7 +- .../claude-code-plugin/core/telemetry.py | 87 ++++++++++++++++--- integrations/codex-plugin/core/hook_runner.py | 7 +- integrations/codex-plugin/core/telemetry.py | 87 ++++++++++++++++--- .../cursor-plugin/core/hook_runner.py | 7 +- integrations/cursor-plugin/core/telemetry.py | 87 ++++++++++++++++--- integrations/kimi-plugin/core/hook_runner.py | 7 +- integrations/kimi-plugin/core/telemetry.py | 87 ++++++++++++++++--- .../mem0-agent-plugin/core/telemetry.py | 87 ++++++++++++++++--- 14 files changed, 636 insertions(+), 83 deletions(-) diff --git a/integrations/agent-plugin-core/python/hook_runner.py b/integrations/agent-plugin-core/python/hook_runner.py index 559702102..b3d8a3210 100644 --- a/integrations/agent-plugin-core/python/hook_runner.py +++ b/integrations/agent-plugin-core/python/hook_runner.py @@ -290,6 +290,11 @@ def run( if args.plugin_data_dir: os.environ[data_dir_env] = args.plugin_data_dir + # Snapshot BEFORE anything writes to the data dir: cache_plugin_api_key + # writes `api-key` and EvidenceStore creates `evidence.sqlite3`, so asking + # after them always saw content and every fresh install reported an upgrade. + data_dir_was_empty = telemetry.data_dir_was_empty() + cache_plugin_api_key() if args.action == "session-start": clear_stale_api_key_cache() @@ -307,7 +312,7 @@ def run( if args.action == "session-start": # Claims the marker atomically and says which event to record, so a # second session starting alongside this one cannot record it too. - first_event = telemetry.claim_install() + first_event = telemetry.claim_install(was_empty=data_dir_was_empty) if first_event == "install": telemetry.record("install") elif first_event == "upgrade": diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index d7933bfbc..a24c97264 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -221,18 +221,35 @@ def is_first_run() -> bool: return not _install_state_path().exists() -def claim_install() -> str | None: +def data_dir_was_empty() -> bool: + """Whether the data directory is untouched. Call BEFORE anything writes to it. + + hook_runner reaches claim_install() only after cache_plugin_api_key() has + written `api-key` and EvidenceStore() has created `evidence.sqlite3`, so + asking at claim time always saw content and every fresh install reported an + upgrade. The caller snapshots this at the top of the run instead. + """ + return not _data_dir_has_content() + + +def claim_install(was_empty: bool | None = None) -> str | None: """Claim the one install/upgrade record for this machine, atomically. Returns the event to record ("install" or "upgrade"), or None if another session already claimed it. O_CREAT|O_EXCL so two sessions starting together cannot both win. + + `was_empty` must come from data_dir_was_empty() called before this process + wrote anything. Omitting it falls back to checking now, which is only + correct for a caller that has touched nothing. """ + if not is_enabled(): + # Never consume the one-shot claim while the user is opted out, or they + # would silently lose their install event if they later opt in. + return None + path = _install_state_path() - # A fresh install has an empty data directory. Anything already there — - # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read - # before the marker is created, since creating it would itself be content. - upgrading = _data_dir_has_content() + upgrading = not (data_dir_was_empty() if was_empty is None else was_empty) try: path.parent.mkdir(parents=True, exist_ok=True) handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) @@ -266,6 +283,19 @@ def _data_dir_has_content() -> bool: return False +def _repair_install_state(path: Path) -> None: + """Rewrite an unparseable marker so version tracking can resume.""" + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text( + json.dumps({"plugin_version": memory_core.PLUGIN_VERSION, "repaired_at": memory_core.utc_now()}), + encoding="utf-8", + ) + temporary.replace(path) + except OSError: + pass + + def claim_version_change() -> str | None: """Return the previously recorded version if it differs, updating the marker. @@ -276,13 +306,32 @@ def claim_version_change() -> str | None: path = _install_state_path() try: state = json.loads(path.read_text(encoding="utf-8")) - except (OSError, json.JSONDecodeError): + except OSError: return None + except json.JSONDecodeError: + # A crash between O_EXCL and the write leaves an empty marker. Left + # alone it disables every future upgrade event on this machine, because + # claim_install sees the file and this function cannot parse it. + state = None if not isinstance(state, dict): + _repair_install_state(path) return None previous = str(state.get("plugin_version") or "") if not previous or previous == memory_core.PLUGIN_VERSION: return None + # Claim the transition with an exclusive sentinel before rewriting the + # marker. A plain read-modify-write let every concurrently starting session + # observe the old version and each record its own upgrade — and the first + # session after a version bump is exactly when several agent windows restart + # together. + sentinel = path.with_name(f"upgraded-{memory_core.PLUGIN_VERSION}") + try: + os.close(os.open(sentinel, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)) + except FileExistsError: + return None + except OSError: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() try: @@ -563,8 +612,18 @@ def resolve_distinct_id() -> tuple[str, str]: fingerprint = _digest(key) if key else "" email = identity.get("email", "") - if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: - return email, "" + if email and fingerprint: + recorded = identity.get("key_fingerprint", "") + if recorded == fingerprint: + return email, "" + if not recorded: + # Rows written before fingerprints existed. Adopt the current key + # rather than re-resolving: otherwise every existing user pays an + # uncached /v1/ping/ on every flush, forever, and a firewalled one + # pays the full timeout each time. + identity["key_fingerprint"] = fingerprint + _write_identity(identity) + return email, "" if not key: # No key to verify the account with; do not keep attributing to it. @@ -576,10 +635,16 @@ def resolve_distinct_id() -> tuple[str, str]: resolved = _resolve_email(key) if not resolved: - return (email, "") if email else (anonymous_id(identity), "") + # The key changed and will not resolve (revoked, offline, API down). + # Do not keep attributing to the previous account. + return anonymous_id(identity), "" - # Alias only when going anonymous -> email for the first time. - previous = "" if email else identity.get("anonymous_id", "") + # Alias only when going anonymous -> email for the first time. Once an anon + # id has been merged into an account it must never be offered again: an + # alias naming an already-identified id is what could link two real people. + previous = "" if (email or identity.get("aliased")) else identity.get("anonymous_id", "") + if previous: + identity["aliased"] = True identity["email"] = resolved identity["key_fingerprint"] = fingerprint _write_identity(identity) diff --git a/integrations/agent-plugin-core/tests/test_uninitialised_identity.py b/integrations/agent-plugin-core/tests/test_uninitialised_identity.py index 14f911bee..7d48dbcc3 100644 --- a/integrations/agent-plugin-core/tests/test_uninitialised_identity.py +++ b/integrations/agent-plugin-core/tests/test_uninitialised_identity.py @@ -177,3 +177,71 @@ def test_source_tag_defaults_agree_between_the_two_modules(): ) left, right = out.split() assert left == right == "KIMI_PLUGIN" + + +def _session_start(core: Path, data_dir: Path) -> list[str]: + """Drive the real hook_runner session-start path and return lifecycle events.""" + recorded = "\n".join( + [ + "import io, json, sys", + f"sys.path.insert(0, {str(core)!r})", + "import telemetry, hook_runner", + "seen = []", + "telemetry.record = lambda event, **kw: seen.append(event) or None", + "telemetry.spawn_flush = lambda: False", + # run() reads sys.argv through argparse; it takes no positional args. + "sys.argv = ['hook_runner', 'session-start']", + "sys.stdin = io.StringIO('{}')", + "hook_runner.run()", + "print(json.dumps([e for e in seen if e in ('install', 'upgrade')]))", + ] + ) + import json as _json + + return _json.loads(_run(core, data_dir, recorded) or "[]") + + +def test_a_fresh_install_reports_install_not_upgrade(): + """The decision must survive the writes hook_runner does before asking. + + claim_install() is reached only after cache_plugin_api_key() has written + `api-key` and EvidenceStore() has created `evidence.sqlite3`. Asking "is the + data dir empty" at that point always saw content, so code.install could + never fire and every new user was counted as an upgrade. + """ + core = _core_dir("claude-code-plugin") + if not core.exists(): + pytest.skip("claude-code-plugin is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + data_dir = Path(tmp) / "data" + assert _session_start(core, data_dir) == ["install"] + + +def test_the_lifecycle_event_fires_exactly_once(): + core = _core_dir("claude-code-plugin") + if not core.exists(): + pytest.skip("claude-code-plugin is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + data_dir = Path(tmp) / "data" + first = _session_start(core, data_dir) + second = _session_start(core, data_dir) + third = _session_start(core, data_dir) + + assert first == ["install"] + assert second == [] + assert third == [] + + +def test_an_existing_data_dir_reports_upgrade(): + core = _core_dir("claude-code-plugin") + if not core.exists(): + pytest.skip("claude-code-plugin is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + data_dir = Path(tmp) / "data" + data_dir.mkdir(parents=True) + # A 0.2.x leftover: the data dir survives the upgrade. + (data_dir / "requirements.txt").write_text("mem0ai\n", encoding="utf-8") + assert _session_start(core, data_dir) == ["upgrade"] diff --git a/integrations/antigravity-plugin/core/hook_runner.py b/integrations/antigravity-plugin/core/hook_runner.py index 559702102..b3d8a3210 100644 --- a/integrations/antigravity-plugin/core/hook_runner.py +++ b/integrations/antigravity-plugin/core/hook_runner.py @@ -290,6 +290,11 @@ def run( if args.plugin_data_dir: os.environ[data_dir_env] = args.plugin_data_dir + # Snapshot BEFORE anything writes to the data dir: cache_plugin_api_key + # writes `api-key` and EvidenceStore creates `evidence.sqlite3`, so asking + # after them always saw content and every fresh install reported an upgrade. + data_dir_was_empty = telemetry.data_dir_was_empty() + cache_plugin_api_key() if args.action == "session-start": clear_stale_api_key_cache() @@ -307,7 +312,7 @@ def run( if args.action == "session-start": # Claims the marker atomically and says which event to record, so a # second session starting alongside this one cannot record it too. - first_event = telemetry.claim_install() + first_event = telemetry.claim_install(was_empty=data_dir_was_empty) if first_event == "install": telemetry.record("install") elif first_event == "upgrade": diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index d7933bfbc..a24c97264 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -221,18 +221,35 @@ def is_first_run() -> bool: return not _install_state_path().exists() -def claim_install() -> str | None: +def data_dir_was_empty() -> bool: + """Whether the data directory is untouched. Call BEFORE anything writes to it. + + hook_runner reaches claim_install() only after cache_plugin_api_key() has + written `api-key` and EvidenceStore() has created `evidence.sqlite3`, so + asking at claim time always saw content and every fresh install reported an + upgrade. The caller snapshots this at the top of the run instead. + """ + return not _data_dir_has_content() + + +def claim_install(was_empty: bool | None = None) -> str | None: """Claim the one install/upgrade record for this machine, atomically. Returns the event to record ("install" or "upgrade"), or None if another session already claimed it. O_CREAT|O_EXCL so two sessions starting together cannot both win. + + `was_empty` must come from data_dir_was_empty() called before this process + wrote anything. Omitting it falls back to checking now, which is only + correct for a caller that has touched nothing. """ + if not is_enabled(): + # Never consume the one-shot claim while the user is opted out, or they + # would silently lose their install event if they later opt in. + return None + path = _install_state_path() - # A fresh install has an empty data directory. Anything already there — - # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read - # before the marker is created, since creating it would itself be content. - upgrading = _data_dir_has_content() + upgrading = not (data_dir_was_empty() if was_empty is None else was_empty) try: path.parent.mkdir(parents=True, exist_ok=True) handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) @@ -266,6 +283,19 @@ def _data_dir_has_content() -> bool: return False +def _repair_install_state(path: Path) -> None: + """Rewrite an unparseable marker so version tracking can resume.""" + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text( + json.dumps({"plugin_version": memory_core.PLUGIN_VERSION, "repaired_at": memory_core.utc_now()}), + encoding="utf-8", + ) + temporary.replace(path) + except OSError: + pass + + def claim_version_change() -> str | None: """Return the previously recorded version if it differs, updating the marker. @@ -276,13 +306,32 @@ def claim_version_change() -> str | None: path = _install_state_path() try: state = json.loads(path.read_text(encoding="utf-8")) - except (OSError, json.JSONDecodeError): + except OSError: return None + except json.JSONDecodeError: + # A crash between O_EXCL and the write leaves an empty marker. Left + # alone it disables every future upgrade event on this machine, because + # claim_install sees the file and this function cannot parse it. + state = None if not isinstance(state, dict): + _repair_install_state(path) return None previous = str(state.get("plugin_version") or "") if not previous or previous == memory_core.PLUGIN_VERSION: return None + # Claim the transition with an exclusive sentinel before rewriting the + # marker. A plain read-modify-write let every concurrently starting session + # observe the old version and each record its own upgrade — and the first + # session after a version bump is exactly when several agent windows restart + # together. + sentinel = path.with_name(f"upgraded-{memory_core.PLUGIN_VERSION}") + try: + os.close(os.open(sentinel, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)) + except FileExistsError: + return None + except OSError: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() try: @@ -563,8 +612,18 @@ def resolve_distinct_id() -> tuple[str, str]: fingerprint = _digest(key) if key else "" email = identity.get("email", "") - if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: - return email, "" + if email and fingerprint: + recorded = identity.get("key_fingerprint", "") + if recorded == fingerprint: + return email, "" + if not recorded: + # Rows written before fingerprints existed. Adopt the current key + # rather than re-resolving: otherwise every existing user pays an + # uncached /v1/ping/ on every flush, forever, and a firewalled one + # pays the full timeout each time. + identity["key_fingerprint"] = fingerprint + _write_identity(identity) + return email, "" if not key: # No key to verify the account with; do not keep attributing to it. @@ -576,10 +635,16 @@ def resolve_distinct_id() -> tuple[str, str]: resolved = _resolve_email(key) if not resolved: - return (email, "") if email else (anonymous_id(identity), "") + # The key changed and will not resolve (revoked, offline, API down). + # Do not keep attributing to the previous account. + return anonymous_id(identity), "" - # Alias only when going anonymous -> email for the first time. - previous = "" if email else identity.get("anonymous_id", "") + # Alias only when going anonymous -> email for the first time. Once an anon + # id has been merged into an account it must never be offered again: an + # alias naming an already-identified id is what could link two real people. + previous = "" if (email or identity.get("aliased")) else identity.get("anonymous_id", "") + if previous: + identity["aliased"] = True identity["email"] = resolved identity["key_fingerprint"] = fingerprint _write_identity(identity) diff --git a/integrations/claude-code-plugin/core/hook_runner.py b/integrations/claude-code-plugin/core/hook_runner.py index 559702102..b3d8a3210 100644 --- a/integrations/claude-code-plugin/core/hook_runner.py +++ b/integrations/claude-code-plugin/core/hook_runner.py @@ -290,6 +290,11 @@ def run( if args.plugin_data_dir: os.environ[data_dir_env] = args.plugin_data_dir + # Snapshot BEFORE anything writes to the data dir: cache_plugin_api_key + # writes `api-key` and EvidenceStore creates `evidence.sqlite3`, so asking + # after them always saw content and every fresh install reported an upgrade. + data_dir_was_empty = telemetry.data_dir_was_empty() + cache_plugin_api_key() if args.action == "session-start": clear_stale_api_key_cache() @@ -307,7 +312,7 @@ def run( if args.action == "session-start": # Claims the marker atomically and says which event to record, so a # second session starting alongside this one cannot record it too. - first_event = telemetry.claim_install() + first_event = telemetry.claim_install(was_empty=data_dir_was_empty) if first_event == "install": telemetry.record("install") elif first_event == "upgrade": diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index d7933bfbc..a24c97264 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -221,18 +221,35 @@ def is_first_run() -> bool: return not _install_state_path().exists() -def claim_install() -> str | None: +def data_dir_was_empty() -> bool: + """Whether the data directory is untouched. Call BEFORE anything writes to it. + + hook_runner reaches claim_install() only after cache_plugin_api_key() has + written `api-key` and EvidenceStore() has created `evidence.sqlite3`, so + asking at claim time always saw content and every fresh install reported an + upgrade. The caller snapshots this at the top of the run instead. + """ + return not _data_dir_has_content() + + +def claim_install(was_empty: bool | None = None) -> str | None: """Claim the one install/upgrade record for this machine, atomically. Returns the event to record ("install" or "upgrade"), or None if another session already claimed it. O_CREAT|O_EXCL so two sessions starting together cannot both win. + + `was_empty` must come from data_dir_was_empty() called before this process + wrote anything. Omitting it falls back to checking now, which is only + correct for a caller that has touched nothing. """ + if not is_enabled(): + # Never consume the one-shot claim while the user is opted out, or they + # would silently lose their install event if they later opt in. + return None + path = _install_state_path() - # A fresh install has an empty data directory. Anything already there — - # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read - # before the marker is created, since creating it would itself be content. - upgrading = _data_dir_has_content() + upgrading = not (data_dir_was_empty() if was_empty is None else was_empty) try: path.parent.mkdir(parents=True, exist_ok=True) handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) @@ -266,6 +283,19 @@ def _data_dir_has_content() -> bool: return False +def _repair_install_state(path: Path) -> None: + """Rewrite an unparseable marker so version tracking can resume.""" + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text( + json.dumps({"plugin_version": memory_core.PLUGIN_VERSION, "repaired_at": memory_core.utc_now()}), + encoding="utf-8", + ) + temporary.replace(path) + except OSError: + pass + + def claim_version_change() -> str | None: """Return the previously recorded version if it differs, updating the marker. @@ -276,13 +306,32 @@ def claim_version_change() -> str | None: path = _install_state_path() try: state = json.loads(path.read_text(encoding="utf-8")) - except (OSError, json.JSONDecodeError): + except OSError: return None + except json.JSONDecodeError: + # A crash between O_EXCL and the write leaves an empty marker. Left + # alone it disables every future upgrade event on this machine, because + # claim_install sees the file and this function cannot parse it. + state = None if not isinstance(state, dict): + _repair_install_state(path) return None previous = str(state.get("plugin_version") or "") if not previous or previous == memory_core.PLUGIN_VERSION: return None + # Claim the transition with an exclusive sentinel before rewriting the + # marker. A plain read-modify-write let every concurrently starting session + # observe the old version and each record its own upgrade — and the first + # session after a version bump is exactly when several agent windows restart + # together. + sentinel = path.with_name(f"upgraded-{memory_core.PLUGIN_VERSION}") + try: + os.close(os.open(sentinel, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)) + except FileExistsError: + return None + except OSError: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() try: @@ -563,8 +612,18 @@ def resolve_distinct_id() -> tuple[str, str]: fingerprint = _digest(key) if key else "" email = identity.get("email", "") - if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: - return email, "" + if email and fingerprint: + recorded = identity.get("key_fingerprint", "") + if recorded == fingerprint: + return email, "" + if not recorded: + # Rows written before fingerprints existed. Adopt the current key + # rather than re-resolving: otherwise every existing user pays an + # uncached /v1/ping/ on every flush, forever, and a firewalled one + # pays the full timeout each time. + identity["key_fingerprint"] = fingerprint + _write_identity(identity) + return email, "" if not key: # No key to verify the account with; do not keep attributing to it. @@ -576,10 +635,16 @@ def resolve_distinct_id() -> tuple[str, str]: resolved = _resolve_email(key) if not resolved: - return (email, "") if email else (anonymous_id(identity), "") + # The key changed and will not resolve (revoked, offline, API down). + # Do not keep attributing to the previous account. + return anonymous_id(identity), "" - # Alias only when going anonymous -> email for the first time. - previous = "" if email else identity.get("anonymous_id", "") + # Alias only when going anonymous -> email for the first time. Once an anon + # id has been merged into an account it must never be offered again: an + # alias naming an already-identified id is what could link two real people. + previous = "" if (email or identity.get("aliased")) else identity.get("anonymous_id", "") + if previous: + identity["aliased"] = True identity["email"] = resolved identity["key_fingerprint"] = fingerprint _write_identity(identity) diff --git a/integrations/codex-plugin/core/hook_runner.py b/integrations/codex-plugin/core/hook_runner.py index 559702102..b3d8a3210 100644 --- a/integrations/codex-plugin/core/hook_runner.py +++ b/integrations/codex-plugin/core/hook_runner.py @@ -290,6 +290,11 @@ def run( if args.plugin_data_dir: os.environ[data_dir_env] = args.plugin_data_dir + # Snapshot BEFORE anything writes to the data dir: cache_plugin_api_key + # writes `api-key` and EvidenceStore creates `evidence.sqlite3`, so asking + # after them always saw content and every fresh install reported an upgrade. + data_dir_was_empty = telemetry.data_dir_was_empty() + cache_plugin_api_key() if args.action == "session-start": clear_stale_api_key_cache() @@ -307,7 +312,7 @@ def run( if args.action == "session-start": # Claims the marker atomically and says which event to record, so a # second session starting alongside this one cannot record it too. - first_event = telemetry.claim_install() + first_event = telemetry.claim_install(was_empty=data_dir_was_empty) if first_event == "install": telemetry.record("install") elif first_event == "upgrade": diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index d7933bfbc..a24c97264 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -221,18 +221,35 @@ def is_first_run() -> bool: return not _install_state_path().exists() -def claim_install() -> str | None: +def data_dir_was_empty() -> bool: + """Whether the data directory is untouched. Call BEFORE anything writes to it. + + hook_runner reaches claim_install() only after cache_plugin_api_key() has + written `api-key` and EvidenceStore() has created `evidence.sqlite3`, so + asking at claim time always saw content and every fresh install reported an + upgrade. The caller snapshots this at the top of the run instead. + """ + return not _data_dir_has_content() + + +def claim_install(was_empty: bool | None = None) -> str | None: """Claim the one install/upgrade record for this machine, atomically. Returns the event to record ("install" or "upgrade"), or None if another session already claimed it. O_CREAT|O_EXCL so two sessions starting together cannot both win. + + `was_empty` must come from data_dir_was_empty() called before this process + wrote anything. Omitting it falls back to checking now, which is only + correct for a caller that has touched nothing. """ + if not is_enabled(): + # Never consume the one-shot claim while the user is opted out, or they + # would silently lose their install event if they later opt in. + return None + path = _install_state_path() - # A fresh install has an empty data directory. Anything already there — - # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read - # before the marker is created, since creating it would itself be content. - upgrading = _data_dir_has_content() + upgrading = not (data_dir_was_empty() if was_empty is None else was_empty) try: path.parent.mkdir(parents=True, exist_ok=True) handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) @@ -266,6 +283,19 @@ def _data_dir_has_content() -> bool: return False +def _repair_install_state(path: Path) -> None: + """Rewrite an unparseable marker so version tracking can resume.""" + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text( + json.dumps({"plugin_version": memory_core.PLUGIN_VERSION, "repaired_at": memory_core.utc_now()}), + encoding="utf-8", + ) + temporary.replace(path) + except OSError: + pass + + def claim_version_change() -> str | None: """Return the previously recorded version if it differs, updating the marker. @@ -276,13 +306,32 @@ def claim_version_change() -> str | None: path = _install_state_path() try: state = json.loads(path.read_text(encoding="utf-8")) - except (OSError, json.JSONDecodeError): + except OSError: return None + except json.JSONDecodeError: + # A crash between O_EXCL and the write leaves an empty marker. Left + # alone it disables every future upgrade event on this machine, because + # claim_install sees the file and this function cannot parse it. + state = None if not isinstance(state, dict): + _repair_install_state(path) return None previous = str(state.get("plugin_version") or "") if not previous or previous == memory_core.PLUGIN_VERSION: return None + # Claim the transition with an exclusive sentinel before rewriting the + # marker. A plain read-modify-write let every concurrently starting session + # observe the old version and each record its own upgrade — and the first + # session after a version bump is exactly when several agent windows restart + # together. + sentinel = path.with_name(f"upgraded-{memory_core.PLUGIN_VERSION}") + try: + os.close(os.open(sentinel, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)) + except FileExistsError: + return None + except OSError: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() try: @@ -563,8 +612,18 @@ def resolve_distinct_id() -> tuple[str, str]: fingerprint = _digest(key) if key else "" email = identity.get("email", "") - if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: - return email, "" + if email and fingerprint: + recorded = identity.get("key_fingerprint", "") + if recorded == fingerprint: + return email, "" + if not recorded: + # Rows written before fingerprints existed. Adopt the current key + # rather than re-resolving: otherwise every existing user pays an + # uncached /v1/ping/ on every flush, forever, and a firewalled one + # pays the full timeout each time. + identity["key_fingerprint"] = fingerprint + _write_identity(identity) + return email, "" if not key: # No key to verify the account with; do not keep attributing to it. @@ -576,10 +635,16 @@ def resolve_distinct_id() -> tuple[str, str]: resolved = _resolve_email(key) if not resolved: - return (email, "") if email else (anonymous_id(identity), "") + # The key changed and will not resolve (revoked, offline, API down). + # Do not keep attributing to the previous account. + return anonymous_id(identity), "" - # Alias only when going anonymous -> email for the first time. - previous = "" if email else identity.get("anonymous_id", "") + # Alias only when going anonymous -> email for the first time. Once an anon + # id has been merged into an account it must never be offered again: an + # alias naming an already-identified id is what could link two real people. + previous = "" if (email or identity.get("aliased")) else identity.get("anonymous_id", "") + if previous: + identity["aliased"] = True identity["email"] = resolved identity["key_fingerprint"] = fingerprint _write_identity(identity) diff --git a/integrations/cursor-plugin/core/hook_runner.py b/integrations/cursor-plugin/core/hook_runner.py index 559702102..b3d8a3210 100644 --- a/integrations/cursor-plugin/core/hook_runner.py +++ b/integrations/cursor-plugin/core/hook_runner.py @@ -290,6 +290,11 @@ def run( if args.plugin_data_dir: os.environ[data_dir_env] = args.plugin_data_dir + # Snapshot BEFORE anything writes to the data dir: cache_plugin_api_key + # writes `api-key` and EvidenceStore creates `evidence.sqlite3`, so asking + # after them always saw content and every fresh install reported an upgrade. + data_dir_was_empty = telemetry.data_dir_was_empty() + cache_plugin_api_key() if args.action == "session-start": clear_stale_api_key_cache() @@ -307,7 +312,7 @@ def run( if args.action == "session-start": # Claims the marker atomically and says which event to record, so a # second session starting alongside this one cannot record it too. - first_event = telemetry.claim_install() + first_event = telemetry.claim_install(was_empty=data_dir_was_empty) if first_event == "install": telemetry.record("install") elif first_event == "upgrade": diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index d7933bfbc..a24c97264 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -221,18 +221,35 @@ def is_first_run() -> bool: return not _install_state_path().exists() -def claim_install() -> str | None: +def data_dir_was_empty() -> bool: + """Whether the data directory is untouched. Call BEFORE anything writes to it. + + hook_runner reaches claim_install() only after cache_plugin_api_key() has + written `api-key` and EvidenceStore() has created `evidence.sqlite3`, so + asking at claim time always saw content and every fresh install reported an + upgrade. The caller snapshots this at the top of the run instead. + """ + return not _data_dir_has_content() + + +def claim_install(was_empty: bool | None = None) -> str | None: """Claim the one install/upgrade record for this machine, atomically. Returns the event to record ("install" or "upgrade"), or None if another session already claimed it. O_CREAT|O_EXCL so two sessions starting together cannot both win. + + `was_empty` must come from data_dir_was_empty() called before this process + wrote anything. Omitting it falls back to checking now, which is only + correct for a caller that has touched nothing. """ + if not is_enabled(): + # Never consume the one-shot claim while the user is opted out, or they + # would silently lose their install event if they later opt in. + return None + path = _install_state_path() - # A fresh install has an empty data directory. Anything already there — - # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read - # before the marker is created, since creating it would itself be content. - upgrading = _data_dir_has_content() + upgrading = not (data_dir_was_empty() if was_empty is None else was_empty) try: path.parent.mkdir(parents=True, exist_ok=True) handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) @@ -266,6 +283,19 @@ def _data_dir_has_content() -> bool: return False +def _repair_install_state(path: Path) -> None: + """Rewrite an unparseable marker so version tracking can resume.""" + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text( + json.dumps({"plugin_version": memory_core.PLUGIN_VERSION, "repaired_at": memory_core.utc_now()}), + encoding="utf-8", + ) + temporary.replace(path) + except OSError: + pass + + def claim_version_change() -> str | None: """Return the previously recorded version if it differs, updating the marker. @@ -276,13 +306,32 @@ def claim_version_change() -> str | None: path = _install_state_path() try: state = json.loads(path.read_text(encoding="utf-8")) - except (OSError, json.JSONDecodeError): + except OSError: return None + except json.JSONDecodeError: + # A crash between O_EXCL and the write leaves an empty marker. Left + # alone it disables every future upgrade event on this machine, because + # claim_install sees the file and this function cannot parse it. + state = None if not isinstance(state, dict): + _repair_install_state(path) return None previous = str(state.get("plugin_version") or "") if not previous or previous == memory_core.PLUGIN_VERSION: return None + # Claim the transition with an exclusive sentinel before rewriting the + # marker. A plain read-modify-write let every concurrently starting session + # observe the old version and each record its own upgrade — and the first + # session after a version bump is exactly when several agent windows restart + # together. + sentinel = path.with_name(f"upgraded-{memory_core.PLUGIN_VERSION}") + try: + os.close(os.open(sentinel, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)) + except FileExistsError: + return None + except OSError: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() try: @@ -563,8 +612,18 @@ def resolve_distinct_id() -> tuple[str, str]: fingerprint = _digest(key) if key else "" email = identity.get("email", "") - if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: - return email, "" + if email and fingerprint: + recorded = identity.get("key_fingerprint", "") + if recorded == fingerprint: + return email, "" + if not recorded: + # Rows written before fingerprints existed. Adopt the current key + # rather than re-resolving: otherwise every existing user pays an + # uncached /v1/ping/ on every flush, forever, and a firewalled one + # pays the full timeout each time. + identity["key_fingerprint"] = fingerprint + _write_identity(identity) + return email, "" if not key: # No key to verify the account with; do not keep attributing to it. @@ -576,10 +635,16 @@ def resolve_distinct_id() -> tuple[str, str]: resolved = _resolve_email(key) if not resolved: - return (email, "") if email else (anonymous_id(identity), "") + # The key changed and will not resolve (revoked, offline, API down). + # Do not keep attributing to the previous account. + return anonymous_id(identity), "" - # Alias only when going anonymous -> email for the first time. - previous = "" if email else identity.get("anonymous_id", "") + # Alias only when going anonymous -> email for the first time. Once an anon + # id has been merged into an account it must never be offered again: an + # alias naming an already-identified id is what could link two real people. + previous = "" if (email or identity.get("aliased")) else identity.get("anonymous_id", "") + if previous: + identity["aliased"] = True identity["email"] = resolved identity["key_fingerprint"] = fingerprint _write_identity(identity) diff --git a/integrations/kimi-plugin/core/hook_runner.py b/integrations/kimi-plugin/core/hook_runner.py index 559702102..b3d8a3210 100644 --- a/integrations/kimi-plugin/core/hook_runner.py +++ b/integrations/kimi-plugin/core/hook_runner.py @@ -290,6 +290,11 @@ def run( if args.plugin_data_dir: os.environ[data_dir_env] = args.plugin_data_dir + # Snapshot BEFORE anything writes to the data dir: cache_plugin_api_key + # writes `api-key` and EvidenceStore creates `evidence.sqlite3`, so asking + # after them always saw content and every fresh install reported an upgrade. + data_dir_was_empty = telemetry.data_dir_was_empty() + cache_plugin_api_key() if args.action == "session-start": clear_stale_api_key_cache() @@ -307,7 +312,7 @@ def run( if args.action == "session-start": # Claims the marker atomically and says which event to record, so a # second session starting alongside this one cannot record it too. - first_event = telemetry.claim_install() + first_event = telemetry.claim_install(was_empty=data_dir_was_empty) if first_event == "install": telemetry.record("install") elif first_event == "upgrade": diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index d7933bfbc..a24c97264 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -221,18 +221,35 @@ def is_first_run() -> bool: return not _install_state_path().exists() -def claim_install() -> str | None: +def data_dir_was_empty() -> bool: + """Whether the data directory is untouched. Call BEFORE anything writes to it. + + hook_runner reaches claim_install() only after cache_plugin_api_key() has + written `api-key` and EvidenceStore() has created `evidence.sqlite3`, so + asking at claim time always saw content and every fresh install reported an + upgrade. The caller snapshots this at the top of the run instead. + """ + return not _data_dir_has_content() + + +def claim_install(was_empty: bool | None = None) -> str | None: """Claim the one install/upgrade record for this machine, atomically. Returns the event to record ("install" or "upgrade"), or None if another session already claimed it. O_CREAT|O_EXCL so two sessions starting together cannot both win. + + `was_empty` must come from data_dir_was_empty() called before this process + wrote anything. Omitting it falls back to checking now, which is only + correct for a caller that has touched nothing. """ + if not is_enabled(): + # Never consume the one-shot claim while the user is opted out, or they + # would silently lose their install event if they later opt in. + return None + path = _install_state_path() - # A fresh install has an empty data directory. Anything already there — - # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read - # before the marker is created, since creating it would itself be content. - upgrading = _data_dir_has_content() + upgrading = not (data_dir_was_empty() if was_empty is None else was_empty) try: path.parent.mkdir(parents=True, exist_ok=True) handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) @@ -266,6 +283,19 @@ def _data_dir_has_content() -> bool: return False +def _repair_install_state(path: Path) -> None: + """Rewrite an unparseable marker so version tracking can resume.""" + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text( + json.dumps({"plugin_version": memory_core.PLUGIN_VERSION, "repaired_at": memory_core.utc_now()}), + encoding="utf-8", + ) + temporary.replace(path) + except OSError: + pass + + def claim_version_change() -> str | None: """Return the previously recorded version if it differs, updating the marker. @@ -276,13 +306,32 @@ def claim_version_change() -> str | None: path = _install_state_path() try: state = json.loads(path.read_text(encoding="utf-8")) - except (OSError, json.JSONDecodeError): + except OSError: return None + except json.JSONDecodeError: + # A crash between O_EXCL and the write leaves an empty marker. Left + # alone it disables every future upgrade event on this machine, because + # claim_install sees the file and this function cannot parse it. + state = None if not isinstance(state, dict): + _repair_install_state(path) return None previous = str(state.get("plugin_version") or "") if not previous or previous == memory_core.PLUGIN_VERSION: return None + # Claim the transition with an exclusive sentinel before rewriting the + # marker. A plain read-modify-write let every concurrently starting session + # observe the old version and each record its own upgrade — and the first + # session after a version bump is exactly when several agent windows restart + # together. + sentinel = path.with_name(f"upgraded-{memory_core.PLUGIN_VERSION}") + try: + os.close(os.open(sentinel, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)) + except FileExistsError: + return None + except OSError: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() try: @@ -563,8 +612,18 @@ def resolve_distinct_id() -> tuple[str, str]: fingerprint = _digest(key) if key else "" email = identity.get("email", "") - if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: - return email, "" + if email and fingerprint: + recorded = identity.get("key_fingerprint", "") + if recorded == fingerprint: + return email, "" + if not recorded: + # Rows written before fingerprints existed. Adopt the current key + # rather than re-resolving: otherwise every existing user pays an + # uncached /v1/ping/ on every flush, forever, and a firewalled one + # pays the full timeout each time. + identity["key_fingerprint"] = fingerprint + _write_identity(identity) + return email, "" if not key: # No key to verify the account with; do not keep attributing to it. @@ -576,10 +635,16 @@ def resolve_distinct_id() -> tuple[str, str]: resolved = _resolve_email(key) if not resolved: - return (email, "") if email else (anonymous_id(identity), "") + # The key changed and will not resolve (revoked, offline, API down). + # Do not keep attributing to the previous account. + return anonymous_id(identity), "" - # Alias only when going anonymous -> email for the first time. - previous = "" if email else identity.get("anonymous_id", "") + # Alias only when going anonymous -> email for the first time. Once an anon + # id has been merged into an account it must never be offered again: an + # alias naming an already-identified id is what could link two real people. + previous = "" if (email or identity.get("aliased")) else identity.get("anonymous_id", "") + if previous: + identity["aliased"] = True identity["email"] = resolved identity["key_fingerprint"] = fingerprint _write_identity(identity) diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index d7933bfbc..a24c97264 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -221,18 +221,35 @@ def is_first_run() -> bool: return not _install_state_path().exists() -def claim_install() -> str | None: +def data_dir_was_empty() -> bool: + """Whether the data directory is untouched. Call BEFORE anything writes to it. + + hook_runner reaches claim_install() only after cache_plugin_api_key() has + written `api-key` and EvidenceStore() has created `evidence.sqlite3`, so + asking at claim time always saw content and every fresh install reported an + upgrade. The caller snapshots this at the top of the run instead. + """ + return not _data_dir_has_content() + + +def claim_install(was_empty: bool | None = None) -> str | None: """Claim the one install/upgrade record for this machine, atomically. Returns the event to record ("install" or "upgrade"), or None if another session already claimed it. O_CREAT|O_EXCL so two sessions starting together cannot both win. + + `was_empty` must come from data_dir_was_empty() called before this process + wrote anything. Omitting it falls back to checking now, which is only + correct for a caller that has touched nothing. """ + if not is_enabled(): + # Never consume the one-shot claim while the user is opted out, or they + # would silently lose their install event if they later opt in. + return None + path = _install_state_path() - # A fresh install has an empty data directory. Anything already there — - # a 0.2.x venv, an evidence db, a spool — means this is an upgrade. Read - # before the marker is created, since creating it would itself be content. - upgrading = _data_dir_has_content() + upgrading = not (data_dir_was_empty() if was_empty is None else was_empty) try: path.parent.mkdir(parents=True, exist_ok=True) handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) @@ -266,6 +283,19 @@ def _data_dir_has_content() -> bool: return False +def _repair_install_state(path: Path) -> None: + """Rewrite an unparseable marker so version tracking can resume.""" + try: + temporary = path.with_suffix(f".{os.getpid()}.tmp") + temporary.write_text( + json.dumps({"plugin_version": memory_core.PLUGIN_VERSION, "repaired_at": memory_core.utc_now()}), + encoding="utf-8", + ) + temporary.replace(path) + except OSError: + pass + + def claim_version_change() -> str | None: """Return the previously recorded version if it differs, updating the marker. @@ -276,13 +306,32 @@ def claim_version_change() -> str | None: path = _install_state_path() try: state = json.loads(path.read_text(encoding="utf-8")) - except (OSError, json.JSONDecodeError): + except OSError: return None + except json.JSONDecodeError: + # A crash between O_EXCL and the write leaves an empty marker. Left + # alone it disables every future upgrade event on this machine, because + # claim_install sees the file and this function cannot parse it. + state = None if not isinstance(state, dict): + _repair_install_state(path) return None previous = str(state.get("plugin_version") or "") if not previous or previous == memory_core.PLUGIN_VERSION: return None + # Claim the transition with an exclusive sentinel before rewriting the + # marker. A plain read-modify-write let every concurrently starting session + # observe the old version and each record its own upgrade — and the first + # session after a version bump is exactly when several agent windows restart + # together. + sentinel = path.with_name(f"upgraded-{memory_core.PLUGIN_VERSION}") + try: + os.close(os.open(sentinel, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600)) + except FileExistsError: + return None + except OSError: + return None + state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() try: @@ -563,8 +612,18 @@ def resolve_distinct_id() -> tuple[str, str]: fingerprint = _digest(key) if key else "" email = identity.get("email", "") - if email and identity.get("key_fingerprint", "") == fingerprint and fingerprint: - return email, "" + if email and fingerprint: + recorded = identity.get("key_fingerprint", "") + if recorded == fingerprint: + return email, "" + if not recorded: + # Rows written before fingerprints existed. Adopt the current key + # rather than re-resolving: otherwise every existing user pays an + # uncached /v1/ping/ on every flush, forever, and a firewalled one + # pays the full timeout each time. + identity["key_fingerprint"] = fingerprint + _write_identity(identity) + return email, "" if not key: # No key to verify the account with; do not keep attributing to it. @@ -576,10 +635,16 @@ def resolve_distinct_id() -> tuple[str, str]: resolved = _resolve_email(key) if not resolved: - return (email, "") if email else (anonymous_id(identity), "") + # The key changed and will not resolve (revoked, offline, API down). + # Do not keep attributing to the previous account. + return anonymous_id(identity), "" - # Alias only when going anonymous -> email for the first time. - previous = "" if email else identity.get("anonymous_id", "") + # Alias only when going anonymous -> email for the first time. Once an anon + # id has been merged into an account it must never be offered again: an + # alias naming an already-identified id is what could link two real people. + previous = "" if (email or identity.get("aliased")) else identity.get("anonymous_id", "") + if previous: + identity["aliased"] = True identity["email"] = resolved identity["key_fingerprint"] = fingerprint _write_identity(identity) From 47ce17c21ba9f5cbafb888c2c90f8e6751f51ba0 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:32:39 +0530 Subject: [PATCH 09/30] fix(integrations): apply the header contract the docs described MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review found the contract documented but not implemented, and one client path missed entirely. AsyncMemoryClient's custom-client branch still carried the old literal header dict, so `AsyncMemoryClient(client=...)` sent no surface identity at all — the exact asymmetry this work set out to remove. Both custom-client branches also used a blanket headers.update(), which overwrites. That is the one code path where an outer layer's identity can physically be present, and it was the one path that erased it. They now check-then-set the identity headers and append to an existing client stack, which is what set-once and append-only were supposed to mean. AGENTS.md claimed a plugin calling the Python SDK produces `mem0-plugin/0.3.1, mem0-python/2.0.19`. Nothing in the repo sets the env vars that would make that happen, so the concatenation was unreachable. Replaced with the three ways an integration can actually declare itself, in preference order. memory_core's comment said the backend reads X-Mem0-Source. That is only true from the platform release shipping alongside this, and a reader would otherwise trust it and build header-only attribution that silently does nothing — which is how vercel-ai-sdk was written in the first cut. Corrected in all seven copies, and the body value is what makes attribution work against either backend. mem0-ts hardcoded SDK_VERSION = "3.1.8" while the repo already injects __MEM0_SDK_VERSION__ via tsup, the same mechanism telemetry.ts uses. The hardcode was correct only until the next release bump. Dropped both `as never` casts in pi-agent. They suppressed an excess-property error but also disabled checking of every other option at those call sites, so a typo in filters or threshold would have compiled. SearchMemoryOptions now declares `source` instead. Stack truncation cut mid-identifier, leaving a fragment that parses as a real client name. It now drops whole entries. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- integrations/AGENTS.md | 22 ++++++--- .../agent-plugin-core/python/memory_core.py | 9 ++-- .../tests/test_uninitialised_identity.py | 27 ++++++++++ .../antigravity-plugin/core/memory_core.py | 9 ++-- .../claude-code-plugin/core/memory_core.py | 9 ++-- integrations/codex-plugin/core/memory_core.py | 9 ++-- .../cursor-plugin/core/memory_core.py | 9 ++-- integrations/kimi-plugin/core/memory_core.py | 9 ++-- .../mem0-agent-plugin/core/memory_core.py | 9 ++-- integrations/pi-agent-plugin/src/commands.ts | 12 ++--- mem0-ts/src/client/mem0.ts | 8 ++- mem0-ts/src/client/mem0.types.ts | 3 ++ mem0/client/main.py | 49 ++++++++++++++++--- 13 files changed, 142 insertions(+), 42 deletions(-) diff --git a/integrations/AGENTS.md b/integrations/AGENTS.md index 75b60009e..9b85cddb1 100644 --- a/integrations/AGENTS.md +++ b/integrations/AGENTS.md @@ -60,13 +60,23 @@ and the rules on them are what keep one layer from erasing another: | `X-Application` | the host app it runs inside | **set-once** — write only if absent | | `X-Mem0-Client` | `name/version`, outermost first | **append-only** — add yourself, never replace | -Set-once means `setdefault`, never assignment. An integration that wraps the -SDK is the outermost layer and sets the source; the SDK underneath must defer to -it. Assignment is exactly how every agent plugin came to be indistinguishable -from every other one at the platform. +Set-once means check-then-set, never assignment. An integration that wraps the +SDK is the outermost layer and sets the source; the SDK underneath defers to it. +Assignment is exactly how every agent plugin came to be indistinguishable from +every other one at the platform. -Append-only means a plugin calling the Python SDK produces -`mem0-plugin/0.3.1, mem0-python/2.0.19`, so neither layer can erase the other. +How to declare it from an integration, in order of preference: + +1. Send the headers yourself, if you make the HTTP call directly. +2. Pass `source` in the call options, if you go through an SDK. +3. Set `MEM0_SOURCE` / `MEM0_APPLICATION` / `MEM0_CLIENT_STACK` in the + environment before constructing the client. The SDKs read these and defer to + anything already present. + +Append-only applies where a stack can actually form: an SDK handed a client that +already carries `X-Mem0-Client` appends itself rather than replacing. An SDK +constructed with no outer context simply reports itself, which is correct — it +is the outermost layer in that process. The backend recognizes a fixed list of source values and buckets everything else into `OTHERS`. A new value has to land in the platform's `EventSource` enum, so diff --git a/integrations/agent-plugin-core/python/memory_core.py b/integrations/agent-plugin-core/python/memory_core.py index 31a08ec37..d350e76d2 100644 --- a/integrations/agent-plugin-core/python/memory_core.py +++ b/integrations/agent-plugin-core/python/memory_core.py @@ -2008,9 +2008,12 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, - # Top level, not metadata: the backend reads `source` from the body, - # query string or X-Mem0-Source header, never from metadata. The - # harness tag stays in metadata as hook provenance. + # Top level, not metadata: the backend reads `source` from the body or + # the query string, never from metadata, which is where this used to + # sit. The X-Mem0-Source header is also read, but only from the + # platform release that ships alongside this change, so the body value + # is what makes attribution work on both. The harness tag stays in + # metadata as hook provenance. "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, diff --git a/integrations/agent-plugin-core/tests/test_uninitialised_identity.py b/integrations/agent-plugin-core/tests/test_uninitialised_identity.py index 14f911bee..1c742b518 100644 --- a/integrations/agent-plugin-core/tests/test_uninitialised_identity.py +++ b/integrations/agent-plugin-core/tests/test_uninitialised_identity.py @@ -177,3 +177,30 @@ def test_source_tag_defaults_agree_between_the_two_modules(): ) left, right = out.split() assert left == right == "KIMI_PLUGIN" + + +def test_the_plugin_declares_its_surface_in_the_body_and_the_headers(): + """Body and headers both, because only the body works on every backend.""" + core = _core_dir("claude-code-plugin") + if not core.exists(): + pytest.skip("claude-code-plugin is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + out = _run( + core, + Path(tmp), + "import json, memory_core\n" + "h = memory_core.platform_headers('k')\n" + "print(json.dumps({'source': h.get('X-Mem0-Source')," + " 'app': h.get('X-Application')," + " 'client': h.get('X-Mem0-Client')," + " 'auth': h.get('Authorization')," + " 'ctype': h.get('Content-Type')}))", + ) + headers = json.loads(out) + assert headers["source"] == "MEM0_PLUGIN" + assert headers["app"] == "claude-code" + assert headers["client"].startswith("mem0-plugin/") + # The transport headers the three call sites relied on must survive. + assert headers["auth"] == "Token k" + assert headers["ctype"] == "application/json" diff --git a/integrations/antigravity-plugin/core/memory_core.py b/integrations/antigravity-plugin/core/memory_core.py index 31a08ec37..d350e76d2 100644 --- a/integrations/antigravity-plugin/core/memory_core.py +++ b/integrations/antigravity-plugin/core/memory_core.py @@ -2008,9 +2008,12 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, - # Top level, not metadata: the backend reads `source` from the body, - # query string or X-Mem0-Source header, never from metadata. The - # harness tag stays in metadata as hook provenance. + # Top level, not metadata: the backend reads `source` from the body or + # the query string, never from metadata, which is where this used to + # sit. The X-Mem0-Source header is also read, but only from the + # platform release that ships alongside this change, so the body value + # is what makes attribution work on both. The harness tag stays in + # metadata as hook provenance. "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, diff --git a/integrations/claude-code-plugin/core/memory_core.py b/integrations/claude-code-plugin/core/memory_core.py index 31a08ec37..d350e76d2 100644 --- a/integrations/claude-code-plugin/core/memory_core.py +++ b/integrations/claude-code-plugin/core/memory_core.py @@ -2008,9 +2008,12 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, - # Top level, not metadata: the backend reads `source` from the body, - # query string or X-Mem0-Source header, never from metadata. The - # harness tag stays in metadata as hook provenance. + # Top level, not metadata: the backend reads `source` from the body or + # the query string, never from metadata, which is where this used to + # sit. The X-Mem0-Source header is also read, but only from the + # platform release that ships alongside this change, so the body value + # is what makes attribution work on both. The harness tag stays in + # metadata as hook provenance. "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, diff --git a/integrations/codex-plugin/core/memory_core.py b/integrations/codex-plugin/core/memory_core.py index 31a08ec37..d350e76d2 100644 --- a/integrations/codex-plugin/core/memory_core.py +++ b/integrations/codex-plugin/core/memory_core.py @@ -2008,9 +2008,12 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, - # Top level, not metadata: the backend reads `source` from the body, - # query string or X-Mem0-Source header, never from metadata. The - # harness tag stays in metadata as hook provenance. + # Top level, not metadata: the backend reads `source` from the body or + # the query string, never from metadata, which is where this used to + # sit. The X-Mem0-Source header is also read, but only from the + # platform release that ships alongside this change, so the body value + # is what makes attribution work on both. The harness tag stays in + # metadata as hook provenance. "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, diff --git a/integrations/cursor-plugin/core/memory_core.py b/integrations/cursor-plugin/core/memory_core.py index 31a08ec37..d350e76d2 100644 --- a/integrations/cursor-plugin/core/memory_core.py +++ b/integrations/cursor-plugin/core/memory_core.py @@ -2008,9 +2008,12 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, - # Top level, not metadata: the backend reads `source` from the body, - # query string or X-Mem0-Source header, never from metadata. The - # harness tag stays in metadata as hook provenance. + # Top level, not metadata: the backend reads `source` from the body or + # the query string, never from metadata, which is where this used to + # sit. The X-Mem0-Source header is also read, but only from the + # platform release that ships alongside this change, so the body value + # is what makes attribution work on both. The harness tag stays in + # metadata as hook provenance. "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, diff --git a/integrations/kimi-plugin/core/memory_core.py b/integrations/kimi-plugin/core/memory_core.py index 31a08ec37..d350e76d2 100644 --- a/integrations/kimi-plugin/core/memory_core.py +++ b/integrations/kimi-plugin/core/memory_core.py @@ -2008,9 +2008,12 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, - # Top level, not metadata: the backend reads `source` from the body, - # query string or X-Mem0-Source header, never from metadata. The - # harness tag stays in metadata as hook provenance. + # Top level, not metadata: the backend reads `source` from the body or + # the query string, never from metadata, which is where this used to + # sit. The X-Mem0-Source header is also read, but only from the + # platform release that ships alongside this change, so the body value + # is what makes attribution work on both. The harness tag stays in + # metadata as hook provenance. "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, diff --git a/integrations/mem0-agent-plugin/core/memory_core.py b/integrations/mem0-agent-plugin/core/memory_core.py index 31a08ec37..d350e76d2 100644 --- a/integrations/mem0-agent-plugin/core/memory_core.py +++ b/integrations/mem0-agent-plugin/core/memory_core.py @@ -2008,9 +2008,12 @@ def flush_session( "user_id": write_user, "app_id": repo.app_id, "run_id": session_id, - # Top level, not metadata: the backend reads `source` from the body, - # query string or X-Mem0-Source header, never from metadata. The - # harness tag stays in metadata as hook provenance. + # Top level, not metadata: the backend reads `source` from the body or + # the query string, never from metadata, which is where this used to + # sit. The X-Mem0-Source header is also read, but only from the + # platform release that ships alongside this change, so the body value + # is what makes attribution work on both. The harness tag stays in + # metadata as hook provenance. "source": _PLATFORM_SOURCE, "metadata": {**metadata, "author": write_user, "dirs": directory_chain(repo)}, "agent_custom_instructions": PROJECT_MEMORY_INSTRUCTIONS, diff --git a/integrations/pi-agent-plugin/src/commands.ts b/integrations/pi-agent-plugin/src/commands.ts index e90f8833b..f50194ed6 100644 --- a/integrations/pi-agent-plugin/src/commands.ts +++ b/integrations/pi-agent-plugin/src/commands.ts @@ -6,6 +6,10 @@ import { resolveSearchFilters, resolveAddParams } from "./memory/scoping.ts"; import { formatMemoryList, formatMemoryCompact, groupByCategory } from "./memory/formatting.ts"; import { captureCommandEvent } from "./telemetry.ts"; +// Surface attribution on the wire. Previously a PostHog property only, so +// the platform saw these calls as generic SDK traffic. +const PLATFORM_SOURCE = "PI_AGENT"; + const SEARCH_TOP_K = 10; export function registerCommands( @@ -22,10 +26,6 @@ export function registerCommands( const pluralize = (n: number, one: string, many: string): string => `${n} ${n === 1 ? one : many}`; -// Surface attribution on the wire. This was previously only a PostHog property, -// so the platform saw these calls as generic SDK traffic. -const PLATFORM_SOURCE = "PI_AGENT"; - const searchMemories = async (query: string, scope: Scope) => { const filters = resolveSearchFilters(scope, getScopeCtx()); const result = await mem0.search(query, { @@ -34,7 +34,7 @@ const PLATFORM_SOURCE = "PI_AGENT"; topK: SEARCH_TOP_K, rerank: true, source: PLATFORM_SOURCE, - } as never); + }); return result.results ?? []; }; @@ -50,7 +50,7 @@ const PLATFORM_SOURCE = "PI_AGENT"; const addParams = resolveAddParams(config.defaultScope, getScopeCtx()); const result = await mem0.add( [{ role: "user", content: text }], - { ...addParams, customCategories: DEFAULT_CUSTOM_CATEGORIES, infer: false, source: PLATFORM_SOURCE } as never, + { ...addParams, customCategories: DEFAULT_CUSTOM_CATEGORIES, infer: false, source: PLATFORM_SOURCE }, ); captureCommandEvent("mem0-remember", {}, telemetryCtx); diff --git a/mem0-ts/src/client/mem0.ts b/mem0-ts/src/client/mem0.ts index 6327acffa..ddea270a2 100644 --- a/mem0-ts/src/client/mem0.ts +++ b/mem0-ts/src/client/mem0.ts @@ -95,7 +95,13 @@ interface ClientIdentity { const IDENTITY_CACHE_MAX_DEFAULT = 50; const identityByCredentials = new Map>(); -const SDK_VERSION = "3.1.8"; +declare const __MEM0_SDK_VERSION__: string | undefined; + +// Injected by tsup (see mem0-ts/tsup.config.ts `define`), the same mechanism +// telemetry.ts already uses. A hardcoded literal goes stale at the next release +// bump and then misreports the client version forever. +const SDK_VERSION = + typeof __MEM0_SDK_VERSION__ !== "undefined" ? __MEM0_SDK_VERSION__ : "dev"; /** * Surface-identity headers. diff --git a/mem0-ts/src/client/mem0.types.ts b/mem0-ts/src/client/mem0.types.ts index c230441e0..cbe541321 100644 --- a/mem0-ts/src/client/mem0.types.ts +++ b/mem0-ts/src/client/mem0.types.ts @@ -30,6 +30,9 @@ export interface SearchMemoryOptions { showExpired?: boolean; referenceDate?: string | number; keywordSearch?: boolean; + /** Surface that produced the call, e.g. "OPENCLAW". Must be a value the + * backend's EventSource enum knows, or it buckets into OTHERS. */ + source?: string; } export interface GetAllMemoryOptions { diff --git a/mem0/client/main.py b/mem0/client/main.py index d118bc340..abdf61bca 100644 --- a/mem0/client/main.py +++ b/mem0/client/main.py @@ -89,6 +89,44 @@ def _sdk_version() -> str: return "unknown" +def _apply_client_headers(client: Any, api_key: str, user_id: str) -> None: + """Merge our headers into a caller-supplied client without erasing theirs. + + A wrapper may hand us a client already carrying its own X-Mem0-Source or a + partial X-Mem0-Client stack. Blanket update() replaced both, which is the + opposite of the set-once / append-only contract: the outermost layer is the + one whose identity should survive. + """ + existing = client.headers + mine = _client_headers(api_key, user_id) + + outer_stack = existing.get("X-Mem0-Client") + if outer_stack: + entries = [part.strip() for part in str(outer_stack).split(",") if part.strip()] + entries.append(f"mem0-python/{_sdk_version()}") + mine["X-Mem0-Client"] = _bounded_stack(entries) + + for name, value in mine.items(): + if name in ("X-Mem0-Source", "X-Application") and existing.get(name): + continue + existing[name] = value + + +def _bounded_stack(entries) -> str: + """Join stack entries within the cap, dropping whole entries not characters. + + A blunt slice cut mid-identifier and left a fragment that parses as a real + client name. + """ + out = [] + for entry in list(entries)[:4]: + candidate = ", ".join(out + [entry]) + if len(candidate) > 200: + break + out.append(entry) + return ", ".join(out) + + def _client_headers(api_key: str, user_id: str) -> Dict[str, str]: """Auth plus surface-identity headers. @@ -120,7 +158,7 @@ def _client_stack() -> str: mine = f"mem0-python/{_sdk_version()}" entries = [part.strip() for part in existing.split(",") if part.strip()] if existing else [] entries.append(mine) - return ", ".join(entries[:4])[:200] + return _bounded_stack(entries) class MemoryClient: @@ -173,7 +211,7 @@ class MemoryClient: self.client = client # Ensure the client has the correct base_url and headers self.client.base_url = httpx.URL(self.host) - self.client.headers.update(_client_headers(self.api_key, self.user_id)) + _apply_client_headers(self.client, self.api_key, self.user_id) else: self.client = httpx.Client( base_url=self.host, @@ -1054,12 +1092,7 @@ class AsyncMemoryClient: self.async_client = client # Ensure the client has the correct base_url and headers self.async_client.base_url = httpx.URL(self.host) - self.async_client.headers.update( - { - "Authorization": f"Token {self.api_key}", - "Mem0-User-ID": self.user_id, - } - ) + _apply_client_headers(self.async_client, self.api_key, self.user_id) else: self.async_client = httpx.AsyncClient( base_url=self.host, From 5104cc3276cdfcc0c4be58ac110bbea7cd4e1854 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:33:49 +0530 Subject: [PATCH 10/30] fix(plugins): repair the merged test file and regenerate bundles The keep-both conflict resolution split a function body. Rebuilt from both merge parents so the header-contract test and the session-start tests are each intact. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../tests/test_uninitialised_identity.py | 43 +++++++++++-------- 1 file changed, 24 insertions(+), 19 deletions(-) diff --git a/integrations/agent-plugin-core/tests/test_uninitialised_identity.py b/integrations/agent-plugin-core/tests/test_uninitialised_identity.py index 3a733d0bd..74a31fa5c 100644 --- a/integrations/agent-plugin-core/tests/test_uninitialised_identity.py +++ b/integrations/agent-plugin-core/tests/test_uninitialised_identity.py @@ -181,6 +181,30 @@ def test_source_tag_defaults_agree_between_the_two_modules(): def test_the_plugin_declares_its_surface_in_the_body_and_the_headers(): """Body and headers both, because only the body works on every backend.""" + core = _core_dir("claude-code-plugin") + if not core.exists(): + pytest.skip("claude-code-plugin is not built in this tree") + + with tempfile.TemporaryDirectory() as tmp: + out = _run( + core, + Path(tmp), + "import json, memory_core\n" + "h = memory_core.platform_headers('k')\n" + "print(json.dumps({'source': h.get('X-Mem0-Source')," + " 'app': h.get('X-Application')," + " 'client': h.get('X-Mem0-Client')," + " 'auth': h.get('Authorization')," + " 'ctype': h.get('Content-Type')}))", + ) + headers = json.loads(out) + assert headers["source"] == "MEM0_PLUGIN" + assert headers["app"] == "claude-code" + assert headers["client"].startswith("mem0-plugin/") + # The transport headers the three call sites relied on must survive. + assert headers["auth"] == "Token k" + assert headers["ctype"] == "application/json" + def _session_start(core: Path, data_dir: Path) -> list[str]: """Drive the real hook_runner session-start path and return lifecycle events.""" @@ -217,25 +241,6 @@ def test_a_fresh_install_reports_install_not_upgrade(): pytest.skip("claude-code-plugin is not built in this tree") with tempfile.TemporaryDirectory() as tmp: - out = _run( - core, - Path(tmp), - "import json, memory_core\n" - "h = memory_core.platform_headers('k')\n" - "print(json.dumps({'source': h.get('X-Mem0-Source')," - " 'app': h.get('X-Application')," - " 'client': h.get('X-Mem0-Client')," - " 'auth': h.get('Authorization')," - " 'ctype': h.get('Content-Type')}))", - ) - headers = json.loads(out) - assert headers["source"] == "MEM0_PLUGIN" - assert headers["app"] == "claude-code" - assert headers["client"].startswith("mem0-plugin/") - # The transport headers the three call sites relied on must survive. - assert headers["auth"] == "Token k" - assert headers["ctype"] == "application/json" - data_dir = Path(tmp) / "data" assert _session_start(core, data_dir) == ["install"] From 349f77e556b8087cb82d18cbe4ada59a2d6ce1ec Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:36:23 +0530 Subject: [PATCH 11/30] fix(plugins): stop the new spool tests depending on ambient state MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit CI runs agent-plugin-core/tests and claude-code-plugin/tests in one pytest process. Two things only show up in that combined run, so the suites passed locally and failed on every push. claude-code-plugin/tests/conftest.py sets MEM0_TELEMETRY=false at import, which is process-wide. record() then returns early and every assertion in test_spool_delivery.py saw an empty spool — nine failures, all reported as "recorded nothing" rather than as a disabled feature. The fixture now pins MEM0_TELEMETRY rather than trusting whatever collected first. The fixture also dropped telemetry/memory_core/_harness_id from sys.modules on teardown. That conftest imports memory_core once at collection and calls configure_harness() on it, so a later re-import got a fresh module with default harness config and test_memory_core failed depending on collection order. The fixture now saves and restores those entries instead of deleting them. Verified with CI's exact command rather than the narrower path I had been running: 266 passed, 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../tests/test_spool_delivery.py | 25 ++++++++++++++++--- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/integrations/agent-plugin-core/tests/test_spool_delivery.py b/integrations/agent-plugin-core/tests/test_spool_delivery.py index 08266cc98..a51027904 100644 --- a/integrations/agent-plugin-core/tests/test_spool_delivery.py +++ b/integrations/agent-plugin-core/tests/test_spool_delivery.py @@ -25,15 +25,32 @@ pytestmark = pytest.mark.skipif(not HOST_CORE.exists(), reason="claude-code-plug @pytest.fixture() def telemetry(tmp_path, monkeypatch): + # CI runs this directory and claude-code-plugin/tests in ONE pytest process, + # and that suite's conftest sets MEM0_TELEMETRY=false at import, process-wide. + # Without this the whole file silently no-ops: record() returns early and + # every assertion sees an empty spool. Do not rely on ambient env. + monkeypatch.setenv("MEM0_TELEMETRY", "true") monkeypatch.setenv("MEM0_CODE_DATA_DIR", str(tmp_path / "data")) monkeypatch.syspath_prepend(str(HOST_CORE)) - for name in ("telemetry", "memory_core", "_harness_id"): + + # Save and RESTORE rather than delete. claude-code-plugin/tests/conftest.py + # imports memory_core once at collection and calls configure_harness() on it; + # dropping the module left a later re-import with default harness config, so + # tests in that suite failed depending on collection order. + names = ("telemetry", "memory_core", "_harness_id") + saved = {name: sys.modules.get(name) for name in names} + for name in names: sys.modules.pop(name, None) + module = importlib.import_module("telemetry") monkeypatch.setattr(module, "resolve_distinct_id", lambda: ("tester@example.com", "")) - yield module - for name in ("telemetry", "memory_core", "_harness_id"): - sys.modules.pop(name, None) + try: + yield module + finally: + for name in names: + sys.modules.pop(name, None) + if saved[name] is not None: + sys.modules[name] = saved[name] def _delivered(payloads): From aa770aa65291da0d1c7a0360223e09033683993c Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:37:33 +0530 Subject: [PATCH 12/30] docs(plugins): finish the telemetry sweep across the remaining surfaces MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The first pass fixed the plugin README and the module docstring but left the same claim standing everywhere else. - docs/integrations/deepseek-plugin.mdx still said "Anonymous usage events". The TS SDK's telemetryId is the raw account email, so it is not anonymous. - The pause skill told users a "minimal anonymous telemetry ping" fires while paused. Same ping, same email. Corrected in the template, which regenerates into all six hosts. - integrations/zapier-mem0/README.md advertised telemetry the app does not have: there is no telemetry code in it at all. It now says what is actually true, that its requests carry source="ZAPIER". - The data directory listing is presented as exhaustive and had gone stale against this stack's two new files, telemetry-salt and install-state.json. Also replaced the property enumeration in both the README and the docs page. Review pointed out it omitted the configured model name among others — writing a fresh exhaustive list in a PR whose whole purpose is making docs match code reproduces the defect being fixed. It now describes the shape and points at where the rule is actually enforced, so it cannot drift again. Deliberately unchanged: docs/integrations/openclaw.mdx. OpenClaw hashes the email rather than sending it, which is materially different from the plugin and the SDK, so its claim is not wrong in the same way. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- docs/integrations/claude-code.mdx | 11 ++++++++--- docs/integrations/deepseek-plugin.mdx | 2 +- .../agent-plugin-core/skills/pause/SKILL.md.tmpl | 4 ++-- integrations/antigravity-plugin/skills/pause/SKILL.md | 4 ++-- integrations/claude-code-plugin/README.md | 6 +++++- integrations/claude-code-plugin/skills/pause/SKILL.md | 4 ++-- integrations/codex-plugin/skills/pause/SKILL.md | 4 ++-- integrations/cursor-plugin/skills/pause/SKILL.md | 4 ++-- integrations/kimi-plugin/skills/pause/SKILL.md | 4 ++-- integrations/mem0-agent-plugin/skills/pause/SKILL.md | 4 ++-- integrations/zapier-mem0/README.md | 2 +- 11 files changed, 29 insertions(+), 20 deletions(-) diff --git a/docs/integrations/claude-code.mdx b/docs/integrations/claude-code.mdx index c4b5a2c35..4277bb90e 100644 --- a/docs/integrations/claude-code.mdx +++ b/docs/integrations/claude-code.mdx @@ -183,11 +183,16 @@ the same way the Python SDK and the CLI attribute theirs. Without a key they are sent under a random per-machine id. Each event carries the event name, the plugin version, the harness it ran in, -your OS and Python version, timings, counts, and a coarse failure label. -Repository and session identifiers are hashed with a random salt generated on -your machine and never sent, so they cannot be linked back to a repository name +your OS and Python version, and per-event properties describing what happened: +timings, counts, coarse outcome and failure labels, and which model was +configured. Repository and session identifiers are hashed with a random salt +generated on your machine, so they cannot be linked back to a repository name or path. +The exact set is enforced in code rather than by this list: every property is +filtered through a denylist of sensitive keys and credential-shaped values are +redacted before anything is sent. + Prompts, memory text, queries, file paths, repository names, and API keys are never sent. diff --git a/docs/integrations/deepseek-plugin.mdx b/docs/integrations/deepseek-plugin.mdx index 16b8badaf..0242496e1 100644 --- a/docs/integrations/deepseek-plugin.mdx +++ b/docs/integrations/deepseek-plugin.mdx @@ -114,7 +114,7 @@ Both tools also accept optional per-call `userId`, `agentId`, and `runId` params ## Telemetry -Writes are tagged `source="DEEPSEEK_HARNESS"` so Mem0 can attribute usage to this integration. Anonymous usage events include operation names, durations, result counts, and coarse failure kinds. Queries, memory text, entity IDs, and API keys are never included. Set `MEM0_TELEMETRY=false` to opt out. +Writes are tagged `source="DEEPSEEK_HARNESS"` so Mem0 can attribute usage to this integration. Usage events include operation names, durations, result counts, and coarse failure kinds. They are **not anonymous**: when an API key is configured they are sent under your Mem0 account email, the same way the SDK attributes its own. Queries, memory text, entity IDs, and API keys are never included. Set `MEM0_TELEMETRY=false` to opt out. This plugin is a developer preview and tracks the evolving DeepSeek Harness plugin API. diff --git a/integrations/agent-plugin-core/skills/pause/SKILL.md.tmpl b/integrations/agent-plugin-core/skills/pause/SKILL.md.tmpl index 9cc720c7a..569305ec7 100644 --- a/integrations/agent-plugin-core/skills/pause/SKILL.md.tmpl +++ b/integrations/agent-plugin-core/skills/pause/SKILL.md.tmpl @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "{{PLUGIN_ROOT}}/core/memory_cli.py" --harness "{{HARNESS_ID}}" {{PLUGIN_DATA_ARG}} pause diff --git a/integrations/antigravity-plugin/skills/pause/SKILL.md b/integrations/antigravity-plugin/skills/pause/SKILL.md index e88f7d315..77b4146b6 100644 --- a/integrations/antigravity-plugin/skills/pause/SKILL.md +++ b/integrations/antigravity-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${ANTIGRAVITY_PLUGIN_ROOT}/core/memory_cli.py" --harness "antigravity" pause diff --git a/integrations/claude-code-plugin/README.md b/integrations/claude-code-plugin/README.md index 872071abe..b58f54c79 100644 --- a/integrations/claude-code-plugin/README.md +++ b/integrations/claude-code-plugin/README.md @@ -137,6 +137,8 @@ Local data lives in `${CLAUDE_PLUGIN_DATA}`: - `flush-worker.log`: whether memory creation succeeded - `plugin-errors.log`: hook errors (no credentials) - `telemetry.jsonl` / `telemetry-identity.json`: usage events and the id they are sent under +- `telemetry-salt`: random per-install salt for the repo and session hashes +- `install-state.json`: records that install has been counted once on this machine Mem0 receives captured user messages, Claude's answers, sidekick assignments and completed responses, and changed file paths. When a failed command is recorded, extraction can also include bounded command details and results. Complete files and general tool output stay on your machine. Values that look like credentials are redacted before anything is sent. @@ -146,7 +148,9 @@ Usage events (which hook ran, timing, result counts, failure types) so Mem0 can **These events are not anonymous.** When an API key is configured — which installing the plugin requires — events are sent under your Mem0 account email, the same way the Python SDK and the CLI attribute theirs. Without a key they are sent under a random per-machine id. -What each event carries: the event name, the plugin version, the harness it ran in, your OS and Python version, timings, counts, and a coarse failure label. Repository and session identifiers are hashed with a random salt generated on your machine and never sent, so they cannot be linked back to a repository name or path. +What each event carries: the event name, the plugin version, the harness it ran in, your OS and Python version, and per-event properties describing what happened — timings, counts, coarse outcome and failure labels, and which model was configured. Repository and session identifiers are hashed with a random salt generated on your machine, so they cannot be linked back to a repository name or path. + +Rather than restate a list that drifts, the exact set is enforced in code: `telemetry.record` filters every property through a denylist of sensitive keys and redacts credential-shaped values. See `_PRIVATE_KEYS` in `core/telemetry.py`. Prompts, memory text, queries, file paths, repository names, and API keys are never sent. diff --git a/integrations/claude-code-plugin/skills/pause/SKILL.md b/integrations/claude-code-plugin/skills/pause/SKILL.md index 5aef04f39..ce69d13d2 100644 --- a/integrations/claude-code-plugin/skills/pause/SKILL.md +++ b/integrations/claude-code-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${CLAUDE_PLUGIN_ROOT}/core/memory_cli.py" --harness "claude-code" --plugin-data-dir "${CLAUDE_PLUGIN_DATA}" pause diff --git a/integrations/codex-plugin/skills/pause/SKILL.md b/integrations/codex-plugin/skills/pause/SKILL.md index d8a52f47b..c8f8ddd5f 100644 --- a/integrations/codex-plugin/skills/pause/SKILL.md +++ b/integrations/codex-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${PLUGIN_ROOT}/core/memory_cli.py" --harness "codex" --plugin-data-dir "${PLUGIN_DATA}" pause diff --git a/integrations/cursor-plugin/skills/pause/SKILL.md b/integrations/cursor-plugin/skills/pause/SKILL.md index 634385145..17384c368 100644 --- a/integrations/cursor-plugin/skills/pause/SKILL.md +++ b/integrations/cursor-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${CURSOR_PLUGIN_ROOT}/core/memory_cli.py" --harness "cursor" pause diff --git a/integrations/kimi-plugin/skills/pause/SKILL.md b/integrations/kimi-plugin/skills/pause/SKILL.md index 9f217a468..8f93e3bf7 100644 --- a/integrations/kimi-plugin/skills/pause/SKILL.md +++ b/integrations/kimi-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${KIMI_PLUGIN_ROOT}/core/memory_cli.py" --harness "kimi" pause diff --git a/integrations/mem0-agent-plugin/skills/pause/SKILL.md b/integrations/mem0-agent-plugin/skills/pause/SKILL.md index c6316dd0b..a87d6c3ee 100644 --- a/integrations/mem0-agent-plugin/skills/pause/SKILL.md +++ b/integrations/mem0-agent-plugin/skills/pause/SKILL.md @@ -6,8 +6,8 @@ description: Pause Mem0 memory capture on this machine. Use when the user wants # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${PLUGIN_ROOT}/core/memory_cli.py" --harness "coding-agent" pause diff --git a/integrations/zapier-mem0/README.md b/integrations/zapier-mem0/README.md index 7b3f5ed0f..dab21d3f3 100644 --- a/integrations/zapier-mem0/README.md +++ b/integrations/zapier-mem0/README.md @@ -32,7 +32,7 @@ pnpm test:unit # offline unit tests (mocked, no network) MEM0_API_KEY=m0-... pnpm test # unit + live E2E against api.mem0.ai ``` -Anonymous usage telemetry is sent to Mem0; opt out with `MEM0_TELEMETRY=false`. +This app sends no telemetry of its own. Its API requests carry `source: "ZAPIER"` so Mem0 can see aggregate usage of the integration. To deploy (maintainers): `pnpm build && zapier push`. From e9cbc626c039abf4f10699a9498a0c0be3cf0a54 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 00:42:44 +0530 Subject: [PATCH 13/30] fix(pi-agent): widen the search options by one property instead of to never CI caught what I could not check locally: `pnpm exec tsc --noEmit` fails with error TS2353: Object literal may only specify known properties, and 'source' does not exist in type 'SearchMemoryOptions'. Adding `source` to SearchMemoryOptions in mem0-ts does not help here. pi-agent resolves `mem0ai` from npm, so it typechecks against the published 3.1.8 types, not this repo's source. The declaration still belongs in mem0-ts for the next release; this call site needs to compile today. Widened by exactly that one property rather than restoring `as never`, which was the original objection: a blanket cast also disabled checking of filters, threshold, topK and rerank on the same literal. `source` reaches the wire through the SDK's camelToSnakeKeys spread either way. Verified by installing the package deps and running the real gates: tsc clean, build clean. vercel-ai-sdk typechecks clean too. Also carries the spool-test environment fix that had not been committed in this worktree. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../tests/test_spool_delivery.py | 25 ++++++++++++++++--- integrations/pi-agent-plugin/src/commands.ts | 7 +++++- 2 files changed, 27 insertions(+), 5 deletions(-) diff --git a/integrations/agent-plugin-core/tests/test_spool_delivery.py b/integrations/agent-plugin-core/tests/test_spool_delivery.py index 08266cc98..a51027904 100644 --- a/integrations/agent-plugin-core/tests/test_spool_delivery.py +++ b/integrations/agent-plugin-core/tests/test_spool_delivery.py @@ -25,15 +25,32 @@ pytestmark = pytest.mark.skipif(not HOST_CORE.exists(), reason="claude-code-plug @pytest.fixture() def telemetry(tmp_path, monkeypatch): + # CI runs this directory and claude-code-plugin/tests in ONE pytest process, + # and that suite's conftest sets MEM0_TELEMETRY=false at import, process-wide. + # Without this the whole file silently no-ops: record() returns early and + # every assertion sees an empty spool. Do not rely on ambient env. + monkeypatch.setenv("MEM0_TELEMETRY", "true") monkeypatch.setenv("MEM0_CODE_DATA_DIR", str(tmp_path / "data")) monkeypatch.syspath_prepend(str(HOST_CORE)) - for name in ("telemetry", "memory_core", "_harness_id"): + + # Save and RESTORE rather than delete. claude-code-plugin/tests/conftest.py + # imports memory_core once at collection and calls configure_harness() on it; + # dropping the module left a later re-import with default harness config, so + # tests in that suite failed depending on collection order. + names = ("telemetry", "memory_core", "_harness_id") + saved = {name: sys.modules.get(name) for name in names} + for name in names: sys.modules.pop(name, None) + module = importlib.import_module("telemetry") monkeypatch.setattr(module, "resolve_distinct_id", lambda: ("tester@example.com", "")) - yield module - for name in ("telemetry", "memory_core", "_harness_id"): - sys.modules.pop(name, None) + try: + yield module + finally: + for name in names: + sys.modules.pop(name, None) + if saved[name] is not None: + sys.modules[name] = saved[name] def _delivered(payloads): diff --git a/integrations/pi-agent-plugin/src/commands.ts b/integrations/pi-agent-plugin/src/commands.ts index f50194ed6..a733aea0a 100644 --- a/integrations/pi-agent-plugin/src/commands.ts +++ b/integrations/pi-agent-plugin/src/commands.ts @@ -1,3 +1,4 @@ +import type { SearchMemoryOptions } from "mem0ai"; import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"; import type MemoryClient from "mem0ai"; import type { Mem0Config, ScopeContext, Scope } from "./types.ts"; @@ -34,7 +35,11 @@ export function registerCommands( topK: SEARCH_TOP_K, rerank: true, source: PLATFORM_SOURCE, - }); + // Widened by exactly this one property. `source` reaches the wire via the + // SDK's camelToSnakeKeys spread, but it is absent from SearchMemoryOptions + // in the published mem0ai types. A blanket `as never` would also disable + // checking of filters, threshold, topK and rerank above. + } as SearchMemoryOptions & { source: string }); return result.results ?? []; }; From 2097e29edba715b37f9e3e169b49eccbe2136de6 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 22:37:16 +0530 Subject: [PATCH 14/30] docs(plugins): restore the telemetry sweep this branch's merge reverted The pr4 -> pr5 merge resolved eleven documentation files to the pre-sweep side, undoing aa770aa6 in its entirety. Because the stack lands in order, main would have taken the corrected wording in pr1 and then had it reverted by pr5, leaving the shipped claim wrong again: - all six hosts' pause skill back to "a minimal anonymous telemetry ping" - docs/integrations/deepseek-plugin.mdx back to "Anonymous usage events" - integrations/zapier-mem0/README.md back to advertising telemetry the app does not have, with an MEM0_TELEMETRY opt-out that controls nothing - the README data-dir listing back to omitting telemetry-salt and install-state.json, both of which this stack creates - the README and docs property lists back to the enumeration that drifts Restored verbatim from pr4. No file here is in pr5's scope, and the full pr4..pr5 diff is now surface headers only. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- docs/integrations/claude-code.mdx | 11 ++++++++--- docs/integrations/deepseek-plugin.mdx | 2 +- .../agent-plugin-core/skills/pause/SKILL.md.tmpl | 4 ++-- integrations/antigravity-plugin/skills/pause/SKILL.md | 4 ++-- integrations/claude-code-plugin/README.md | 6 +++++- integrations/claude-code-plugin/skills/pause/SKILL.md | 4 ++-- integrations/codex-plugin/skills/pause/SKILL.md | 4 ++-- integrations/cursor-plugin/skills/pause/SKILL.md | 4 ++-- integrations/kimi-plugin/skills/pause/SKILL.md | 4 ++-- integrations/mem0-agent-plugin/skills/pause/SKILL.md | 4 ++-- integrations/zapier-mem0/README.md | 2 +- 11 files changed, 29 insertions(+), 20 deletions(-) diff --git a/docs/integrations/claude-code.mdx b/docs/integrations/claude-code.mdx index c4b5a2c35..4277bb90e 100644 --- a/docs/integrations/claude-code.mdx +++ b/docs/integrations/claude-code.mdx @@ -183,11 +183,16 @@ the same way the Python SDK and the CLI attribute theirs. Without a key they are sent under a random per-machine id. Each event carries the event name, the plugin version, the harness it ran in, -your OS and Python version, timings, counts, and a coarse failure label. -Repository and session identifiers are hashed with a random salt generated on -your machine and never sent, so they cannot be linked back to a repository name +your OS and Python version, and per-event properties describing what happened: +timings, counts, coarse outcome and failure labels, and which model was +configured. Repository and session identifiers are hashed with a random salt +generated on your machine, so they cannot be linked back to a repository name or path. +The exact set is enforced in code rather than by this list: every property is +filtered through a denylist of sensitive keys and credential-shaped values are +redacted before anything is sent. + Prompts, memory text, queries, file paths, repository names, and API keys are never sent. diff --git a/docs/integrations/deepseek-plugin.mdx b/docs/integrations/deepseek-plugin.mdx index 16b8badaf..0242496e1 100644 --- a/docs/integrations/deepseek-plugin.mdx +++ b/docs/integrations/deepseek-plugin.mdx @@ -114,7 +114,7 @@ Both tools also accept optional per-call `userId`, `agentId`, and `runId` params ## Telemetry -Writes are tagged `source="DEEPSEEK_HARNESS"` so Mem0 can attribute usage to this integration. Anonymous usage events include operation names, durations, result counts, and coarse failure kinds. Queries, memory text, entity IDs, and API keys are never included. Set `MEM0_TELEMETRY=false` to opt out. +Writes are tagged `source="DEEPSEEK_HARNESS"` so Mem0 can attribute usage to this integration. Usage events include operation names, durations, result counts, and coarse failure kinds. They are **not anonymous**: when an API key is configured they are sent under your Mem0 account email, the same way the SDK attributes its own. Queries, memory text, entity IDs, and API keys are never included. Set `MEM0_TELEMETRY=false` to opt out. This plugin is a developer preview and tracks the evolving DeepSeek Harness plugin API. diff --git a/integrations/agent-plugin-core/skills/pause/SKILL.md.tmpl b/integrations/agent-plugin-core/skills/pause/SKILL.md.tmpl index 9cc720c7a..569305ec7 100644 --- a/integrations/agent-plugin-core/skills/pause/SKILL.md.tmpl +++ b/integrations/agent-plugin-core/skills/pause/SKILL.md.tmpl @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "{{PLUGIN_ROOT}}/core/memory_cli.py" --harness "{{HARNESS_ID}}" {{PLUGIN_DATA_ARG}} pause diff --git a/integrations/antigravity-plugin/skills/pause/SKILL.md b/integrations/antigravity-plugin/skills/pause/SKILL.md index e88f7d315..77b4146b6 100644 --- a/integrations/antigravity-plugin/skills/pause/SKILL.md +++ b/integrations/antigravity-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${ANTIGRAVITY_PLUGIN_ROOT}/core/memory_cli.py" --harness "antigravity" pause diff --git a/integrations/claude-code-plugin/README.md b/integrations/claude-code-plugin/README.md index 872071abe..b58f54c79 100644 --- a/integrations/claude-code-plugin/README.md +++ b/integrations/claude-code-plugin/README.md @@ -137,6 +137,8 @@ Local data lives in `${CLAUDE_PLUGIN_DATA}`: - `flush-worker.log`: whether memory creation succeeded - `plugin-errors.log`: hook errors (no credentials) - `telemetry.jsonl` / `telemetry-identity.json`: usage events and the id they are sent under +- `telemetry-salt`: random per-install salt for the repo and session hashes +- `install-state.json`: records that install has been counted once on this machine Mem0 receives captured user messages, Claude's answers, sidekick assignments and completed responses, and changed file paths. When a failed command is recorded, extraction can also include bounded command details and results. Complete files and general tool output stay on your machine. Values that look like credentials are redacted before anything is sent. @@ -146,7 +148,9 @@ Usage events (which hook ran, timing, result counts, failure types) so Mem0 can **These events are not anonymous.** When an API key is configured — which installing the plugin requires — events are sent under your Mem0 account email, the same way the Python SDK and the CLI attribute theirs. Without a key they are sent under a random per-machine id. -What each event carries: the event name, the plugin version, the harness it ran in, your OS and Python version, timings, counts, and a coarse failure label. Repository and session identifiers are hashed with a random salt generated on your machine and never sent, so they cannot be linked back to a repository name or path. +What each event carries: the event name, the plugin version, the harness it ran in, your OS and Python version, and per-event properties describing what happened — timings, counts, coarse outcome and failure labels, and which model was configured. Repository and session identifiers are hashed with a random salt generated on your machine, so they cannot be linked back to a repository name or path. + +Rather than restate a list that drifts, the exact set is enforced in code: `telemetry.record` filters every property through a denylist of sensitive keys and redacts credential-shaped values. See `_PRIVATE_KEYS` in `core/telemetry.py`. Prompts, memory text, queries, file paths, repository names, and API keys are never sent. diff --git a/integrations/claude-code-plugin/skills/pause/SKILL.md b/integrations/claude-code-plugin/skills/pause/SKILL.md index 5aef04f39..ce69d13d2 100644 --- a/integrations/claude-code-plugin/skills/pause/SKILL.md +++ b/integrations/claude-code-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${CLAUDE_PLUGIN_ROOT}/core/memory_cli.py" --harness "claude-code" --plugin-data-dir "${CLAUDE_PLUGIN_DATA}" pause diff --git a/integrations/codex-plugin/skills/pause/SKILL.md b/integrations/codex-plugin/skills/pause/SKILL.md index d8a52f47b..c8f8ddd5f 100644 --- a/integrations/codex-plugin/skills/pause/SKILL.md +++ b/integrations/codex-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${PLUGIN_ROOT}/core/memory_cli.py" --harness "codex" --plugin-data-dir "${PLUGIN_DATA}" pause diff --git a/integrations/cursor-plugin/skills/pause/SKILL.md b/integrations/cursor-plugin/skills/pause/SKILL.md index 634385145..17384c368 100644 --- a/integrations/cursor-plugin/skills/pause/SKILL.md +++ b/integrations/cursor-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${CURSOR_PLUGIN_ROOT}/core/memory_cli.py" --harness "cursor" pause diff --git a/integrations/kimi-plugin/skills/pause/SKILL.md b/integrations/kimi-plugin/skills/pause/SKILL.md index 9f217a468..8f93e3bf7 100644 --- a/integrations/kimi-plugin/skills/pause/SKILL.md +++ b/integrations/kimi-plugin/skills/pause/SKILL.md @@ -7,8 +7,8 @@ disable-model-invocation: true # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${KIMI_PLUGIN_ROOT}/core/memory_cli.py" --harness "kimi" pause diff --git a/integrations/mem0-agent-plugin/skills/pause/SKILL.md b/integrations/mem0-agent-plugin/skills/pause/SKILL.md index c6316dd0b..a87d6c3ee 100644 --- a/integrations/mem0-agent-plugin/skills/pause/SKILL.md +++ b/integrations/mem0-agent-plugin/skills/pause/SKILL.md @@ -6,8 +6,8 @@ description: Pause Mem0 memory capture on this machine. Use when the user wants # Pause memory capture To pause (hooks stop capturing and sending session content; a minimal -anonymous telemetry ping still fires at session start unless -`MEM0_TELEMETRY=false`): +telemetry ping still fires at session start, under your Mem0 account email, +unless `MEM0_TELEMETRY=false`): ```bash python3 "${PLUGIN_ROOT}/core/memory_cli.py" --harness "coding-agent" pause diff --git a/integrations/zapier-mem0/README.md b/integrations/zapier-mem0/README.md index 7b3f5ed0f..dab21d3f3 100644 --- a/integrations/zapier-mem0/README.md +++ b/integrations/zapier-mem0/README.md @@ -32,7 +32,7 @@ pnpm test:unit # offline unit tests (mocked, no network) MEM0_API_KEY=m0-... pnpm test # unit + live E2E against api.mem0.ai ``` -Anonymous usage telemetry is sent to Mem0; opt out with `MEM0_TELEMETRY=false`. +This app sends no telemetry of its own. Its API requests carry `source: "ZAPIER"` so Mem0 can see aggregate usage of the integration. To deploy (maintainers): `pnpm build && zapier push`. From f8a9d524be5e1db738c6514ae07ab61d8b3a0bef Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Tue, 15 Sep 2026 22:44:17 +0530 Subject: [PATCH 15/30] docs(openclaw): correct the anonymity claim to match how it identifies events The sweep in aa770aa6 deliberately left this page alone, reasoning that hashing the email is materially different from sending it. Reading integrations/openclaw/telemetry.ts does not support that: distinctId() is an unsalted sha256 of the account email, and Mem0 holds the emails it is derived from, so recovering the account is a table join. resolveEmail() also rewrites already-queued events onto that id, and identifyAnonymous() fires a PostHog $identify that merges the prior random id into it for good. That is pseudonymous, not anonymous, and it is the same mismatch between the stated privacy posture and the wire format that this stack exists to close. The opt-out is unchanged and still correct. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- docs/integrations/openclaw.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/integrations/openclaw.mdx b/docs/integrations/openclaw.mdx index a9642d444..fd7d449d9 100644 --- a/docs/integrations/openclaw.mdx +++ b/docs/integrations/openclaw.mdx @@ -481,7 +481,9 @@ Plugin config is stored in `~/.openclaw/openclaw.json` with file permissions `0o ### Telemetry -Anonymous usage telemetry (PostHog) is enabled by default to help improve the plugin. No conversation content or memory values are included, only event counts (recall, capture, tool usage, CLI commands). +Usage telemetry (PostHog) is enabled by default to help improve the plugin. No conversation content or memory values are included, only event counts (recall, capture, tool usage, CLI commands). + +These events are **not anonymous**. OpenClaw does not send your account email the way the SDK does, but it does send an unsalted SHA-256 hash of it, falling back to a hash of the API key and then to a random per-machine id. Mem0 holds the email the hash is derived from, so the hash identifies your account rather than concealing it. The first run that resolves an account also emits a PostHog `$identify`, which permanently merges any earlier random id into that identity. To opt out, set the environment variable: From f80d21fa0653a19c13deed476dbd9bd3291f3f3f Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Wed, 16 Sep 2026 02:49:11 +0530 Subject: [PATCH 16/30] fix(plugins): do not claim a host application the portable bundle cannot know Review point. The portable bundle is built with host "coding-agent", and the build wrote that straight into PLATFORM_APPLICATION, so every portable install sent X-Application: coding-agent. That value is not in the platform's allowlist, so it was already being dropped server-side. The effect was the worst of both: the wire claimed we knew the editor, the stored event recorded that we did not, and nothing said which was right. An absent header says the same thing honestly and costs a lookup. HARNESS_ID stays "coding-agent". It is the PostHog-side label, it is true, and grouping portable installs together there is useful. Native bundles are unchanged apart from the regenerated comment. Covered by two new build tests: portable declares no application, and each native names the host it was generated for. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- integrations/AGENTS.md | 9 ++++++ integrations/agent-plugin-core/build/build.py | 16 ++++++++-- .../agent-plugin-core/tests/test_build.py | 32 +++++++++++++++++++ .../antigravity-plugin/core/_harness_id.py | 2 ++ .../claude-code-plugin/core/_harness_id.py | 2 ++ integrations/codex-plugin/core/_harness_id.py | 2 ++ .../cursor-plugin/core/_harness_id.py | 2 ++ integrations/kimi-plugin/core/_harness_id.py | 2 ++ .../mem0-agent-plugin/core/_harness_id.py | 4 ++- 9 files changed, 67 insertions(+), 4 deletions(-) diff --git a/integrations/AGENTS.md b/integrations/AGENTS.md index 9b85cddb1..221c8206f 100644 --- a/integrations/AGENTS.md +++ b/integrations/AGENTS.md @@ -82,6 +82,15 @@ The backend recognizes a fixed list of source values and buckets everything else into `OTHERS`. A new value has to land in the platform's `EventSource` enum, so do not invent one without that change going in too. +`X-Application` is allowlisted the same way, and this one has a rule of its own: +**omit the header when you do not know the host.** A value outside the allowlist +is discarded server-side, so guessing produces an event that claims an +attribution we do not actually have. The portable bundle is the case that +matters. It runs in whatever editor a user drops it into, so its build leaves +`PLATFORM_APPLICATION` empty and `memory_core` sends no header at all, while the +native bundles each name the host they were generated for. If you add a build +target, decide which of those two it is. + ## Adding an integration 1. For a native coding-agent host, add `integrations/-plugin/` with `plugin-build.json`, its manifest, and a thin adapter, then generate its shared runtime. Portable clients use the single `mem0-agent-plugin/` package. Independent TypeScript integrations stay self-contained and import shared lifecycle behavior from `agent-plugin-core/typescript/`. diff --git a/integrations/agent-plugin-core/build/build.py b/integrations/agent-plugin-core/build/build.py index e675efb02..3059b9b1f 100644 --- a/integrations/agent-plugin-core/build/build.py +++ b/integrations/agent-plugin-core/build/build.py @@ -81,15 +81,23 @@ def replace_output(staged: Path, output: Path) -> Path: return output -def _render_harness_id(host: str) -> str: +def _render_harness_id(host: str, *, portable: bool = False) -> str: """Emit core/_harness_id.py for one host. Carries both vocabularies from a single definition: the PostHog `source` tag and the platform's X-Mem0-Source / X-Application pair. Keeping them together is what stops the two from drifting into separate vocabularies for the same thing. + + The portable bundle runs in whatever editor a user drops it into, so it does + not know its host and must not guess one. HARNESS_ID stays "coding-agent", + which is true and useful for grouping in PostHog, but PLATFORM_APPLICATION is + left empty: X-Application names a real host app, is checked against an + allowlist server-side, and a value that is always discarded is worse than no + value -- it reads like an attribution we have and do not. """ tag = host.upper().replace("-", "_") + "_PLUGIN" + application = "" if portable else host return ( '"""Generated by integrations/agent-plugin-core/build/build.py. Do not edit."""\n' "\n" @@ -98,8 +106,10 @@ def _render_harness_id(host: str) -> str: "\n" "# Platform-side vocabulary (mem0_event.source + X-Application). The whole\n" "# plugin family is one source; which editor it runs in is the application.\n" + "# An empty application means the host is unknown, and memory_core omits\n" + "# the header entirely rather than sending a placeholder.\n" 'PLATFORM_SOURCE = "MEM0_PLUGIN"\n' - f'PLATFORM_APPLICATION = "{host}"\n' + f'PLATFORM_APPLICATION = "{application}"\n' ) @@ -122,7 +132,7 @@ def _bundle_python( # to call telemetry.init(). mcp_server.py and the detached telemetry.py sender # never did, which is how MCP searches reported harness=generic and every # batch they drained was labelled MEM0_PLUGIN regardless of the real host. - (core / "_harness_id.py").write_text(_render_harness_id(host), encoding="utf-8") + (core / "_harness_id.py").write_text(_render_harness_id(host, portable=portable), encoding="utf-8") values = { "PLUGIN_ROOT": plugin_root, diff --git a/integrations/agent-plugin-core/tests/test_build.py b/integrations/agent-plugin-core/tests/test_build.py index 54b5e5c6a..23295cc38 100644 --- a/integrations/agent-plugin-core/tests/test_build.py +++ b/integrations/agent-plugin-core/tests/test_build.py @@ -70,6 +70,38 @@ def test_portable_bundle_is_conformant_and_self_contained(tmp_path: Path) -> Non assert not any(path.is_symlink() for path in root.rglob("*")) +def _harness_identity(root: Path) -> dict[str, str]: + """Read the generated core/_harness_id.py without importing it.""" + values: dict[str, str] = {} + for line in (root / "core" / "_harness_id.py").read_text(encoding="utf-8").splitlines(): + if "=" in line and not line.lstrip().startswith("#"): + name, _, raw = line.partition("=") + values[name.strip()] = raw.strip().strip('"') + return values + + +def test_the_portable_bundle_declares_no_host_application(tmp_path: Path) -> None: + """It runs in whatever editor a user drops it into, so it cannot know the host. + + X-Application is allowlisted server-side. A guessed value is silently dropped + there, which is the worst outcome: the wire says we know the host and the + stored event says we do not. + """ + identity = _harness_identity(build("mem0-agent-plugin", "portable", tmp_path / "portable")) + + assert identity["PLATFORM_APPLICATION"] == "" + # The PostHog-side label is still useful for grouping and stays populated. + assert identity["HARNESS_ID"] == "coding-agent" + assert identity["PLATFORM_SOURCE"] == "MEM0_PLUGIN" + + +@pytest.mark.parametrize("host", ["claude-code", "cursor", "codex", "kimi", "antigravity"]) +def test_a_native_bundle_names_the_host_it_was_built_for(host: str, tmp_path: Path) -> None: + identity = _harness_identity(build(host, "native", tmp_path / host)) + + assert identity["PLATFORM_APPLICATION"] == host + + @pytest.mark.parametrize("host", ["claude-code", "cursor", "codex", "kimi", "antigravity"]) def test_native_bundle_is_self_contained(host: str, tmp_path: Path) -> None: root = build(host, "native", tmp_path / host) diff --git a/integrations/antigravity-plugin/core/_harness_id.py b/integrations/antigravity-plugin/core/_harness_id.py index 2c8a515f4..18b7f68ec 100644 --- a/integrations/antigravity-plugin/core/_harness_id.py +++ b/integrations/antigravity-plugin/core/_harness_id.py @@ -5,5 +5,7 @@ SOURCE_TAG = "ANTIGRAVITY_PLUGIN" # Platform-side vocabulary (mem0_event.source + X-Application). The whole # plugin family is one source; which editor it runs in is the application. +# An empty application means the host is unknown, and memory_core omits +# the header entirely rather than sending a placeholder. PLATFORM_SOURCE = "MEM0_PLUGIN" PLATFORM_APPLICATION = "antigravity" diff --git a/integrations/claude-code-plugin/core/_harness_id.py b/integrations/claude-code-plugin/core/_harness_id.py index 6c3e1ce15..9c4949408 100644 --- a/integrations/claude-code-plugin/core/_harness_id.py +++ b/integrations/claude-code-plugin/core/_harness_id.py @@ -5,5 +5,7 @@ SOURCE_TAG = "CLAUDE_CODE_PLUGIN" # Platform-side vocabulary (mem0_event.source + X-Application). The whole # plugin family is one source; which editor it runs in is the application. +# An empty application means the host is unknown, and memory_core omits +# the header entirely rather than sending a placeholder. PLATFORM_SOURCE = "MEM0_PLUGIN" PLATFORM_APPLICATION = "claude-code" diff --git a/integrations/codex-plugin/core/_harness_id.py b/integrations/codex-plugin/core/_harness_id.py index 152313a21..47938ee08 100644 --- a/integrations/codex-plugin/core/_harness_id.py +++ b/integrations/codex-plugin/core/_harness_id.py @@ -5,5 +5,7 @@ SOURCE_TAG = "CODEX_PLUGIN" # Platform-side vocabulary (mem0_event.source + X-Application). The whole # plugin family is one source; which editor it runs in is the application. +# An empty application means the host is unknown, and memory_core omits +# the header entirely rather than sending a placeholder. PLATFORM_SOURCE = "MEM0_PLUGIN" PLATFORM_APPLICATION = "codex" diff --git a/integrations/cursor-plugin/core/_harness_id.py b/integrations/cursor-plugin/core/_harness_id.py index 40241a7f4..0e20bf1ff 100644 --- a/integrations/cursor-plugin/core/_harness_id.py +++ b/integrations/cursor-plugin/core/_harness_id.py @@ -5,5 +5,7 @@ SOURCE_TAG = "CURSOR_PLUGIN" # Platform-side vocabulary (mem0_event.source + X-Application). The whole # plugin family is one source; which editor it runs in is the application. +# An empty application means the host is unknown, and memory_core omits +# the header entirely rather than sending a placeholder. PLATFORM_SOURCE = "MEM0_PLUGIN" PLATFORM_APPLICATION = "cursor" diff --git a/integrations/kimi-plugin/core/_harness_id.py b/integrations/kimi-plugin/core/_harness_id.py index aa17750b1..83ab061ef 100644 --- a/integrations/kimi-plugin/core/_harness_id.py +++ b/integrations/kimi-plugin/core/_harness_id.py @@ -5,5 +5,7 @@ SOURCE_TAG = "KIMI_PLUGIN" # Platform-side vocabulary (mem0_event.source + X-Application). The whole # plugin family is one source; which editor it runs in is the application. +# An empty application means the host is unknown, and memory_core omits +# the header entirely rather than sending a placeholder. PLATFORM_SOURCE = "MEM0_PLUGIN" PLATFORM_APPLICATION = "kimi" diff --git a/integrations/mem0-agent-plugin/core/_harness_id.py b/integrations/mem0-agent-plugin/core/_harness_id.py index b0836d6de..3efd000f8 100644 --- a/integrations/mem0-agent-plugin/core/_harness_id.py +++ b/integrations/mem0-agent-plugin/core/_harness_id.py @@ -5,5 +5,7 @@ SOURCE_TAG = "CODING_AGENT_PLUGIN" # Platform-side vocabulary (mem0_event.source + X-Application). The whole # plugin family is one source; which editor it runs in is the application. +# An empty application means the host is unknown, and memory_core omits +# the header entirely rather than sending a placeholder. PLATFORM_SOURCE = "MEM0_PLUGIN" -PLATFORM_APPLICATION = "coding-agent" +PLATFORM_APPLICATION = "" From 7710a4e180de38813779fae0322914ca8b01a46e Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Wed, 16 Sep 2026 20:33:54 +0530 Subject: [PATCH 17/30] fix(plugins): publish the salt atomically, and omit the hash when there is none Review finding from @kartik-mem0 on this PR. O_CREAT|O_EXCL then write leaves a window where the salt file exists and is empty. Hooks are short-lived processes firing on every tool call and people run several agent windows, so a concurrent reader lands in that window, reads nothing, and falls back to a digest of the salt file's own path, memoized for its whole run. That path is guessable, so the race silently replaced the privacy control with something an attacker can compute, and hashed the same repository two ways depending on timing. The value is now written to a private temp file, fsynced, and published with os.link, which is atomic and fails if another process already published one. Link rather than replace, so losing the race adopts their salt instead of clobbering it. The temp file is removed either way. The derived fallback is gone rather than fixed. _scoped_digest returns "" when there is no salt and record() omits the property, because an unsalted digest over a git remote or a home-directory path is close to plaintext, and shipping one under a name that says hash is worse than sending nothing. Three tests: the racing reader never sees the name half-written, a second writer adopts the first's salt and leaves no temp file, and an unwritable data directory drops the property instead of emitting a weak one. The old test asserted the fallback behaviour and is replaced. 265 passed, 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/telemetry.py | 61 +++++++++++++------ .../antigravity-plugin/core/telemetry.py | 61 +++++++++++++------ .../claude-code-plugin/core/telemetry.py | 61 +++++++++++++------ .../tests/test_telemetry.py | 57 +++++++++++++++-- integrations/codex-plugin/core/telemetry.py | 61 +++++++++++++------ integrations/cursor-plugin/core/telemetry.py | 61 +++++++++++++------ integrations/kimi-plugin/core/telemetry.py | 61 +++++++++++++------ .../mem0-agent-plugin/core/telemetry.py | 61 +++++++++++++------ 8 files changed, 359 insertions(+), 125 deletions(-) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 239836604..2cb1056e0 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -116,36 +116,49 @@ def _install_salt() -> str: keys off that file, so recording an event would silently suppress the install event. - On a read-only or full data directory the fallback is derived from the data - directory path: stable for the machine rather than random per call, so the - failure mode is a weaker salt and not unbounded cardinality in PostHog. + Published atomically, and there is deliberately no derived fallback. Creating + the file with O_CREAT|O_EXCL and then writing into it leaves a window where + the file exists and is empty, and a concurrent hook that reads it in that + window gets nothing. Falling back to a digest of the path would hand that + process a salt an attacker can compute, memoized for its whole run, which is + the privacy control this function exists to provide silently turning itself + off under load. The salt is written to a private temp file first and linked + into place, so the name either does not exist or already has the full value. + + Returns "" when it genuinely cannot persist. Callers omit the hash entirely + rather than emit an unsalted one. """ global _salt_cache if _salt_cache: return _salt_cache path = _salt_path() + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) - handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + handle = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + stream.flush() + os.fsync(stream.fileno()) try: - with os.fdopen(handle, "w", encoding="utf-8") as stream: - stream.write(uuid.uuid4().hex) + # Atomic claim: fails if another process already published one. + # os.link rather than replace, which would clobber theirs. + os.link(temporary, path) + except FileExistsError: + pass + except OSError: + pass + finally: + try: + temporary.unlink() except OSError: pass - except FileExistsError: - pass - except OSError: - # Cannot persist. Stable-per-machine beats random-per-call. - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() - return _salt_cache try: _salt_cache = path.read_text(encoding="utf-8").strip() except OSError: _salt_cache = "" - if not _salt_cache: - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() return _salt_cache @@ -158,10 +171,17 @@ def _scoped_digest(value: str, length: int = 16) -> str: privacy control without the salt. Salting per install keeps every within-account join the analytics actually use and gives up only cross-machine joins on the same repository, which nothing computes. + + Returns "" when there is no salt, so record() omits the property. An + unsalted digest over this input space is close to plaintext, and emitting one + under a name that implies it is hashed is worse than sending nothing. """ if not value: return "" - return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + salt = _install_salt() + if not salt: + return "" + return hashlib.sha256(f"{salt}:{value}".encode("utf-8")).hexdigest()[:length] def _safe_value(value: Any) -> Any: @@ -252,10 +272,17 @@ def record( os=sys.platform, python_version=platform.python_version(), ) + # Assigned only when the digest is real. _scoped_digest returns "" when + # the salt could not be persisted, and an empty property is worse than an + # absent one: it survives the None filter below and reads as a value. if repo is not None: - properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) + repo_hash = _scoped_digest(getattr(repo, "identity", "")) + if repo_hash: + properties["repo_hash"] = repo_hash if session_id: - properties["session_hash"] = _scoped_digest(session_id) + session_hash = _scoped_digest(session_id) + if session_hash: + properties["session_hash"] = session_hash line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 239836604..2cb1056e0 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -116,36 +116,49 @@ def _install_salt() -> str: keys off that file, so recording an event would silently suppress the install event. - On a read-only or full data directory the fallback is derived from the data - directory path: stable for the machine rather than random per call, so the - failure mode is a weaker salt and not unbounded cardinality in PostHog. + Published atomically, and there is deliberately no derived fallback. Creating + the file with O_CREAT|O_EXCL and then writing into it leaves a window where + the file exists and is empty, and a concurrent hook that reads it in that + window gets nothing. Falling back to a digest of the path would hand that + process a salt an attacker can compute, memoized for its whole run, which is + the privacy control this function exists to provide silently turning itself + off under load. The salt is written to a private temp file first and linked + into place, so the name either does not exist or already has the full value. + + Returns "" when it genuinely cannot persist. Callers omit the hash entirely + rather than emit an unsalted one. """ global _salt_cache if _salt_cache: return _salt_cache path = _salt_path() + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) - handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + handle = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + stream.flush() + os.fsync(stream.fileno()) try: - with os.fdopen(handle, "w", encoding="utf-8") as stream: - stream.write(uuid.uuid4().hex) + # Atomic claim: fails if another process already published one. + # os.link rather than replace, which would clobber theirs. + os.link(temporary, path) + except FileExistsError: + pass + except OSError: + pass + finally: + try: + temporary.unlink() except OSError: pass - except FileExistsError: - pass - except OSError: - # Cannot persist. Stable-per-machine beats random-per-call. - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() - return _salt_cache try: _salt_cache = path.read_text(encoding="utf-8").strip() except OSError: _salt_cache = "" - if not _salt_cache: - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() return _salt_cache @@ -158,10 +171,17 @@ def _scoped_digest(value: str, length: int = 16) -> str: privacy control without the salt. Salting per install keeps every within-account join the analytics actually use and gives up only cross-machine joins on the same repository, which nothing computes. + + Returns "" when there is no salt, so record() omits the property. An + unsalted digest over this input space is close to plaintext, and emitting one + under a name that implies it is hashed is worse than sending nothing. """ if not value: return "" - return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + salt = _install_salt() + if not salt: + return "" + return hashlib.sha256(f"{salt}:{value}".encode("utf-8")).hexdigest()[:length] def _safe_value(value: Any) -> Any: @@ -252,10 +272,17 @@ def record( os=sys.platform, python_version=platform.python_version(), ) + # Assigned only when the digest is real. _scoped_digest returns "" when + # the salt could not be persisted, and an empty property is worse than an + # absent one: it survives the None filter below and reads as a value. if repo is not None: - properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) + repo_hash = _scoped_digest(getattr(repo, "identity", "")) + if repo_hash: + properties["repo_hash"] = repo_hash if session_id: - properties["session_hash"] = _scoped_digest(session_id) + session_hash = _scoped_digest(session_id) + if session_hash: + properties["session_hash"] = session_hash line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 239836604..2cb1056e0 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -116,36 +116,49 @@ def _install_salt() -> str: keys off that file, so recording an event would silently suppress the install event. - On a read-only or full data directory the fallback is derived from the data - directory path: stable for the machine rather than random per call, so the - failure mode is a weaker salt and not unbounded cardinality in PostHog. + Published atomically, and there is deliberately no derived fallback. Creating + the file with O_CREAT|O_EXCL and then writing into it leaves a window where + the file exists and is empty, and a concurrent hook that reads it in that + window gets nothing. Falling back to a digest of the path would hand that + process a salt an attacker can compute, memoized for its whole run, which is + the privacy control this function exists to provide silently turning itself + off under load. The salt is written to a private temp file first and linked + into place, so the name either does not exist or already has the full value. + + Returns "" when it genuinely cannot persist. Callers omit the hash entirely + rather than emit an unsalted one. """ global _salt_cache if _salt_cache: return _salt_cache path = _salt_path() + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) - handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + handle = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + stream.flush() + os.fsync(stream.fileno()) try: - with os.fdopen(handle, "w", encoding="utf-8") as stream: - stream.write(uuid.uuid4().hex) + # Atomic claim: fails if another process already published one. + # os.link rather than replace, which would clobber theirs. + os.link(temporary, path) + except FileExistsError: + pass + except OSError: + pass + finally: + try: + temporary.unlink() except OSError: pass - except FileExistsError: - pass - except OSError: - # Cannot persist. Stable-per-machine beats random-per-call. - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() - return _salt_cache try: _salt_cache = path.read_text(encoding="utf-8").strip() except OSError: _salt_cache = "" - if not _salt_cache: - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() return _salt_cache @@ -158,10 +171,17 @@ def _scoped_digest(value: str, length: int = 16) -> str: privacy control without the salt. Salting per install keeps every within-account join the analytics actually use and gives up only cross-machine joins on the same repository, which nothing computes. + + Returns "" when there is no salt, so record() omits the property. An + unsalted digest over this input space is close to plaintext, and emitting one + under a name that implies it is hashed is worse than sending nothing. """ if not value: return "" - return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + salt = _install_salt() + if not salt: + return "" + return hashlib.sha256(f"{salt}:{value}".encode("utf-8")).hexdigest()[:length] def _safe_value(value: Any) -> Any: @@ -252,10 +272,17 @@ def record( os=sys.platform, python_version=platform.python_version(), ) + # Assigned only when the digest is real. _scoped_digest returns "" when + # the salt could not be persisted, and an empty property is worse than an + # absent one: it survives the None filter below and reads as a value. if repo is not None: - properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) + repo_hash = _scoped_digest(getattr(repo, "identity", "")) + if repo_hash: + properties["repo_hash"] = repo_hash if session_id: - properties["session_hash"] = _scoped_digest(session_id) + session_hash = _scoped_digest(session_id) + if session_hash: + properties["session_hash"] = session_hash line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/claude-code-plugin/tests/test_telemetry.py b/integrations/claude-code-plugin/tests/test_telemetry.py index eaa741ac5..b816b629e 100644 --- a/integrations/claude-code-plugin/tests/test_telemetry.py +++ b/integrations/claude-code-plugin/tests/test_telemetry.py @@ -309,14 +309,59 @@ def test_salt_does_not_touch_the_identity_file(isolated_env): assert not telemetry._identity_path().exists() -def test_salt_is_stable_when_it_cannot_be_persisted(isolated_env, monkeypatch): - """A read-only data dir must degrade to a weaker salt, not to random-per-call. +def test_no_salt_means_no_hash_rather_than_an_unsalted_one(isolated_env, monkeypatch): + """A read-only data dir drops the property; it must not emit a weak digest. - Random per call is unbounded cardinality in PostHog, which is worse than no - salt at all. + The previous fallback was a digest of the salt file's own path, which an + attacker can compute, memoized for the whole process. A property named + repo_hash carrying an effectively unsalted digest is worse than no property: + it reads as protected and is not. """ telemetry._salt_cache = "" monkeypatch.setattr(telemetry.os, "open", lambda *a, **k: (_ for _ in ()).throw(OSError("read-only"))) - first = telemetry._install_salt() + + assert telemetry._install_salt() == "" + assert telemetry._scoped_digest("git@github.com:acme/secret.git") == "" + + +def test_a_half_written_salt_is_never_visible_to_another_process(isolated_env, monkeypatch): + """The window this closes: file created, value not yet written. + + O_CREAT|O_EXCL then write leaves the name present and empty in between. A + hook reading it there used to get "", fall back to the path digest and cache + that for its whole run, so the same repo hashed two ways depending on timing. + Publishing by link means the name either does not exist or is complete. + """ telemetry._salt_cache = "" - assert telemetry._install_salt() == first + salt_path = telemetry._salt_path() + observed = [] + + real_link = telemetry.os.link + + def observing_link(source, target): + # Stand where the racing reader stands: after the temp file is written, + # before the real name exists. + observed.append(salt_path.exists()) + return real_link(source, target) + + monkeypatch.setattr(telemetry.os, "link", observing_link) + salt = telemetry._install_salt() + + assert observed == [False], "the salt name existed before it held a value" + assert len(salt) == 32 + assert salt_path.read_text(encoding="utf-8").strip() == salt + + +def test_a_concurrent_writer_does_not_clobber_the_published_salt(isolated_env): + """Second process to finish must adopt the first one's salt, not replace it. + + os.link rather than os.replace is what makes losing the race harmless. + """ + telemetry._salt_cache = "" + first = telemetry._install_salt() + + telemetry._salt_cache = "" + second = telemetry._install_salt() + + assert second == first + assert not list(telemetry._salt_path().parent.glob("telemetry-salt.*.tmp")), "temp file left behind" diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 239836604..2cb1056e0 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -116,36 +116,49 @@ def _install_salt() -> str: keys off that file, so recording an event would silently suppress the install event. - On a read-only or full data directory the fallback is derived from the data - directory path: stable for the machine rather than random per call, so the - failure mode is a weaker salt and not unbounded cardinality in PostHog. + Published atomically, and there is deliberately no derived fallback. Creating + the file with O_CREAT|O_EXCL and then writing into it leaves a window where + the file exists and is empty, and a concurrent hook that reads it in that + window gets nothing. Falling back to a digest of the path would hand that + process a salt an attacker can compute, memoized for its whole run, which is + the privacy control this function exists to provide silently turning itself + off under load. The salt is written to a private temp file first and linked + into place, so the name either does not exist or already has the full value. + + Returns "" when it genuinely cannot persist. Callers omit the hash entirely + rather than emit an unsalted one. """ global _salt_cache if _salt_cache: return _salt_cache path = _salt_path() + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) - handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + handle = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + stream.flush() + os.fsync(stream.fileno()) try: - with os.fdopen(handle, "w", encoding="utf-8") as stream: - stream.write(uuid.uuid4().hex) + # Atomic claim: fails if another process already published one. + # os.link rather than replace, which would clobber theirs. + os.link(temporary, path) + except FileExistsError: + pass + except OSError: + pass + finally: + try: + temporary.unlink() except OSError: pass - except FileExistsError: - pass - except OSError: - # Cannot persist. Stable-per-machine beats random-per-call. - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() - return _salt_cache try: _salt_cache = path.read_text(encoding="utf-8").strip() except OSError: _salt_cache = "" - if not _salt_cache: - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() return _salt_cache @@ -158,10 +171,17 @@ def _scoped_digest(value: str, length: int = 16) -> str: privacy control without the salt. Salting per install keeps every within-account join the analytics actually use and gives up only cross-machine joins on the same repository, which nothing computes. + + Returns "" when there is no salt, so record() omits the property. An + unsalted digest over this input space is close to plaintext, and emitting one + under a name that implies it is hashed is worse than sending nothing. """ if not value: return "" - return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + salt = _install_salt() + if not salt: + return "" + return hashlib.sha256(f"{salt}:{value}".encode("utf-8")).hexdigest()[:length] def _safe_value(value: Any) -> Any: @@ -252,10 +272,17 @@ def record( os=sys.platform, python_version=platform.python_version(), ) + # Assigned only when the digest is real. _scoped_digest returns "" when + # the salt could not be persisted, and an empty property is worse than an + # absent one: it survives the None filter below and reads as a value. if repo is not None: - properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) + repo_hash = _scoped_digest(getattr(repo, "identity", "")) + if repo_hash: + properties["repo_hash"] = repo_hash if session_id: - properties["session_hash"] = _scoped_digest(session_id) + session_hash = _scoped_digest(session_id) + if session_hash: + properties["session_hash"] = session_hash line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 239836604..2cb1056e0 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -116,36 +116,49 @@ def _install_salt() -> str: keys off that file, so recording an event would silently suppress the install event. - On a read-only or full data directory the fallback is derived from the data - directory path: stable for the machine rather than random per call, so the - failure mode is a weaker salt and not unbounded cardinality in PostHog. + Published atomically, and there is deliberately no derived fallback. Creating + the file with O_CREAT|O_EXCL and then writing into it leaves a window where + the file exists and is empty, and a concurrent hook that reads it in that + window gets nothing. Falling back to a digest of the path would hand that + process a salt an attacker can compute, memoized for its whole run, which is + the privacy control this function exists to provide silently turning itself + off under load. The salt is written to a private temp file first and linked + into place, so the name either does not exist or already has the full value. + + Returns "" when it genuinely cannot persist. Callers omit the hash entirely + rather than emit an unsalted one. """ global _salt_cache if _salt_cache: return _salt_cache path = _salt_path() + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) - handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + handle = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + stream.flush() + os.fsync(stream.fileno()) try: - with os.fdopen(handle, "w", encoding="utf-8") as stream: - stream.write(uuid.uuid4().hex) + # Atomic claim: fails if another process already published one. + # os.link rather than replace, which would clobber theirs. + os.link(temporary, path) + except FileExistsError: + pass + except OSError: + pass + finally: + try: + temporary.unlink() except OSError: pass - except FileExistsError: - pass - except OSError: - # Cannot persist. Stable-per-machine beats random-per-call. - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() - return _salt_cache try: _salt_cache = path.read_text(encoding="utf-8").strip() except OSError: _salt_cache = "" - if not _salt_cache: - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() return _salt_cache @@ -158,10 +171,17 @@ def _scoped_digest(value: str, length: int = 16) -> str: privacy control without the salt. Salting per install keeps every within-account join the analytics actually use and gives up only cross-machine joins on the same repository, which nothing computes. + + Returns "" when there is no salt, so record() omits the property. An + unsalted digest over this input space is close to plaintext, and emitting one + under a name that implies it is hashed is worse than sending nothing. """ if not value: return "" - return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + salt = _install_salt() + if not salt: + return "" + return hashlib.sha256(f"{salt}:{value}".encode("utf-8")).hexdigest()[:length] def _safe_value(value: Any) -> Any: @@ -252,10 +272,17 @@ def record( os=sys.platform, python_version=platform.python_version(), ) + # Assigned only when the digest is real. _scoped_digest returns "" when + # the salt could not be persisted, and an empty property is worse than an + # absent one: it survives the None filter below and reads as a value. if repo is not None: - properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) + repo_hash = _scoped_digest(getattr(repo, "identity", "")) + if repo_hash: + properties["repo_hash"] = repo_hash if session_id: - properties["session_hash"] = _scoped_digest(session_id) + session_hash = _scoped_digest(session_id) + if session_hash: + properties["session_hash"] = session_hash line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 239836604..2cb1056e0 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -116,36 +116,49 @@ def _install_salt() -> str: keys off that file, so recording an event would silently suppress the install event. - On a read-only or full data directory the fallback is derived from the data - directory path: stable for the machine rather than random per call, so the - failure mode is a weaker salt and not unbounded cardinality in PostHog. + Published atomically, and there is deliberately no derived fallback. Creating + the file with O_CREAT|O_EXCL and then writing into it leaves a window where + the file exists and is empty, and a concurrent hook that reads it in that + window gets nothing. Falling back to a digest of the path would hand that + process a salt an attacker can compute, memoized for its whole run, which is + the privacy control this function exists to provide silently turning itself + off under load. The salt is written to a private temp file first and linked + into place, so the name either does not exist or already has the full value. + + Returns "" when it genuinely cannot persist. Callers omit the hash entirely + rather than emit an unsalted one. """ global _salt_cache if _salt_cache: return _salt_cache path = _salt_path() + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) - handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + handle = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + stream.flush() + os.fsync(stream.fileno()) try: - with os.fdopen(handle, "w", encoding="utf-8") as stream: - stream.write(uuid.uuid4().hex) + # Atomic claim: fails if another process already published one. + # os.link rather than replace, which would clobber theirs. + os.link(temporary, path) + except FileExistsError: + pass + except OSError: + pass + finally: + try: + temporary.unlink() except OSError: pass - except FileExistsError: - pass - except OSError: - # Cannot persist. Stable-per-machine beats random-per-call. - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() - return _salt_cache try: _salt_cache = path.read_text(encoding="utf-8").strip() except OSError: _salt_cache = "" - if not _salt_cache: - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() return _salt_cache @@ -158,10 +171,17 @@ def _scoped_digest(value: str, length: int = 16) -> str: privacy control without the salt. Salting per install keeps every within-account join the analytics actually use and gives up only cross-machine joins on the same repository, which nothing computes. + + Returns "" when there is no salt, so record() omits the property. An + unsalted digest over this input space is close to plaintext, and emitting one + under a name that implies it is hashed is worse than sending nothing. """ if not value: return "" - return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + salt = _install_salt() + if not salt: + return "" + return hashlib.sha256(f"{salt}:{value}".encode("utf-8")).hexdigest()[:length] def _safe_value(value: Any) -> Any: @@ -252,10 +272,17 @@ def record( os=sys.platform, python_version=platform.python_version(), ) + # Assigned only when the digest is real. _scoped_digest returns "" when + # the salt could not be persisted, and an empty property is worse than an + # absent one: it survives the None filter below and reads as a value. if repo is not None: - properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) + repo_hash = _scoped_digest(getattr(repo, "identity", "")) + if repo_hash: + properties["repo_hash"] = repo_hash if session_id: - properties["session_hash"] = _scoped_digest(session_id) + session_hash = _scoped_digest(session_id) + if session_hash: + properties["session_hash"] = session_hash line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 239836604..2cb1056e0 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -116,36 +116,49 @@ def _install_salt() -> str: keys off that file, so recording an event would silently suppress the install event. - On a read-only or full data directory the fallback is derived from the data - directory path: stable for the machine rather than random per call, so the - failure mode is a weaker salt and not unbounded cardinality in PostHog. + Published atomically, and there is deliberately no derived fallback. Creating + the file with O_CREAT|O_EXCL and then writing into it leaves a window where + the file exists and is empty, and a concurrent hook that reads it in that + window gets nothing. Falling back to a digest of the path would hand that + process a salt an attacker can compute, memoized for its whole run, which is + the privacy control this function exists to provide silently turning itself + off under load. The salt is written to a private temp file first and linked + into place, so the name either does not exist or already has the full value. + + Returns "" when it genuinely cannot persist. Callers omit the hash entirely + rather than emit an unsalted one. """ global _salt_cache if _salt_cache: return _salt_cache path = _salt_path() + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) - handle = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + handle = os.open(temporary, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(handle, "w", encoding="utf-8") as stream: + stream.write(uuid.uuid4().hex) + stream.flush() + os.fsync(stream.fileno()) try: - with os.fdopen(handle, "w", encoding="utf-8") as stream: - stream.write(uuid.uuid4().hex) + # Atomic claim: fails if another process already published one. + # os.link rather than replace, which would clobber theirs. + os.link(temporary, path) + except FileExistsError: + pass + except OSError: + pass + finally: + try: + temporary.unlink() except OSError: pass - except FileExistsError: - pass - except OSError: - # Cannot persist. Stable-per-machine beats random-per-call. - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() - return _salt_cache try: _salt_cache = path.read_text(encoding="utf-8").strip() except OSError: _salt_cache = "" - if not _salt_cache: - _salt_cache = hashlib.sha256(str(path).encode("utf-8")).hexdigest() return _salt_cache @@ -158,10 +171,17 @@ def _scoped_digest(value: str, length: int = 16) -> str: privacy control without the salt. Salting per install keeps every within-account join the analytics actually use and gives up only cross-machine joins on the same repository, which nothing computes. + + Returns "" when there is no salt, so record() omits the property. An + unsalted digest over this input space is close to plaintext, and emitting one + under a name that implies it is hashed is worse than sending nothing. """ if not value: return "" - return hashlib.sha256(f"{_install_salt()}:{value}".encode("utf-8")).hexdigest()[:length] + salt = _install_salt() + if not salt: + return "" + return hashlib.sha256(f"{salt}:{value}".encode("utf-8")).hexdigest()[:length] def _safe_value(value: Any) -> Any: @@ -252,10 +272,17 @@ def record( os=sys.platform, python_version=platform.python_version(), ) + # Assigned only when the digest is real. _scoped_digest returns "" when + # the salt could not be persisted, and an empty property is worse than an + # absent one: it survives the None filter below and reads as a value. if repo is not None: - properties["repo_hash"] = _scoped_digest(getattr(repo, "identity", "")) + repo_hash = _scoped_digest(getattr(repo, "identity", "")) + if repo_hash: + properties["repo_hash"] = repo_hash if session_id: - properties["session_hash"] = _scoped_digest(session_id) + session_hash = _scoped_digest(session_id) + if session_hash: + properties["session_hash"] = session_hash line = json.dumps( { "event": f"{EVENT_PREFIX}.{event}", From d8c99fb405d59adc28225ce7c603d0b13fe29533 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Wed, 16 Sep 2026 20:35:13 +0530 Subject: [PATCH 18/30] fix(plugins): check the lease before judging a claim exhausted Review finding from @kartik-mem0 on this PR, and the most serious one: it loses events, which is what this PR exists to prevent. _claim_parked judged exhaustion before liveness. Claiming a parked file bumps its attempt count and refreshes its mtime, so the moment a sender takes the final attempt the file looks exhausted to every other sender while its owner is actively draining it. The second sender unlinked it, and everything in that batch was gone. The liveness check now runs first, so a batch under a live lease is skipped whatever its attempt count. The cleanup is deferred, not cancelled: once the lease lapses, the same exhausted file is reaped on a later run. Two tests. The first walks a batch to the final attempt and asserts a second sender neither takes it nor deletes it, and that the events are still in it. The second asserts an abandoned exhausted batch is still discarded once its lease lapses, which is the over-correction to guard against. Confirmed the first fails against the previous ordering. 288 passed, 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/telemetry.py | 11 +++- .../tests/test_spool_delivery.py | 61 +++++++++++++++++++ .../antigravity-plugin/core/telemetry.py | 11 +++- .../claude-code-plugin/core/telemetry.py | 11 +++- integrations/codex-plugin/core/telemetry.py | 11 +++- integrations/cursor-plugin/core/telemetry.py | 11 +++- integrations/kimi-plugin/core/telemetry.py | 11 +++- .../mem0-agent-plugin/core/telemetry.py | 11 +++- 8 files changed, 117 insertions(+), 21 deletions(-) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 792a7f2eb..48d6660aa 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -461,6 +461,14 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue + if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. This check has to come + # first. Claiming a file bumps its attempt count and refreshes its + # mtime, so a sender that has just taken the final attempt looks + # exhausted to everyone else while it is actively draining. Judging + # exhaustion before liveness let a second sender unlink a batch out + # from under its owner, losing every event in it. + continue # Attempts, not age. Every re-claim touches the mtime and every release # backdates it by a fixed amount, so age is pinned near the stale # threshold and never reaches the expiry. Age stays only as a backstop @@ -471,9 +479,6 @@ def _claim_parked(directory: Path) -> Path | None: except OSError: pass continue - if age < CLAIM_STALE_SECONDS: - # Someone else holds a live lease on it. - continue claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) diff --git a/integrations/agent-plugin-core/tests/test_spool_delivery.py b/integrations/agent-plugin-core/tests/test_spool_delivery.py index a51027904..a7646cc31 100644 --- a/integrations/agent-plugin-core/tests/test_spool_delivery.py +++ b/integrations/agent-plugin-core/tests/test_spool_delivery.py @@ -104,6 +104,67 @@ def test_a_fresh_claim_is_not_immediately_stealable(telemetry): assert telemetry._claim_parked(first.parent) is None +def test_a_live_final_attempt_is_not_deleted_by_another_sender(telemetry): + """Review finding: exhaustion was judged before liveness, so owners lost batches. + + Claiming a parked file bumps its attempt count and refreshes its mtime. Once + the count reaches the budget, the owner draining it looked exhausted to every + other sender, which unlinked the file out from under it. Everything in that + batch was gone, which is precisely the loss this PR exists to stop. + """ + telemetry.record("search", reason="owned-by-the-first-sender") + spool = telemetry._spool_path() + stale = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(spool, (stale, stale)) + + claim = telemetry._claim_spool() + assert claim is not None + + # Walk it to the final attempt, ageing it each round so it can be re-claimed. + # _claim_spool hands back a0 and _release_claim keeps the name, so it takes + # one full round per attempt to reach the budget. + for _ in range(telemetry.MAX_CLAIM_ATTEMPTS): + # Carry the marker through each rewrite so the final assertion proves the + # events survived, not merely that some file with the right name did. + telemetry._release_claim(claim, [{"event": "code.search", "uuid": "owned-by-the-first-sender"}]) + parked = sorted(claim.parent.glob("telemetry-*.sending")) + assert parked, "the batch was dropped while still inside its budget" + os.utime(parked[0], (stale, stale)) + claim = telemetry._claim_parked(claim.parent) + assert claim is not None + + assert telemetry._claim_attempt(claim) >= telemetry.MAX_CLAIM_ATTEMPTS + assert claim.exists() + + # The owner is draining it right now: fresh mtime, live lease. + second_sender = telemetry._claim_parked(claim.parent) + + assert second_sender is None, "a second sender took a batch under a live lease" + assert claim.exists(), "a second sender deleted a batch its owner was draining" + assert "owned-by-the-first-sender" in claim.read_text(encoding="utf-8") + + +def test_an_exhausted_batch_is_still_discarded_once_its_lease_lapses(telemetry): + """The liveness check must defer the cleanup, not cancel it. + + Guards the obvious over-correction: skipping live claims is only safe if an + abandoned one at the same attempt count is still reaped on a later run. + """ + telemetry.record("search") + spool = telemetry._spool_path() + stale = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(spool, (stale, stale)) + + claim = telemetry._claim_spool() + assert claim is not None + exhausted = claim.parent / telemetry._claim_name(telemetry.MAX_CLAIM_ATTEMPTS) + claim.replace(exhausted) + os.utime(exhausted, (stale, stale)) + + assert telemetry._claim_parked(exhausted.parent) is None + assert not exhausted.exists(), "an abandoned exhausted batch was left behind forever" + + def test_a_parked_batch_is_drained_behind_the_live_spool(telemetry): """Defect 6: parked claims were only reachable when no spool existed. diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 792a7f2eb..48d6660aa 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -461,6 +461,14 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue + if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. This check has to come + # first. Claiming a file bumps its attempt count and refreshes its + # mtime, so a sender that has just taken the final attempt looks + # exhausted to everyone else while it is actively draining. Judging + # exhaustion before liveness let a second sender unlink a batch out + # from under its owner, losing every event in it. + continue # Attempts, not age. Every re-claim touches the mtime and every release # backdates it by a fixed amount, so age is pinned near the stale # threshold and never reaches the expiry. Age stays only as a backstop @@ -471,9 +479,6 @@ def _claim_parked(directory: Path) -> Path | None: except OSError: pass continue - if age < CLAIM_STALE_SECONDS: - # Someone else holds a live lease on it. - continue claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 792a7f2eb..48d6660aa 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -461,6 +461,14 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue + if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. This check has to come + # first. Claiming a file bumps its attempt count and refreshes its + # mtime, so a sender that has just taken the final attempt looks + # exhausted to everyone else while it is actively draining. Judging + # exhaustion before liveness let a second sender unlink a batch out + # from under its owner, losing every event in it. + continue # Attempts, not age. Every re-claim touches the mtime and every release # backdates it by a fixed amount, so age is pinned near the stale # threshold and never reaches the expiry. Age stays only as a backstop @@ -471,9 +479,6 @@ def _claim_parked(directory: Path) -> Path | None: except OSError: pass continue - if age < CLAIM_STALE_SECONDS: - # Someone else holds a live lease on it. - continue claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 792a7f2eb..48d6660aa 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -461,6 +461,14 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue + if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. This check has to come + # first. Claiming a file bumps its attempt count and refreshes its + # mtime, so a sender that has just taken the final attempt looks + # exhausted to everyone else while it is actively draining. Judging + # exhaustion before liveness let a second sender unlink a batch out + # from under its owner, losing every event in it. + continue # Attempts, not age. Every re-claim touches the mtime and every release # backdates it by a fixed amount, so age is pinned near the stale # threshold and never reaches the expiry. Age stays only as a backstop @@ -471,9 +479,6 @@ def _claim_parked(directory: Path) -> Path | None: except OSError: pass continue - if age < CLAIM_STALE_SECONDS: - # Someone else holds a live lease on it. - continue claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 792a7f2eb..48d6660aa 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -461,6 +461,14 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue + if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. This check has to come + # first. Claiming a file bumps its attempt count and refreshes its + # mtime, so a sender that has just taken the final attempt looks + # exhausted to everyone else while it is actively draining. Judging + # exhaustion before liveness let a second sender unlink a batch out + # from under its owner, losing every event in it. + continue # Attempts, not age. Every re-claim touches the mtime and every release # backdates it by a fixed amount, so age is pinned near the stale # threshold and never reaches the expiry. Age stays only as a backstop @@ -471,9 +479,6 @@ def _claim_parked(directory: Path) -> Path | None: except OSError: pass continue - if age < CLAIM_STALE_SECONDS: - # Someone else holds a live lease on it. - continue claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 792a7f2eb..48d6660aa 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -461,6 +461,14 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue + if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. This check has to come + # first. Claiming a file bumps its attempt count and refreshes its + # mtime, so a sender that has just taken the final attempt looks + # exhausted to everyone else while it is actively draining. Judging + # exhaustion before liveness let a second sender unlink a batch out + # from under its owner, losing every event in it. + continue # Attempts, not age. Every re-claim touches the mtime and every release # backdates it by a fixed amount, so age is pinned near the stale # threshold and never reaches the expiry. Age stays only as a backstop @@ -471,9 +479,6 @@ def _claim_parked(directory: Path) -> Path | None: except OSError: pass continue - if age < CLAIM_STALE_SECONDS: - # Someone else holds a live lease on it. - continue claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 792a7f2eb..48d6660aa 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -461,6 +461,14 @@ def _claim_parked(directory: Path) -> Path | None: age = now - orphan.stat().st_mtime except OSError: continue + if age < CLAIM_STALE_SECONDS: + # Someone else holds a live lease on it. This check has to come + # first. Claiming a file bumps its attempt count and refreshes its + # mtime, so a sender that has just taken the final attempt looks + # exhausted to everyone else while it is actively draining. Judging + # exhaustion before liveness let a second sender unlink a batch out + # from under its owner, losing every event in it. + continue # Attempts, not age. Every re-claim touches the mtime and every release # backdates it by a fixed amount, so age is pinned near the stale # threshold and never reaches the expiry. Age stays only as a backstop @@ -471,9 +479,6 @@ def _claim_parked(directory: Path) -> Path | None: except OSError: pass continue - if age < CLAIM_STALE_SECONDS: - # Someone else holds a live lease on it. - continue claim = orphan.parent / _claim_name(_claim_attempt(orphan) + 1) try: orphan.replace(claim) From 6d89b3b33eb71dffc10867414ee98d29116e5bb0 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Wed, 16 Sep 2026 20:36:23 +0530 Subject: [PATCH 19/30] fix(plugins): rotate the anonymous id when the account goes, and verify legacy rows Three review findings from @kartik-mem0 on this PR. Anonymous id reuse, reported twice and one defect. The id is offered to PostHog as $anon_distinct_id on first sign-in and that merge is permanent, so keeping it after a logout or a key change puts every later anonymous event on the account that just left. It is now rotated on both routes, and 'aliased' is cleared with it so the fresh id can be merged into whatever account comes next. Rotation is deliberately not triggered by a plain lookup failure with no cached email: there is no previous account to leak to, and churning ids there would fragment the person for anyone offline on first run. Legacy rows are verified instead of adopted. A row written before fingerprints existed carries an email and no fingerprint; adopting the current key bound that key to the previous account's email permanently, and every run after agreed with itself. It now resolves once and takes the answer. If the lookup fails it keeps the cached email and retries next flush rather than dropping a real attribution, which is safe because the network that failed /v1/ping/ is about to fail the PostHog POST too. My original comment justifying the shortcut claimed the check would cost a request on every flush forever; that was wrong, the fingerprint is stored after one success. A failed upgrade claim is released. The sentinel was created before the marker rewrite and left behind if the rewrite failed, so claim_version_change returned early on every later run and that version's upgrade was never recorded again. Five tests, covering both rotation routes, legacy verification, the firewalled legacy case, and retrying a failed upgrade claim. 300 passed, 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/telemetry.py | 60 ++++++++-- .../antigravity-plugin/core/telemetry.py | 60 ++++++++-- .../claude-code-plugin/core/telemetry.py | 60 ++++++++-- .../tests/test_telemetry.py | 103 ++++++++++++++++++ integrations/codex-plugin/core/telemetry.py | 60 ++++++++-- integrations/cursor-plugin/core/telemetry.py | 60 ++++++++-- integrations/kimi-plugin/core/telemetry.py | 60 ++++++++-- .../mem0-agent-plugin/core/telemetry.py | 60 ++++++++-- 8 files changed, 467 insertions(+), 56 deletions(-) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 371a9b252..274174a9e 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -272,6 +272,25 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _rotate_anonymous_id(identity: dict[str, str]) -> str: + """Mint a fresh anonymous id because the account context is gone. + + The previous id may already have been merged into a person profile by an + $identify, and that merge is permanent. Reusing it after a logout or a key + change attributes everything that follows to the account that just went + away, which is the same misattribution the key fingerprint exists to stop, + only arriving through the anonymous path instead. + + `aliased` is cleared with it: the new id has never been merged, so it is + eligible to be aliased into whatever account comes next. + """ + created = f"code-anon-{uuid.uuid4().hex}" + identity["anonymous_id"] = created + identity.pop("aliased", None) + _write_identity(identity) + return created + + def _install_state_path() -> Path: return memory_core.data_dir() / "install-state.json" @@ -400,11 +419,19 @@ def claim_version_change() -> str | None: state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() + temporary = path.with_suffix(f".{os.getpid()}.tmp") try: - temporary = path.with_suffix(f".{os.getpid()}.tmp") temporary.write_text(json.dumps(state), encoding="utf-8") temporary.replace(path) except OSError: + # Release the claim. The marker still records the old version, so + # without this the sentinel makes claim_version_change return early on + # every later run and this version's upgrade is never recorded again. + for leftover in (sentinel, temporary): + try: + leftover.unlink() + except OSError: + pass return None return previous @@ -727,26 +754,43 @@ def resolve_distinct_id() -> tuple[str, str]: if recorded == fingerprint: return email, "" if not recorded: - # Rows written before fingerprints existed. Adopt the current key - # rather than re-resolving: otherwise every existing user pays an - # uncached /v1/ping/ on every flush, forever, and a firewalled one - # pays the full timeout each time. + # Rows written before fingerprints existed. Verify rather than + # adopt: a key changed before the upgrade would otherwise bind the + # new key to the previous account's email, permanently, and the + # fingerprint would then agree with itself forever after. + verified = _resolve_email(key) + if not verified: + # Offline, firewalled, or the API is down. Keep the previous + # behaviour and retry on the next flush rather than dropping a + # real account attribution. Safe because the same network that + # failed /v1/ping/ is about to fail the PostHog POST, so nothing + # is delivered under the unverified identity in the meantime. + return email, "" + identity["email"] = verified identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, "" + return verified, "" if not key: # No key to verify the account with; do not keep attributing to it. if email: identity.pop("email", None) identity.pop("key_fingerprint", None) - _write_identity(identity) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" resolved = _resolve_email(key) if not resolved: # The key changed and will not resolve (revoked, offline, API down). - # Do not keep attributing to the previous account. + # Reaching here with an email means the recorded fingerprint disagreed, + # so the key really did change. Drop the account and rotate: the stored + # anonymous id may already be merged into that account's person, and + # reusing it would keep the events on the profile we are trying to + # leave. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" # Alias only when going anonymous -> email for the first time. Once an anon diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 371a9b252..274174a9e 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -272,6 +272,25 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _rotate_anonymous_id(identity: dict[str, str]) -> str: + """Mint a fresh anonymous id because the account context is gone. + + The previous id may already have been merged into a person profile by an + $identify, and that merge is permanent. Reusing it after a logout or a key + change attributes everything that follows to the account that just went + away, which is the same misattribution the key fingerprint exists to stop, + only arriving through the anonymous path instead. + + `aliased` is cleared with it: the new id has never been merged, so it is + eligible to be aliased into whatever account comes next. + """ + created = f"code-anon-{uuid.uuid4().hex}" + identity["anonymous_id"] = created + identity.pop("aliased", None) + _write_identity(identity) + return created + + def _install_state_path() -> Path: return memory_core.data_dir() / "install-state.json" @@ -400,11 +419,19 @@ def claim_version_change() -> str | None: state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() + temporary = path.with_suffix(f".{os.getpid()}.tmp") try: - temporary = path.with_suffix(f".{os.getpid()}.tmp") temporary.write_text(json.dumps(state), encoding="utf-8") temporary.replace(path) except OSError: + # Release the claim. The marker still records the old version, so + # without this the sentinel makes claim_version_change return early on + # every later run and this version's upgrade is never recorded again. + for leftover in (sentinel, temporary): + try: + leftover.unlink() + except OSError: + pass return None return previous @@ -727,26 +754,43 @@ def resolve_distinct_id() -> tuple[str, str]: if recorded == fingerprint: return email, "" if not recorded: - # Rows written before fingerprints existed. Adopt the current key - # rather than re-resolving: otherwise every existing user pays an - # uncached /v1/ping/ on every flush, forever, and a firewalled one - # pays the full timeout each time. + # Rows written before fingerprints existed. Verify rather than + # adopt: a key changed before the upgrade would otherwise bind the + # new key to the previous account's email, permanently, and the + # fingerprint would then agree with itself forever after. + verified = _resolve_email(key) + if not verified: + # Offline, firewalled, or the API is down. Keep the previous + # behaviour and retry on the next flush rather than dropping a + # real account attribution. Safe because the same network that + # failed /v1/ping/ is about to fail the PostHog POST, so nothing + # is delivered under the unverified identity in the meantime. + return email, "" + identity["email"] = verified identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, "" + return verified, "" if not key: # No key to verify the account with; do not keep attributing to it. if email: identity.pop("email", None) identity.pop("key_fingerprint", None) - _write_identity(identity) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" resolved = _resolve_email(key) if not resolved: # The key changed and will not resolve (revoked, offline, API down). - # Do not keep attributing to the previous account. + # Reaching here with an email means the recorded fingerprint disagreed, + # so the key really did change. Drop the account and rotate: the stored + # anonymous id may already be merged into that account's person, and + # reusing it would keep the events on the profile we are trying to + # leave. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" # Alias only when going anonymous -> email for the first time. Once an anon diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 371a9b252..274174a9e 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -272,6 +272,25 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _rotate_anonymous_id(identity: dict[str, str]) -> str: + """Mint a fresh anonymous id because the account context is gone. + + The previous id may already have been merged into a person profile by an + $identify, and that merge is permanent. Reusing it after a logout or a key + change attributes everything that follows to the account that just went + away, which is the same misattribution the key fingerprint exists to stop, + only arriving through the anonymous path instead. + + `aliased` is cleared with it: the new id has never been merged, so it is + eligible to be aliased into whatever account comes next. + """ + created = f"code-anon-{uuid.uuid4().hex}" + identity["anonymous_id"] = created + identity.pop("aliased", None) + _write_identity(identity) + return created + + def _install_state_path() -> Path: return memory_core.data_dir() / "install-state.json" @@ -400,11 +419,19 @@ def claim_version_change() -> str | None: state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() + temporary = path.with_suffix(f".{os.getpid()}.tmp") try: - temporary = path.with_suffix(f".{os.getpid()}.tmp") temporary.write_text(json.dumps(state), encoding="utf-8") temporary.replace(path) except OSError: + # Release the claim. The marker still records the old version, so + # without this the sentinel makes claim_version_change return early on + # every later run and this version's upgrade is never recorded again. + for leftover in (sentinel, temporary): + try: + leftover.unlink() + except OSError: + pass return None return previous @@ -727,26 +754,43 @@ def resolve_distinct_id() -> tuple[str, str]: if recorded == fingerprint: return email, "" if not recorded: - # Rows written before fingerprints existed. Adopt the current key - # rather than re-resolving: otherwise every existing user pays an - # uncached /v1/ping/ on every flush, forever, and a firewalled one - # pays the full timeout each time. + # Rows written before fingerprints existed. Verify rather than + # adopt: a key changed before the upgrade would otherwise bind the + # new key to the previous account's email, permanently, and the + # fingerprint would then agree with itself forever after. + verified = _resolve_email(key) + if not verified: + # Offline, firewalled, or the API is down. Keep the previous + # behaviour and retry on the next flush rather than dropping a + # real account attribution. Safe because the same network that + # failed /v1/ping/ is about to fail the PostHog POST, so nothing + # is delivered under the unverified identity in the meantime. + return email, "" + identity["email"] = verified identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, "" + return verified, "" if not key: # No key to verify the account with; do not keep attributing to it. if email: identity.pop("email", None) identity.pop("key_fingerprint", None) - _write_identity(identity) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" resolved = _resolve_email(key) if not resolved: # The key changed and will not resolve (revoked, offline, API down). - # Do not keep attributing to the previous account. + # Reaching here with an email means the recorded fingerprint disagreed, + # so the key really did change. Drop the account and rotate: the stored + # anonymous id may already be merged into that account's person, and + # reusing it would keep the events on the profile we are trying to + # leave. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" # Alias only when going anonymous -> email for the first time. Once an anon diff --git a/integrations/claude-code-plugin/tests/test_telemetry.py b/integrations/claude-code-plugin/tests/test_telemetry.py index 363bf2368..8d83e4a7b 100644 --- a/integrations/claude-code-plugin/tests/test_telemetry.py +++ b/integrations/claude-code-plugin/tests/test_telemetry.py @@ -265,6 +265,109 @@ def test_an_unresolvable_key_falls_back_to_the_anonymous_id(isolated_env, monkey assert telemetry.resolve_distinct_id()[0].startswith("code-anon-") +def test_logging_out_does_not_leave_events_on_the_previous_account(isolated_env, monkeypatch): + """Review finding: clearing the email kept an id already merged into a person. + + The anonymous id is offered to PostHog as $anon_distinct_id on first sign-in, + and that merge is permanent. Keeping it after the key goes away means every + later anonymous event lands on the account that just left. + """ + # Run anonymously first, which is the only way an id exists to be merged. + merged = telemetry.anonymous_id() + + monkeypatch.setenv("MEM0_API_KEY", "key-for-account-a") + with patch.object(telemetry, "_resolve_email", lambda key: "a@example.com"): + identified, alias = telemetry.resolve_distinct_id() + assert identified == "a@example.com" + assert alias == merged, "the anonymous id was merged into this account" + + monkeypatch.delenv("MEM0_API_KEY", raising=False) + after_logout, logout_alias = telemetry.resolve_distinct_id() + + assert after_logout.startswith("code-anon-") + assert after_logout != merged, "reused an id already merged into the previous account" + assert logout_alias == "" + assert "aliased" not in telemetry._read_identity(), "rotated id must be aliasable again" + + +def test_a_changed_key_that_will_not_resolve_rotates_the_anonymous_id(isolated_env, monkeypatch): + """Same leak by the other route: fingerprint disagrees and the lookup fails.""" + merged = telemetry.anonymous_id() + monkeypatch.setenv("MEM0_API_KEY", "key-for-account-a") + with patch.object(telemetry, "_resolve_email", lambda key: "a@example.com"): + telemetry.resolve_distinct_id() + + monkeypatch.setenv("MEM0_API_KEY", "key-for-account-b") + with patch.object(telemetry, "_resolve_email", lambda key: ""): + after, alias = telemetry.resolve_distinct_id() + + assert after.startswith("code-anon-") + assert after != merged + assert alias == "" + assert "email" not in telemetry._read_identity() + + +def test_a_legacy_cached_email_is_verified_before_the_key_is_bound(isolated_env, monkeypatch): + """Review finding: a key changed before upgrading bound the wrong account. + + Rows written before fingerprints existed carry an email and no fingerprint. + Adopting the current key without checking pinned that key to the previous + account's email, and every run after that agreed with itself. + """ + telemetry._write_identity({"email": "old@example.com", "anonymous_id": "code-anon-seed"}) + monkeypatch.setenv("MEM0_API_KEY", "key-for-account-b") + + with patch.object(telemetry, "_resolve_email", lambda key: "new@example.com"): + resolved, alias = telemetry.resolve_distinct_id() + + assert resolved == "new@example.com" + assert alias == "", "email to email must never alias; it merges two real people" + stored = telemetry._read_identity() + assert stored["email"] == "new@example.com" + assert stored["key_fingerprint"] == telemetry._digest("key-for-account-b") + + +def test_a_legacy_row_keeps_working_when_the_account_cannot_be_checked(isolated_env, monkeypatch): + """Firewalled users must not lose attribution, and must not bind unverified. + + The same network that fails /v1/ping/ fails the PostHog POST, so nothing is + delivered under the unverified identity while this holds. + """ + telemetry._write_identity({"email": "old@example.com"}) + monkeypatch.setenv("MEM0_API_KEY", "key-for-account-b") + + with patch.object(telemetry, "_resolve_email", lambda key: ""): + resolved, _ = telemetry.resolve_distinct_id() + + assert resolved == "old@example.com" + assert "key_fingerprint" not in telemetry._read_identity(), "bound an unverified key" + + +def test_a_failed_upgrade_claim_can_be_retried(isolated_env, monkeypatch): + """Review finding: a failed rewrite left the sentinel and suppressed forever. + + claim_version_change returns early on FileExistsError, and the marker still + holds the old version, so the upgrade for that version was never recorded + again on that machine. + """ + telemetry.claim_install() + state_path = memory_core.data_dir() / "install-state.json" + state = json.loads(state_path.read_text()) + state["plugin_version"] = "0.0.1-old" + state_path.write_text(json.dumps(state), encoding="utf-8") + + real_replace = Path.replace + + def failing_replace(self, target): + raise OSError("disk full") + + monkeypatch.setattr(Path, "replace", failing_replace) + assert telemetry.claim_version_change() is None + + monkeypatch.setattr(Path, "replace", real_replace) + assert telemetry.claim_version_change() == "0.0.1-old", "sentinel suppressed the retry" + + def test_first_run_is_not_flipped_by_writing_the_identity_file(isolated_env): """The identity file is written by a successful flush, not by recording. diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 371a9b252..274174a9e 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -272,6 +272,25 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _rotate_anonymous_id(identity: dict[str, str]) -> str: + """Mint a fresh anonymous id because the account context is gone. + + The previous id may already have been merged into a person profile by an + $identify, and that merge is permanent. Reusing it after a logout or a key + change attributes everything that follows to the account that just went + away, which is the same misattribution the key fingerprint exists to stop, + only arriving through the anonymous path instead. + + `aliased` is cleared with it: the new id has never been merged, so it is + eligible to be aliased into whatever account comes next. + """ + created = f"code-anon-{uuid.uuid4().hex}" + identity["anonymous_id"] = created + identity.pop("aliased", None) + _write_identity(identity) + return created + + def _install_state_path() -> Path: return memory_core.data_dir() / "install-state.json" @@ -400,11 +419,19 @@ def claim_version_change() -> str | None: state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() + temporary = path.with_suffix(f".{os.getpid()}.tmp") try: - temporary = path.with_suffix(f".{os.getpid()}.tmp") temporary.write_text(json.dumps(state), encoding="utf-8") temporary.replace(path) except OSError: + # Release the claim. The marker still records the old version, so + # without this the sentinel makes claim_version_change return early on + # every later run and this version's upgrade is never recorded again. + for leftover in (sentinel, temporary): + try: + leftover.unlink() + except OSError: + pass return None return previous @@ -727,26 +754,43 @@ def resolve_distinct_id() -> tuple[str, str]: if recorded == fingerprint: return email, "" if not recorded: - # Rows written before fingerprints existed. Adopt the current key - # rather than re-resolving: otherwise every existing user pays an - # uncached /v1/ping/ on every flush, forever, and a firewalled one - # pays the full timeout each time. + # Rows written before fingerprints existed. Verify rather than + # adopt: a key changed before the upgrade would otherwise bind the + # new key to the previous account's email, permanently, and the + # fingerprint would then agree with itself forever after. + verified = _resolve_email(key) + if not verified: + # Offline, firewalled, or the API is down. Keep the previous + # behaviour and retry on the next flush rather than dropping a + # real account attribution. Safe because the same network that + # failed /v1/ping/ is about to fail the PostHog POST, so nothing + # is delivered under the unverified identity in the meantime. + return email, "" + identity["email"] = verified identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, "" + return verified, "" if not key: # No key to verify the account with; do not keep attributing to it. if email: identity.pop("email", None) identity.pop("key_fingerprint", None) - _write_identity(identity) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" resolved = _resolve_email(key) if not resolved: # The key changed and will not resolve (revoked, offline, API down). - # Do not keep attributing to the previous account. + # Reaching here with an email means the recorded fingerprint disagreed, + # so the key really did change. Drop the account and rotate: the stored + # anonymous id may already be merged into that account's person, and + # reusing it would keep the events on the profile we are trying to + # leave. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" # Alias only when going anonymous -> email for the first time. Once an anon diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 371a9b252..274174a9e 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -272,6 +272,25 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _rotate_anonymous_id(identity: dict[str, str]) -> str: + """Mint a fresh anonymous id because the account context is gone. + + The previous id may already have been merged into a person profile by an + $identify, and that merge is permanent. Reusing it after a logout or a key + change attributes everything that follows to the account that just went + away, which is the same misattribution the key fingerprint exists to stop, + only arriving through the anonymous path instead. + + `aliased` is cleared with it: the new id has never been merged, so it is + eligible to be aliased into whatever account comes next. + """ + created = f"code-anon-{uuid.uuid4().hex}" + identity["anonymous_id"] = created + identity.pop("aliased", None) + _write_identity(identity) + return created + + def _install_state_path() -> Path: return memory_core.data_dir() / "install-state.json" @@ -400,11 +419,19 @@ def claim_version_change() -> str | None: state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() + temporary = path.with_suffix(f".{os.getpid()}.tmp") try: - temporary = path.with_suffix(f".{os.getpid()}.tmp") temporary.write_text(json.dumps(state), encoding="utf-8") temporary.replace(path) except OSError: + # Release the claim. The marker still records the old version, so + # without this the sentinel makes claim_version_change return early on + # every later run and this version's upgrade is never recorded again. + for leftover in (sentinel, temporary): + try: + leftover.unlink() + except OSError: + pass return None return previous @@ -727,26 +754,43 @@ def resolve_distinct_id() -> tuple[str, str]: if recorded == fingerprint: return email, "" if not recorded: - # Rows written before fingerprints existed. Adopt the current key - # rather than re-resolving: otherwise every existing user pays an - # uncached /v1/ping/ on every flush, forever, and a firewalled one - # pays the full timeout each time. + # Rows written before fingerprints existed. Verify rather than + # adopt: a key changed before the upgrade would otherwise bind the + # new key to the previous account's email, permanently, and the + # fingerprint would then agree with itself forever after. + verified = _resolve_email(key) + if not verified: + # Offline, firewalled, or the API is down. Keep the previous + # behaviour and retry on the next flush rather than dropping a + # real account attribution. Safe because the same network that + # failed /v1/ping/ is about to fail the PostHog POST, so nothing + # is delivered under the unverified identity in the meantime. + return email, "" + identity["email"] = verified identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, "" + return verified, "" if not key: # No key to verify the account with; do not keep attributing to it. if email: identity.pop("email", None) identity.pop("key_fingerprint", None) - _write_identity(identity) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" resolved = _resolve_email(key) if not resolved: # The key changed and will not resolve (revoked, offline, API down). - # Do not keep attributing to the previous account. + # Reaching here with an email means the recorded fingerprint disagreed, + # so the key really did change. Drop the account and rotate: the stored + # anonymous id may already be merged into that account's person, and + # reusing it would keep the events on the profile we are trying to + # leave. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" # Alias only when going anonymous -> email for the first time. Once an anon diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 371a9b252..274174a9e 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -272,6 +272,25 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _rotate_anonymous_id(identity: dict[str, str]) -> str: + """Mint a fresh anonymous id because the account context is gone. + + The previous id may already have been merged into a person profile by an + $identify, and that merge is permanent. Reusing it after a logout or a key + change attributes everything that follows to the account that just went + away, which is the same misattribution the key fingerprint exists to stop, + only arriving through the anonymous path instead. + + `aliased` is cleared with it: the new id has never been merged, so it is + eligible to be aliased into whatever account comes next. + """ + created = f"code-anon-{uuid.uuid4().hex}" + identity["anonymous_id"] = created + identity.pop("aliased", None) + _write_identity(identity) + return created + + def _install_state_path() -> Path: return memory_core.data_dir() / "install-state.json" @@ -400,11 +419,19 @@ def claim_version_change() -> str | None: state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() + temporary = path.with_suffix(f".{os.getpid()}.tmp") try: - temporary = path.with_suffix(f".{os.getpid()}.tmp") temporary.write_text(json.dumps(state), encoding="utf-8") temporary.replace(path) except OSError: + # Release the claim. The marker still records the old version, so + # without this the sentinel makes claim_version_change return early on + # every later run and this version's upgrade is never recorded again. + for leftover in (sentinel, temporary): + try: + leftover.unlink() + except OSError: + pass return None return previous @@ -727,26 +754,43 @@ def resolve_distinct_id() -> tuple[str, str]: if recorded == fingerprint: return email, "" if not recorded: - # Rows written before fingerprints existed. Adopt the current key - # rather than re-resolving: otherwise every existing user pays an - # uncached /v1/ping/ on every flush, forever, and a firewalled one - # pays the full timeout each time. + # Rows written before fingerprints existed. Verify rather than + # adopt: a key changed before the upgrade would otherwise bind the + # new key to the previous account's email, permanently, and the + # fingerprint would then agree with itself forever after. + verified = _resolve_email(key) + if not verified: + # Offline, firewalled, or the API is down. Keep the previous + # behaviour and retry on the next flush rather than dropping a + # real account attribution. Safe because the same network that + # failed /v1/ping/ is about to fail the PostHog POST, so nothing + # is delivered under the unverified identity in the meantime. + return email, "" + identity["email"] = verified identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, "" + return verified, "" if not key: # No key to verify the account with; do not keep attributing to it. if email: identity.pop("email", None) identity.pop("key_fingerprint", None) - _write_identity(identity) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" resolved = _resolve_email(key) if not resolved: # The key changed and will not resolve (revoked, offline, API down). - # Do not keep attributing to the previous account. + # Reaching here with an email means the recorded fingerprint disagreed, + # so the key really did change. Drop the account and rotate: the stored + # anonymous id may already be merged into that account's person, and + # reusing it would keep the events on the profile we are trying to + # leave. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" # Alias only when going anonymous -> email for the first time. Once an anon diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 371a9b252..274174a9e 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -272,6 +272,25 @@ def anonymous_id(identity: dict[str, str] | None = None) -> str: return created +def _rotate_anonymous_id(identity: dict[str, str]) -> str: + """Mint a fresh anonymous id because the account context is gone. + + The previous id may already have been merged into a person profile by an + $identify, and that merge is permanent. Reusing it after a logout or a key + change attributes everything that follows to the account that just went + away, which is the same misattribution the key fingerprint exists to stop, + only arriving through the anonymous path instead. + + `aliased` is cleared with it: the new id has never been merged, so it is + eligible to be aliased into whatever account comes next. + """ + created = f"code-anon-{uuid.uuid4().hex}" + identity["anonymous_id"] = created + identity.pop("aliased", None) + _write_identity(identity) + return created + + def _install_state_path() -> Path: return memory_core.data_dir() / "install-state.json" @@ -400,11 +419,19 @@ def claim_version_change() -> str | None: state["plugin_version"] = memory_core.PLUGIN_VERSION state["upgraded_at"] = memory_core.utc_now() + temporary = path.with_suffix(f".{os.getpid()}.tmp") try: - temporary = path.with_suffix(f".{os.getpid()}.tmp") temporary.write_text(json.dumps(state), encoding="utf-8") temporary.replace(path) except OSError: + # Release the claim. The marker still records the old version, so + # without this the sentinel makes claim_version_change return early on + # every later run and this version's upgrade is never recorded again. + for leftover in (sentinel, temporary): + try: + leftover.unlink() + except OSError: + pass return None return previous @@ -727,26 +754,43 @@ def resolve_distinct_id() -> tuple[str, str]: if recorded == fingerprint: return email, "" if not recorded: - # Rows written before fingerprints existed. Adopt the current key - # rather than re-resolving: otherwise every existing user pays an - # uncached /v1/ping/ on every flush, forever, and a firewalled one - # pays the full timeout each time. + # Rows written before fingerprints existed. Verify rather than + # adopt: a key changed before the upgrade would otherwise bind the + # new key to the previous account's email, permanently, and the + # fingerprint would then agree with itself forever after. + verified = _resolve_email(key) + if not verified: + # Offline, firewalled, or the API is down. Keep the previous + # behaviour and retry on the next flush rather than dropping a + # real account attribution. Safe because the same network that + # failed /v1/ping/ is about to fail the PostHog POST, so nothing + # is delivered under the unverified identity in the meantime. + return email, "" + identity["email"] = verified identity["key_fingerprint"] = fingerprint _write_identity(identity) - return email, "" + return verified, "" if not key: # No key to verify the account with; do not keep attributing to it. if email: identity.pop("email", None) identity.pop("key_fingerprint", None) - _write_identity(identity) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" resolved = _resolve_email(key) if not resolved: # The key changed and will not resolve (revoked, offline, API down). - # Do not keep attributing to the previous account. + # Reaching here with an email means the recorded fingerprint disagreed, + # so the key really did change. Drop the account and rotate: the stored + # anonymous id may already be merged into that account's person, and + # reusing it would keep the events on the profile we are trying to + # leave. + if email: + identity.pop("email", None) + identity.pop("key_fingerprint", None) + return _rotate_anonymous_id(identity), "" return anonymous_id(identity), "" # Alias only when going anonymous -> email for the first time. Once an anon From 64a01ab31e9f49d6ac59abc50ba6a2c373ea2bdf Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Wed, 16 Sep 2026 20:37:57 +0530 Subject: [PATCH 20/30] fix(pi-agent): attribute the shared client, not two command call sites Review finding from @kartik-mem0 on this PR. Only the explicit slash commands set a source. Automatic recall at entry.ts:80, the capture path, the memory tools and deletion all go through the same client constructed at entry.ts:31 with no attribution, so everything except the commands still reached the platform as generic SDK traffic. That is most of the plugin's traffic. Identity is now stamped once on the shared client. Deliberately by mutating client.headers rather than through the SDK's MEM0_SOURCE environment support: this package pins mem0ai ^3.0.7, the installed build has no such support, and setting an environment variable it does not read would have looked like a fix and changed nothing. Every request method in the published client sends this.headers, so this covers all of them and keeps working when the SDK gains the env path. Set-once and append-only are preserved, so a wrapper that already named a surface keeps it and the client stack accumulates rather than being replaced. PLATFORM_SOURCE moves into the new module and commands.ts imports it; the body source stays on those two calls because that is what the backend reads when the header is absent. Five tests for the header contract, plus the existing suite: 94 pi-agent tests pass and the tsup DTS build is clean. Python side 307 passed, 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../pi-agent-plugin/src/attribution.test.ts | 53 +++++++++++++++++++ .../pi-agent-plugin/src/attribution.ts | 50 +++++++++++++++++ integrations/pi-agent-plugin/src/commands.ts | 8 +-- integrations/pi-agent-plugin/src/entry.ts | 6 +++ 4 files changed, 114 insertions(+), 3 deletions(-) create mode 100644 integrations/pi-agent-plugin/src/attribution.test.ts create mode 100644 integrations/pi-agent-plugin/src/attribution.ts diff --git a/integrations/pi-agent-plugin/src/attribution.test.ts b/integrations/pi-agent-plugin/src/attribution.test.ts new file mode 100644 index 000000000..79d938c62 --- /dev/null +++ b/integrations/pi-agent-plugin/src/attribution.test.ts @@ -0,0 +1,53 @@ +import { describe, expect, it } from "vitest"; +import { applySurfaceHeaders, PLATFORM_APPLICATION, PLATFORM_SOURCE } from "./attribution.ts"; + +function client(headers: Record = {}) { + return { headers: { Authorization: "Token k", ...headers } } as never; +} + +describe("applySurfaceHeaders", () => { + it("stamps the shared client so every path is attributed, not just commands", () => { + const mem0 = client(); + applySurfaceHeaders(mem0); + const headers = (mem0 as unknown as { headers: Record }).headers; + + expect(headers["X-Mem0-Source"]).toBe(PLATFORM_SOURCE); + expect(headers["X-Application"]).toBe(PLATFORM_APPLICATION); + expect(headers["X-Mem0-Client"]).toMatch(/^mem0-pi-agent\//); + expect(headers.Authorization).toBe("Token k"); + }); + + it("defers to a surface an outer wrapper already declared", () => { + const mem0 = client({ "X-Mem0-Source": "OPENCLAW", "X-Application": "vscode" }); + applySurfaceHeaders(mem0); + const headers = (mem0 as unknown as { headers: Record }).headers; + + expect(headers["X-Mem0-Source"]).toBe("OPENCLAW"); + expect(headers["X-Application"]).toBe("vscode"); + }); + + it("appends to the client stack rather than replacing it", () => { + const mem0 = client({ "X-Mem0-Client": "openclaw/2.1.0" }); + applySurfaceHeaders(mem0); + const headers = (mem0 as unknown as { headers: Record }).headers; + + expect(headers["X-Mem0-Client"]).toMatch(/^openclaw\/2\.1\.0, mem0-pi-agent\//); + }); + + it("treats a blank header as absent", () => { + const mem0 = client({ "X-Mem0-Source": " " }); + applySurfaceHeaders(mem0); + const headers = (mem0 as unknown as { headers: Record }).headers; + + expect(headers["X-Mem0-Source"]).toBe(PLATFORM_SOURCE); + }); + + it("bounds the stack so a long chain cannot grow the header without limit", () => { + const mem0 = client({ "X-Mem0-Client": "a/1, b/1, c/1, d/1, e/1" }); + applySurfaceHeaders(mem0); + const headers = (mem0 as unknown as { headers: Record }).headers; + + expect(headers["X-Mem0-Client"].split(",").length).toBeLessThanOrEqual(4); + expect(headers["X-Mem0-Client"].length).toBeLessThanOrEqual(200); + }); +}); diff --git a/integrations/pi-agent-plugin/src/attribution.ts b/integrations/pi-agent-plugin/src/attribution.ts new file mode 100644 index 000000000..7ab3ea6d6 --- /dev/null +++ b/integrations/pi-agent-plugin/src/attribution.ts @@ -0,0 +1,50 @@ +import type MemoryClient from "mem0ai"; +import * as fs from "node:fs"; + +/** Surface identity for this plugin, as the platform's EventSource knows it. */ +export const PLATFORM_SOURCE = "PI_AGENT"; + +/** Host app the plugin runs inside. Allowlisted server-side. */ +export const PLATFORM_APPLICATION = "pi"; + +const PLUGIN_VERSION = (() => { + try { + return JSON.parse( + fs.readFileSync(new URL("../package.json", import.meta.url), "utf-8"), + ).version as string; + } catch { + return "unknown"; + } +})(); + +const MAX_STACK_ENTRIES = 4; +const MAX_HEADER_CHARS = 200; + +/** + * Stamp surface identity onto the shared client, once, at construction. + * + * Tagging individual call sites was not enough: automatic recall, capture, the + * memory tools and deletion all go through this same client, so everything + * except the explicit slash commands reached the platform as generic SDK + * traffic. Every request method in the SDK sends `this.headers`, so setting + * them here covers all of them. + * + * X-Mem0-Source and X-Application are set-once, so a wrapper that already named + * a surface keeps it. X-Mem0-Client is append-only, so the platform sees the + * whole chain rather than only the last speaker. + */ +export function applySurfaceHeaders(client: MemoryClient): void { + const headers = client.headers as Record; + if (!headers["X-Mem0-Source"]?.trim()) headers["X-Mem0-Source"] = PLATFORM_SOURCE; + if (!headers["X-Application"]?.trim()) headers["X-Application"] = PLATFORM_APPLICATION; + + const existing = (headers["X-Mem0-Client"] ?? "") + .split(",") + .map((part) => part.trim()) + .filter(Boolean); + existing.push(`mem0-pi-agent/${PLUGIN_VERSION}`); + headers["X-Mem0-Client"] = existing + .slice(0, MAX_STACK_ENTRIES) + .join(", ") + .slice(0, MAX_HEADER_CHARS); +} diff --git a/integrations/pi-agent-plugin/src/commands.ts b/integrations/pi-agent-plugin/src/commands.ts index a733aea0a..e969478a1 100644 --- a/integrations/pi-agent-plugin/src/commands.ts +++ b/integrations/pi-agent-plugin/src/commands.ts @@ -6,10 +6,12 @@ import { DEFAULT_CUSTOM_CATEGORIES } from "./types.ts"; import { resolveSearchFilters, resolveAddParams } from "./memory/scoping.ts"; import { formatMemoryList, formatMemoryCompact, groupByCategory } from "./memory/formatting.ts"; import { captureCommandEvent } from "./telemetry.ts"; +import { PLATFORM_SOURCE } from "./attribution.ts"; -// Surface attribution on the wire. Previously a PostHog property only, so -// the platform saw these calls as generic SDK traffic. -const PLATFORM_SOURCE = "PI_AGENT"; +// Wire identity is set once on the shared client in entry.ts, which covers +// every path including recall, capture, tools and deletion. It stays in the +// body of the two calls below as well: body `source` is what the backend reads +// when the header is absent. const SEARCH_TOP_K = 10; diff --git a/integrations/pi-agent-plugin/src/entry.ts b/integrations/pi-agent-plugin/src/entry.ts index d49d78ad0..256c05aa4 100644 --- a/integrations/pi-agent-plugin/src/entry.ts +++ b/integrations/pi-agent-plugin/src/entry.ts @@ -10,6 +10,7 @@ import { captureEvent } from "./telemetry.ts"; import * as os from "node:os"; import type { ScopeContext } from "./types.ts"; import { createMemoryLifecycle } from "../../agent-plugin-core/typescript/src/lifecycle.ts"; +import { applySurfaceHeaders } from "./attribution.ts"; export { buildRecallContext } from "../../agent-plugin-core/typescript/src/lifecycle.ts"; @@ -29,6 +30,11 @@ export default function mem0Extension(pi: ExtensionAPI): void { } const mem0 = new MemoryClient({ apiKey: config.apiKey }); + // Every path below shares this client: automatic recall, capture, the memory + // tools and deletion as well as the slash commands. Attribution belongs here + // rather than on individual calls, or everything except the commands reports + // as generic SDK traffic. + applySurfaceHeaders(mem0); const scopeCtx: ScopeContext = { userId: resolveUserId(config.userId), From 3fd4949040af66ddf17faedd960cefbc7c88d107 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Wed, 16 Sep 2026 21:08:43 +0530 Subject: [PATCH 21/30] fix(plugins): keep the salt working where hardlinks are not supported Self-review of the atomic-publish fix. Some network mounts and container volumes reject os.link, and the outer handler swallowed that into "no salt", which meant repo_hash and session_hash were dropped on every run for that whole cohort. The race being closed is narrow; losing the hashes for an entire filesystem is not a fair trade. Falls back to claiming the name with O_CREAT|O_EXCL and writing, which is what this did before. The empty-file window reopens there, but it is benign now: a reader landing in it gets "" and omits the hash for that process rather than caching a guessable path digest, which was the actual defect. 266 passed, 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/telemetry.py | 13 ++++++++++++ .../antigravity-plugin/core/telemetry.py | 13 ++++++++++++ .../claude-code-plugin/core/telemetry.py | 13 ++++++++++++ .../tests/test_telemetry.py | 20 +++++++++++++++++++ integrations/codex-plugin/core/telemetry.py | 13 ++++++++++++ integrations/cursor-plugin/core/telemetry.py | 13 ++++++++++++ integrations/kimi-plugin/core/telemetry.py | 13 ++++++++++++ .../mem0-agent-plugin/core/telemetry.py | 13 ++++++++++++ 8 files changed, 111 insertions(+) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 2cb1056e0..d86873d3d 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -147,6 +147,19 @@ def _install_salt() -> str: os.link(temporary, path) except FileExistsError: pass + except OSError: + # No hardlinks here (some network mounts, some container volumes). + # Claim the name directly instead. That reopens the empty-file + # window, but the window is now benign: a reader that lands in it + # gets "" and omits the hash for that process rather than caching a + # guessable one. Losing the hashes on every run of an entire + # filesystem is the worse failure. + try: + fallback = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(fallback, "w", encoding="utf-8") as stream: + stream.write(temporary.read_text(encoding="utf-8")) + except OSError: + pass except OSError: pass finally: diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 2cb1056e0..d86873d3d 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -147,6 +147,19 @@ def _install_salt() -> str: os.link(temporary, path) except FileExistsError: pass + except OSError: + # No hardlinks here (some network mounts, some container volumes). + # Claim the name directly instead. That reopens the empty-file + # window, but the window is now benign: a reader that lands in it + # gets "" and omits the hash for that process rather than caching a + # guessable one. Losing the hashes on every run of an entire + # filesystem is the worse failure. + try: + fallback = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(fallback, "w", encoding="utf-8") as stream: + stream.write(temporary.read_text(encoding="utf-8")) + except OSError: + pass except OSError: pass finally: diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 2cb1056e0..d86873d3d 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -147,6 +147,19 @@ def _install_salt() -> str: os.link(temporary, path) except FileExistsError: pass + except OSError: + # No hardlinks here (some network mounts, some container volumes). + # Claim the name directly instead. That reopens the empty-file + # window, but the window is now benign: a reader that lands in it + # gets "" and omits the hash for that process rather than caching a + # guessable one. Losing the hashes on every run of an entire + # filesystem is the worse failure. + try: + fallback = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(fallback, "w", encoding="utf-8") as stream: + stream.write(temporary.read_text(encoding="utf-8")) + except OSError: + pass except OSError: pass finally: diff --git a/integrations/claude-code-plugin/tests/test_telemetry.py b/integrations/claude-code-plugin/tests/test_telemetry.py index b816b629e..6029fa98a 100644 --- a/integrations/claude-code-plugin/tests/test_telemetry.py +++ b/integrations/claude-code-plugin/tests/test_telemetry.py @@ -352,6 +352,26 @@ def test_a_half_written_salt_is_never_visible_to_another_process(isolated_env, m assert salt_path.read_text(encoding="utf-8").strip() == salt +def test_a_filesystem_without_hardlinks_still_gets_a_salt(isolated_env, monkeypatch): + """Publishing by link must not become a silent loss of the hashes. + + Some network mounts and container volumes reject os.link. Returning "" + there would drop repo_hash and session_hash on every run for that whole + cohort, which is a bigger loss than the narrow race the link closes. + """ + telemetry._salt_cache = "" + monkeypatch.setattr( + telemetry.os, "link", lambda src, dst: (_ for _ in ()).throw(OSError(38, "not implemented")) + ) + + salt = telemetry._install_salt() + + assert len(salt) == 32, "no salt on a filesystem without hardlinks" + assert telemetry._salt_path().read_text(encoding="utf-8").strip() == salt + assert telemetry._scoped_digest("git@github.com:acme/x.git") != "" + assert not list(telemetry._salt_path().parent.glob("telemetry-salt.*.tmp")) + + def test_a_concurrent_writer_does_not_clobber_the_published_salt(isolated_env): """Second process to finish must adopt the first one's salt, not replace it. diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 2cb1056e0..d86873d3d 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -147,6 +147,19 @@ def _install_salt() -> str: os.link(temporary, path) except FileExistsError: pass + except OSError: + # No hardlinks here (some network mounts, some container volumes). + # Claim the name directly instead. That reopens the empty-file + # window, but the window is now benign: a reader that lands in it + # gets "" and omits the hash for that process rather than caching a + # guessable one. Losing the hashes on every run of an entire + # filesystem is the worse failure. + try: + fallback = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(fallback, "w", encoding="utf-8") as stream: + stream.write(temporary.read_text(encoding="utf-8")) + except OSError: + pass except OSError: pass finally: diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 2cb1056e0..d86873d3d 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -147,6 +147,19 @@ def _install_salt() -> str: os.link(temporary, path) except FileExistsError: pass + except OSError: + # No hardlinks here (some network mounts, some container volumes). + # Claim the name directly instead. That reopens the empty-file + # window, but the window is now benign: a reader that lands in it + # gets "" and omits the hash for that process rather than caching a + # guessable one. Losing the hashes on every run of an entire + # filesystem is the worse failure. + try: + fallback = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(fallback, "w", encoding="utf-8") as stream: + stream.write(temporary.read_text(encoding="utf-8")) + except OSError: + pass except OSError: pass finally: diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 2cb1056e0..d86873d3d 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -147,6 +147,19 @@ def _install_salt() -> str: os.link(temporary, path) except FileExistsError: pass + except OSError: + # No hardlinks here (some network mounts, some container volumes). + # Claim the name directly instead. That reopens the empty-file + # window, but the window is now benign: a reader that lands in it + # gets "" and omits the hash for that process rather than caching a + # guessable one. Losing the hashes on every run of an entire + # filesystem is the worse failure. + try: + fallback = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(fallback, "w", encoding="utf-8") as stream: + stream.write(temporary.read_text(encoding="utf-8")) + except OSError: + pass except OSError: pass finally: diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 2cb1056e0..d86873d3d 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -147,6 +147,19 @@ def _install_salt() -> str: os.link(temporary, path) except FileExistsError: pass + except OSError: + # No hardlinks here (some network mounts, some container volumes). + # Claim the name directly instead. That reopens the empty-file + # window, but the window is now benign: a reader that lands in it + # gets "" and omits the hash for that process rather than caching a + # guessable one. Losing the hashes on every run of an entire + # filesystem is the worse failure. + try: + fallback = os.open(path, os.O_CREAT | os.O_EXCL | os.O_WRONLY, 0o600) + with os.fdopen(fallback, "w", encoding="utf-8") as stream: + stream.write(temporary.read_text(encoding="utf-8")) + except OSError: + pass except OSError: pass finally: From 40287f6f04d969eb7ac540485e8b5cf630bcc7a6 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Wed, 16 Sep 2026 22:14:42 +0530 Subject: [PATCH 22/30] fix(plugins): a batch that could not be read is not a delivered batch Two review findings from @karthik-indla on this PR. _drain returned (0, True) on any read failure, so a claim nothing was posted from counted as fully delivered. flush() then carried on to the next claim as though this one had arrived, and the single signal that says the run went badly never fired. The two cases are now separated: undecodable content is still quarantined and reported delivered, because there is nothing left to send and the rest of the run should continue, while an OSError leaves the file exactly where it is and reports undelivered. Quarantining there would discard events over a transient filesystem error, and nothing ever re-globs .corrupt. Retries had no time backoff. _release_claim backdated straight to immediately-reclaimable, so two senders meeting one momentary failure could walk a batch from attempt 0 to the limit within seconds and discard it, when a retry a minute later would have delivered. Releases now carry a cooldown that grows with the attempts already spent, clamped so the mtime never lands in the future and reads as a live lease. Four tests: an unreadable batch is neither delivered nor quarantined, undecodable content still is quarantined so one torn file cannot block every later claim, and attempts cannot be burned without waiting. The expiry test now ages the file between flushes, which is the wall time a real retry waits. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/telemetry.py | 26 +++++- .../tests/test_spool_delivery.py | 91 ++++++++++++++++++- .../antigravity-plugin/core/telemetry.py | 26 +++++- .../claude-code-plugin/core/telemetry.py | 26 +++++- integrations/codex-plugin/core/telemetry.py | 26 +++++- integrations/cursor-plugin/core/telemetry.py | 26 +++++- integrations/kimi-plugin/core/telemetry.py | 26 +++++- .../mem0-agent-plugin/core/telemetry.py | 26 +++++- 8 files changed, 244 insertions(+), 29 deletions(-) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index a8f018f8e..a5107d430 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -105,6 +105,11 @@ MAX_CLAIM_ATTEMPTS = 3 # Parked claims drained per run, after the live spool. Bounded so a long backlog # cannot turn one flush into an unbounded send loop. MAX_PARKED_PER_RUN = 3 +# Added to the wait before a released claim becomes reclaimable, per attempt +# already spent. Releasing straight to "reclaimable now" let two senders burn the +# whole budget within seconds of one another on a single momentary failure, and +# discard a batch a retry a minute later would have delivered. +RETRY_COOLDOWN_SECONDS = 60 def is_enabled() -> bool: @@ -556,7 +561,11 @@ def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: if not _rewrite_claim(claim, remaining): return try: - released = time.time() - CLAIM_STALE_SECONDS - 1 + # Backdate past the stale threshold so the next flush can pick it up, + # minus a cooldown that grows with the attempts already spent. Clamped so + # the mtime never lands in the future, which would read as a live lease. + cooldown = min(_claim_attempt(claim) * RETRY_COOLDOWN_SECONDS, CLAIM_STALE_SECONDS) + released = time.time() - CLAIM_STALE_SECONDS - 1 + cooldown os.utime(claim, (released, released)) except OSError: pass @@ -642,11 +651,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except (OSError, ValueError): - # ValueError covers UnicodeDecodeError from a torn write. Quarantine - # rather than retry: flush() runs from a bare `finally:` in + except ValueError: + # UnicodeDecodeError from a torn write: the content is unrecoverable, so + # quarantine rather than retry. flush() runs from a bare `finally:` in # flush_worker, so raising here also skips the handoff cleanup, and an # undecodable file would otherwise be re-read on every flush forever. + # Reported as delivered because there is nothing left to deliver and the + # rest of the run should continue. try: claim.replace(claim.with_suffix(".corrupt")) except OSError: @@ -655,6 +666,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: except OSError: pass return 0, True + except OSError: + # Could not read it, which is not the same as having nothing to send. + # The file is left exactly where it is: a vanished or briefly unreadable + # claim is retryable, and quarantining it here would discard events over + # a transient filesystem error. Reported as undelivered so the run stops + # instead of counting a batch nothing was posted from as delivered. + return 0, False events = [] for line in lines: try: diff --git a/integrations/agent-plugin-core/tests/test_spool_delivery.py b/integrations/agent-plugin-core/tests/test_spool_delivery.py index a7646cc31..ac0bf6b22 100644 --- a/integrations/agent-plugin-core/tests/test_spool_delivery.py +++ b/integrations/agent-plugin-core/tests/test_spool_delivery.py @@ -266,13 +266,102 @@ def test_an_undeliverable_batch_is_eventually_given_up_on(telemetry): telemetry.record("doomed") telemetry._post = lambda payload, url: False + directory = telemetry.memory_core.data_dir() for _ in range(telemetry.MAX_CLAIM_ATTEMPTS + 3): telemetry.flush() + # Attempts now carry a cooldown, so a released claim is not instantly + # reclaimable. Age it to stand in for the wall time a real retry waits; + # without this the loop spins inside one cooldown and proves nothing. + for parked in directory.glob("telemetry-*.sending"): + stale = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(parked, (stale, stale)) - leftover = list(telemetry.memory_core.data_dir().glob("telemetry-*.sending")) + leftover = list(directory.glob("telemetry-*.sending")) assert leftover == [], f"batch never given up on: {[p.name for p in leftover]}" +def test_a_batch_that_cannot_be_read_is_not_counted_as_delivered(telemetry): + """Review finding: a read failure reported 'everything delivered'. + + Nothing was posted, so calling it delivered lets flush() carry on to other + claims as though this batch had arrived, and hides the failure from the one + signal that says the run went badly. It also must not quarantine: a briefly + unreadable file is retryable, and moving it to .corrupt discards the events + over a transient filesystem error, because nothing ever re-globs .corrupt. + """ + telemetry.record("search") + spool = telemetry._spool_path() + stale = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(spool, (stale, stale)) + claim = telemetry._claim_spool() + assert claim is not None + + original = Path.read_text + + def unreadable(self, *args, **kwargs): + if self == claim: + raise OSError(5, "I/O error") + return original(self, *args, **kwargs) + + Path.read_text = unreadable + try: + sent, delivered = telemetry._drain(claim) + finally: + Path.read_text = original + + assert sent == 0 + assert delivered is False, "an unread batch was reported as delivered" + assert claim.exists(), "a transient read error discarded the batch" + assert not list(claim.parent.glob("*.corrupt")), "quarantined over a transient error" + + +def test_undecodable_content_is_still_quarantined_and_the_run_continues(telemetry): + """The other half: genuinely unrecoverable content must not block the run. + + Guards the over-correction. If every read problem returned undelivered, one + torn file would stop every later claim on every flush, forever. + """ + telemetry.record("search") + spool = telemetry._spool_path() + stale = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(spool, (stale, stale)) + claim = telemetry._claim_spool() + assert claim is not None + claim.write_bytes(b"\xff\xfe torn \x00 write") + + sent, delivered = telemetry._drain(claim) + + assert (sent, delivered) == (0, True) + assert not claim.exists() + assert list(claim.parent.glob("*.corrupt")), "unrecoverable content was not quarantined" + + +def test_retries_are_spread_over_real_time_not_burned_at_once(telemetry): + """Review finding: releasing straight to reclaimable spent the budget instantly. + + Two senders hitting one momentary failure could walk a batch from attempt 0 + to the limit within seconds and discard it, when a retry a minute later would + have delivered. Each release now has to age past a cooldown that grows with + the attempts already spent. + """ + telemetry.record("doomed") + telemetry._post = lambda payload, url: False + + directory = telemetry.memory_core.data_dir() + telemetry.flush() + + parked = list(directory.glob("telemetry-*.sending")) + assert parked, "the batch was discarded on its first failure" + assert telemetry._claim_attempt(parked[0]) == 0 + + # Second sender, immediately: the cooldown has not elapsed, so it must not + # be able to spend another attempt. + telemetry.flush() + still = list(directory.glob("telemetry-*.sending")) + assert len(still) == 1 + assert telemetry._claim_attempt(still[0]) <= 1, "burned attempts without waiting" + + def test_a_legacy_claim_filename_is_not_mistaken_for_a_huge_attempt_count(telemetry): """The old shape is telemetry--.sending, and hex can start with 'a'.""" assert telemetry._claim_attempt(Path("telemetry-999-deadbeef.sending")) == 0 diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index a8f018f8e..a5107d430 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -105,6 +105,11 @@ MAX_CLAIM_ATTEMPTS = 3 # Parked claims drained per run, after the live spool. Bounded so a long backlog # cannot turn one flush into an unbounded send loop. MAX_PARKED_PER_RUN = 3 +# Added to the wait before a released claim becomes reclaimable, per attempt +# already spent. Releasing straight to "reclaimable now" let two senders burn the +# whole budget within seconds of one another on a single momentary failure, and +# discard a batch a retry a minute later would have delivered. +RETRY_COOLDOWN_SECONDS = 60 def is_enabled() -> bool: @@ -556,7 +561,11 @@ def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: if not _rewrite_claim(claim, remaining): return try: - released = time.time() - CLAIM_STALE_SECONDS - 1 + # Backdate past the stale threshold so the next flush can pick it up, + # minus a cooldown that grows with the attempts already spent. Clamped so + # the mtime never lands in the future, which would read as a live lease. + cooldown = min(_claim_attempt(claim) * RETRY_COOLDOWN_SECONDS, CLAIM_STALE_SECONDS) + released = time.time() - CLAIM_STALE_SECONDS - 1 + cooldown os.utime(claim, (released, released)) except OSError: pass @@ -642,11 +651,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except (OSError, ValueError): - # ValueError covers UnicodeDecodeError from a torn write. Quarantine - # rather than retry: flush() runs from a bare `finally:` in + except ValueError: + # UnicodeDecodeError from a torn write: the content is unrecoverable, so + # quarantine rather than retry. flush() runs from a bare `finally:` in # flush_worker, so raising here also skips the handoff cleanup, and an # undecodable file would otherwise be re-read on every flush forever. + # Reported as delivered because there is nothing left to deliver and the + # rest of the run should continue. try: claim.replace(claim.with_suffix(".corrupt")) except OSError: @@ -655,6 +666,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: except OSError: pass return 0, True + except OSError: + # Could not read it, which is not the same as having nothing to send. + # The file is left exactly where it is: a vanished or briefly unreadable + # claim is retryable, and quarantining it here would discard events over + # a transient filesystem error. Reported as undelivered so the run stops + # instead of counting a batch nothing was posted from as delivered. + return 0, False events = [] for line in lines: try: diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index a8f018f8e..a5107d430 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -105,6 +105,11 @@ MAX_CLAIM_ATTEMPTS = 3 # Parked claims drained per run, after the live spool. Bounded so a long backlog # cannot turn one flush into an unbounded send loop. MAX_PARKED_PER_RUN = 3 +# Added to the wait before a released claim becomes reclaimable, per attempt +# already spent. Releasing straight to "reclaimable now" let two senders burn the +# whole budget within seconds of one another on a single momentary failure, and +# discard a batch a retry a minute later would have delivered. +RETRY_COOLDOWN_SECONDS = 60 def is_enabled() -> bool: @@ -556,7 +561,11 @@ def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: if not _rewrite_claim(claim, remaining): return try: - released = time.time() - CLAIM_STALE_SECONDS - 1 + # Backdate past the stale threshold so the next flush can pick it up, + # minus a cooldown that grows with the attempts already spent. Clamped so + # the mtime never lands in the future, which would read as a live lease. + cooldown = min(_claim_attempt(claim) * RETRY_COOLDOWN_SECONDS, CLAIM_STALE_SECONDS) + released = time.time() - CLAIM_STALE_SECONDS - 1 + cooldown os.utime(claim, (released, released)) except OSError: pass @@ -642,11 +651,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except (OSError, ValueError): - # ValueError covers UnicodeDecodeError from a torn write. Quarantine - # rather than retry: flush() runs from a bare `finally:` in + except ValueError: + # UnicodeDecodeError from a torn write: the content is unrecoverable, so + # quarantine rather than retry. flush() runs from a bare `finally:` in # flush_worker, so raising here also skips the handoff cleanup, and an # undecodable file would otherwise be re-read on every flush forever. + # Reported as delivered because there is nothing left to deliver and the + # rest of the run should continue. try: claim.replace(claim.with_suffix(".corrupt")) except OSError: @@ -655,6 +666,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: except OSError: pass return 0, True + except OSError: + # Could not read it, which is not the same as having nothing to send. + # The file is left exactly where it is: a vanished or briefly unreadable + # claim is retryable, and quarantining it here would discard events over + # a transient filesystem error. Reported as undelivered so the run stops + # instead of counting a batch nothing was posted from as delivered. + return 0, False events = [] for line in lines: try: diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index a8f018f8e..a5107d430 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -105,6 +105,11 @@ MAX_CLAIM_ATTEMPTS = 3 # Parked claims drained per run, after the live spool. Bounded so a long backlog # cannot turn one flush into an unbounded send loop. MAX_PARKED_PER_RUN = 3 +# Added to the wait before a released claim becomes reclaimable, per attempt +# already spent. Releasing straight to "reclaimable now" let two senders burn the +# whole budget within seconds of one another on a single momentary failure, and +# discard a batch a retry a minute later would have delivered. +RETRY_COOLDOWN_SECONDS = 60 def is_enabled() -> bool: @@ -556,7 +561,11 @@ def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: if not _rewrite_claim(claim, remaining): return try: - released = time.time() - CLAIM_STALE_SECONDS - 1 + # Backdate past the stale threshold so the next flush can pick it up, + # minus a cooldown that grows with the attempts already spent. Clamped so + # the mtime never lands in the future, which would read as a live lease. + cooldown = min(_claim_attempt(claim) * RETRY_COOLDOWN_SECONDS, CLAIM_STALE_SECONDS) + released = time.time() - CLAIM_STALE_SECONDS - 1 + cooldown os.utime(claim, (released, released)) except OSError: pass @@ -642,11 +651,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except (OSError, ValueError): - # ValueError covers UnicodeDecodeError from a torn write. Quarantine - # rather than retry: flush() runs from a bare `finally:` in + except ValueError: + # UnicodeDecodeError from a torn write: the content is unrecoverable, so + # quarantine rather than retry. flush() runs from a bare `finally:` in # flush_worker, so raising here also skips the handoff cleanup, and an # undecodable file would otherwise be re-read on every flush forever. + # Reported as delivered because there is nothing left to deliver and the + # rest of the run should continue. try: claim.replace(claim.with_suffix(".corrupt")) except OSError: @@ -655,6 +666,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: except OSError: pass return 0, True + except OSError: + # Could not read it, which is not the same as having nothing to send. + # The file is left exactly where it is: a vanished or briefly unreadable + # claim is retryable, and quarantining it here would discard events over + # a transient filesystem error. Reported as undelivered so the run stops + # instead of counting a batch nothing was posted from as delivered. + return 0, False events = [] for line in lines: try: diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index a8f018f8e..a5107d430 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -105,6 +105,11 @@ MAX_CLAIM_ATTEMPTS = 3 # Parked claims drained per run, after the live spool. Bounded so a long backlog # cannot turn one flush into an unbounded send loop. MAX_PARKED_PER_RUN = 3 +# Added to the wait before a released claim becomes reclaimable, per attempt +# already spent. Releasing straight to "reclaimable now" let two senders burn the +# whole budget within seconds of one another on a single momentary failure, and +# discard a batch a retry a minute later would have delivered. +RETRY_COOLDOWN_SECONDS = 60 def is_enabled() -> bool: @@ -556,7 +561,11 @@ def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: if not _rewrite_claim(claim, remaining): return try: - released = time.time() - CLAIM_STALE_SECONDS - 1 + # Backdate past the stale threshold so the next flush can pick it up, + # minus a cooldown that grows with the attempts already spent. Clamped so + # the mtime never lands in the future, which would read as a live lease. + cooldown = min(_claim_attempt(claim) * RETRY_COOLDOWN_SECONDS, CLAIM_STALE_SECONDS) + released = time.time() - CLAIM_STALE_SECONDS - 1 + cooldown os.utime(claim, (released, released)) except OSError: pass @@ -642,11 +651,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except (OSError, ValueError): - # ValueError covers UnicodeDecodeError from a torn write. Quarantine - # rather than retry: flush() runs from a bare `finally:` in + except ValueError: + # UnicodeDecodeError from a torn write: the content is unrecoverable, so + # quarantine rather than retry. flush() runs from a bare `finally:` in # flush_worker, so raising here also skips the handoff cleanup, and an # undecodable file would otherwise be re-read on every flush forever. + # Reported as delivered because there is nothing left to deliver and the + # rest of the run should continue. try: claim.replace(claim.with_suffix(".corrupt")) except OSError: @@ -655,6 +666,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: except OSError: pass return 0, True + except OSError: + # Could not read it, which is not the same as having nothing to send. + # The file is left exactly where it is: a vanished or briefly unreadable + # claim is retryable, and quarantining it here would discard events over + # a transient filesystem error. Reported as undelivered so the run stops + # instead of counting a batch nothing was posted from as delivered. + return 0, False events = [] for line in lines: try: diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index a8f018f8e..a5107d430 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -105,6 +105,11 @@ MAX_CLAIM_ATTEMPTS = 3 # Parked claims drained per run, after the live spool. Bounded so a long backlog # cannot turn one flush into an unbounded send loop. MAX_PARKED_PER_RUN = 3 +# Added to the wait before a released claim becomes reclaimable, per attempt +# already spent. Releasing straight to "reclaimable now" let two senders burn the +# whole budget within seconds of one another on a single momentary failure, and +# discard a batch a retry a minute later would have delivered. +RETRY_COOLDOWN_SECONDS = 60 def is_enabled() -> bool: @@ -556,7 +561,11 @@ def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: if not _rewrite_claim(claim, remaining): return try: - released = time.time() - CLAIM_STALE_SECONDS - 1 + # Backdate past the stale threshold so the next flush can pick it up, + # minus a cooldown that grows with the attempts already spent. Clamped so + # the mtime never lands in the future, which would read as a live lease. + cooldown = min(_claim_attempt(claim) * RETRY_COOLDOWN_SECONDS, CLAIM_STALE_SECONDS) + released = time.time() - CLAIM_STALE_SECONDS - 1 + cooldown os.utime(claim, (released, released)) except OSError: pass @@ -642,11 +651,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except (OSError, ValueError): - # ValueError covers UnicodeDecodeError from a torn write. Quarantine - # rather than retry: flush() runs from a bare `finally:` in + except ValueError: + # UnicodeDecodeError from a torn write: the content is unrecoverable, so + # quarantine rather than retry. flush() runs from a bare `finally:` in # flush_worker, so raising here also skips the handoff cleanup, and an # undecodable file would otherwise be re-read on every flush forever. + # Reported as delivered because there is nothing left to deliver and the + # rest of the run should continue. try: claim.replace(claim.with_suffix(".corrupt")) except OSError: @@ -655,6 +666,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: except OSError: pass return 0, True + except OSError: + # Could not read it, which is not the same as having nothing to send. + # The file is left exactly where it is: a vanished or briefly unreadable + # claim is retryable, and quarantining it here would discard events over + # a transient filesystem error. Reported as undelivered so the run stops + # instead of counting a batch nothing was posted from as delivered. + return 0, False events = [] for line in lines: try: diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index a8f018f8e..a5107d430 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -105,6 +105,11 @@ MAX_CLAIM_ATTEMPTS = 3 # Parked claims drained per run, after the live spool. Bounded so a long backlog # cannot turn one flush into an unbounded send loop. MAX_PARKED_PER_RUN = 3 +# Added to the wait before a released claim becomes reclaimable, per attempt +# already spent. Releasing straight to "reclaimable now" let two senders burn the +# whole budget within seconds of one another on a single momentary failure, and +# discard a batch a retry a minute later would have delivered. +RETRY_COOLDOWN_SECONDS = 60 def is_enabled() -> bool: @@ -556,7 +561,11 @@ def _release_claim(claim: Path, remaining: list[dict[str, Any]]) -> None: if not _rewrite_claim(claim, remaining): return try: - released = time.time() - CLAIM_STALE_SECONDS - 1 + # Backdate past the stale threshold so the next flush can pick it up, + # minus a cooldown that grows with the attempts already spent. Clamped so + # the mtime never lands in the future, which would read as a live lease. + cooldown = min(_claim_attempt(claim) * RETRY_COOLDOWN_SECONDS, CLAIM_STALE_SECONDS) + released = time.time() - CLAIM_STALE_SECONDS - 1 + cooldown os.utime(claim, (released, released)) except OSError: pass @@ -642,11 +651,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: return 0, True try: lines = claim.read_text(encoding="utf-8").splitlines() - except (OSError, ValueError): - # ValueError covers UnicodeDecodeError from a torn write. Quarantine - # rather than retry: flush() runs from a bare `finally:` in + except ValueError: + # UnicodeDecodeError from a torn write: the content is unrecoverable, so + # quarantine rather than retry. flush() runs from a bare `finally:` in # flush_worker, so raising here also skips the handoff cleanup, and an # undecodable file would otherwise be re-read on every flush forever. + # Reported as delivered because there is nothing left to deliver and the + # rest of the run should continue. try: claim.replace(claim.with_suffix(".corrupt")) except OSError: @@ -655,6 +666,13 @@ def _drain(claim: Path | None) -> tuple[int, bool]: except OSError: pass return 0, True + except OSError: + # Could not read it, which is not the same as having nothing to send. + # The file is left exactly where it is: a vanished or briefly unreadable + # claim is retryable, and quarantining it here would discard events over + # a transient filesystem error. Reported as undelivered so the run stops + # instead of counting a batch nothing was posted from as delivered. + return 0, False events = [] for line in lines: try: From 2266eccf071e84df161fd8e4f3f861fa8bd85170 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Wed, 16 Sep 2026 22:15:07 +0530 Subject: [PATCH 23/30] fix(plugins): make the install marker durable before claim_install returns Review nit from @karthik-indla on this PR. A hard kill between the O_EXCL open and the buffered write reaching disk left a marker that exists but parses to nothing: is_first_run reads it as claimed, so that install is never counted, and claim_version_change cannot read a version out of it. Not temp-and-rename, which is what the equivalent fixes in this stack use: the O_EXCL open is what makes this claim exclusive across concurrently starting sessions, and a rename would clobber rather than lose the race. The content is the part that needed making safe, so it is flushed and fsynced before the call returns. The recovery path stays as the backstop: _repair_install_state already rewrites an unparseable marker so version tracking resumes. 304 passed, 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- integrations/agent-plugin-core/python/telemetry.py | 8 ++++++++ integrations/antigravity-plugin/core/telemetry.py | 8 ++++++++ integrations/claude-code-plugin/core/telemetry.py | 8 ++++++++ integrations/codex-plugin/core/telemetry.py | 8 ++++++++ integrations/cursor-plugin/core/telemetry.py | 8 ++++++++ integrations/kimi-plugin/core/telemetry.py | 8 ++++++++ integrations/mem0-agent-plugin/core/telemetry.py | 8 ++++++++ 7 files changed, 56 insertions(+) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index b7e52d24f..b3c2ef586 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -370,6 +370,14 @@ def claim_install(was_empty: bool | None = None) -> str | None: }, stream, ) + # Durable before this returns. The O_EXCL open is what makes the + # claim exclusive, so it cannot be replaced by a temp-and-rename + # without losing that, which leaves the content as the thing to make + # safe. A kill between the open and this fsync used to leave a marker + # that exists but parses to nothing: is_first_run reads it as claimed + # and claim_version_change cannot read a version out of it. + stream.flush() + os.fsync(stream.fileno()) except OSError: pass return "upgrade" if upgrading else "install" diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index b7e52d24f..b3c2ef586 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -370,6 +370,14 @@ def claim_install(was_empty: bool | None = None) -> str | None: }, stream, ) + # Durable before this returns. The O_EXCL open is what makes the + # claim exclusive, so it cannot be replaced by a temp-and-rename + # without losing that, which leaves the content as the thing to make + # safe. A kill between the open and this fsync used to leave a marker + # that exists but parses to nothing: is_first_run reads it as claimed + # and claim_version_change cannot read a version out of it. + stream.flush() + os.fsync(stream.fileno()) except OSError: pass return "upgrade" if upgrading else "install" diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index b7e52d24f..b3c2ef586 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -370,6 +370,14 @@ def claim_install(was_empty: bool | None = None) -> str | None: }, stream, ) + # Durable before this returns. The O_EXCL open is what makes the + # claim exclusive, so it cannot be replaced by a temp-and-rename + # without losing that, which leaves the content as the thing to make + # safe. A kill between the open and this fsync used to leave a marker + # that exists but parses to nothing: is_first_run reads it as claimed + # and claim_version_change cannot read a version out of it. + stream.flush() + os.fsync(stream.fileno()) except OSError: pass return "upgrade" if upgrading else "install" diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index b7e52d24f..b3c2ef586 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -370,6 +370,14 @@ def claim_install(was_empty: bool | None = None) -> str | None: }, stream, ) + # Durable before this returns. The O_EXCL open is what makes the + # claim exclusive, so it cannot be replaced by a temp-and-rename + # without losing that, which leaves the content as the thing to make + # safe. A kill between the open and this fsync used to leave a marker + # that exists but parses to nothing: is_first_run reads it as claimed + # and claim_version_change cannot read a version out of it. + stream.flush() + os.fsync(stream.fileno()) except OSError: pass return "upgrade" if upgrading else "install" diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index b7e52d24f..b3c2ef586 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -370,6 +370,14 @@ def claim_install(was_empty: bool | None = None) -> str | None: }, stream, ) + # Durable before this returns. The O_EXCL open is what makes the + # claim exclusive, so it cannot be replaced by a temp-and-rename + # without losing that, which leaves the content as the thing to make + # safe. A kill between the open and this fsync used to leave a marker + # that exists but parses to nothing: is_first_run reads it as claimed + # and claim_version_change cannot read a version out of it. + stream.flush() + os.fsync(stream.fileno()) except OSError: pass return "upgrade" if upgrading else "install" diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index b7e52d24f..b3c2ef586 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -370,6 +370,14 @@ def claim_install(was_empty: bool | None = None) -> str | None: }, stream, ) + # Durable before this returns. The O_EXCL open is what makes the + # claim exclusive, so it cannot be replaced by a temp-and-rename + # without losing that, which leaves the content as the thing to make + # safe. A kill between the open and this fsync used to leave a marker + # that exists but parses to nothing: is_first_run reads it as claimed + # and claim_version_change cannot read a version out of it. + stream.flush() + os.fsync(stream.fileno()) except OSError: pass return "upgrade" if upgrading else "install" diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index b7e52d24f..b3c2ef586 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -370,6 +370,14 @@ def claim_install(was_empty: bool | None = None) -> str | None: }, stream, ) + # Durable before this returns. The O_EXCL open is what makes the + # claim exclusive, so it cannot be replaced by a temp-and-rename + # without losing that, which leaves the content as the thing to make + # safe. A kill between the open and this fsync used to leave a marker + # that exists but parses to nothing: is_first_run reads it as claimed + # and claim_version_change cannot read a version out of it. + stream.flush() + os.fsync(stream.fileno()) except OSError: pass return "upgrade" if upgrading else "install" From 92aa8a1de17385e85e3dfe8af2fc0d31b55ce4c3 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Wed, 16 Sep 2026 22:16:20 +0530 Subject: [PATCH 24/30] fix(vercel-ai-sdk): inject the provider version at build instead of hardcoding it Review finding from @karthik-indla on this PR. src/mem0-utils.ts carried PROVIDER_VERSION = "3.0.2" as a literal. It matches package.json today and misreports the client version from the next release bump onwards, which is the one thing X-Mem0-Client exists to carry. Every other client in the repo injects at build: mem0-ts via __MEM0_SDK_VERSION__, the Python side via importlib.metadata, the CLIs via __CLI_VERSION__. tsup now defines __MEM0_PROVIDER_VERSION__ from package.json, and the source falls back to "dev" only when run unbundled, such as in tests. Verified in the built bundle: PROVIDER_VERSION resolves to "3.0.2" and no placeholder survives. resolveJsonModule is enabled alongside it, matching mem0-ts, because tsc --noEmit covers tsup.config.ts and the package.json import fails without it. Type check clean, build clean. The jest suite's failure is pre-existing and unrelated: it requires a live MEM0_API_KEY, confirmed by running it on a stashed tree. Python side 311 passed, 8 skipped; pi-agent 94 passed. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- integrations/vercel-ai-sdk/src/mem0-utils.ts | 7 ++++++- integrations/vercel-ai-sdk/tsconfig.json | 1 + integrations/vercel-ai-sdk/tsup.config.ts | 7 +++++++ 3 files changed, 14 insertions(+), 1 deletion(-) diff --git a/integrations/vercel-ai-sdk/src/mem0-utils.ts b/integrations/vercel-ai-sdk/src/mem0-utils.ts index 8fa20440c..b7a041939 100644 --- a/integrations/vercel-ai-sdk/src/mem0-utils.ts +++ b/integrations/vercel-ai-sdk/src/mem0-utils.ts @@ -1,4 +1,9 @@ -const PROVIDER_VERSION = "3.0.2"; +declare const __MEM0_PROVIDER_VERSION__: string | undefined; + +// Replaced at build time by tsup `define`. The fallback only applies when the +// source is run unbundled, such as in tests. +const PROVIDER_VERSION = + typeof __MEM0_PROVIDER_VERSION__ !== "undefined" ? __MEM0_PROVIDER_VERSION__ : "dev"; import { LanguageModelV3Prompt } from '@ai-sdk/provider'; import { Mem0ConfigSettings } from './mem0-types'; diff --git a/integrations/vercel-ai-sdk/tsconfig.json b/integrations/vercel-ai-sdk/tsconfig.json index b05d5db02..e40350730 100644 --- a/integrations/vercel-ai-sdk/tsconfig.json +++ b/integrations/vercel-ai-sdk/tsconfig.json @@ -12,6 +12,7 @@ "noUnusedLocals": false, "noUnusedParameters": false, "preserveWatchOutput": true, + "resolveJsonModule": true, "skipLibCheck": true, "strict": true, "types": ["@types/node", "jest"], diff --git a/integrations/vercel-ai-sdk/tsup.config.ts b/integrations/vercel-ai-sdk/tsup.config.ts index 2c8f74a6d..ff2d298c0 100644 --- a/integrations/vercel-ai-sdk/tsup.config.ts +++ b/integrations/vercel-ai-sdk/tsup.config.ts @@ -1,4 +1,5 @@ import { defineConfig } from 'tsup' +import pkg from './package.json' export default defineConfig([ { @@ -6,5 +7,11 @@ export default defineConfig([ entry: ['src/index.ts'], format: ['cjs', 'esm'], sourcemap: true, + // Injected rather than written in the source. A hardcoded literal matches + // package.json on the day it is written and misreports the client version + // from the next release bump onwards. Same mechanism as mem0-ts. + define: { + __MEM0_PROVIDER_VERSION__: JSON.stringify(pkg.version), + }, }, ]) \ No newline at end of file From c043e97673c3ba6cba52375d94ce8fa14a14115f Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Thu, 17 Sep 2026 19:27:39 +0530 Subject: [PATCH 25/30] fix(plugins): read the salt before minting one, and stop overclaiming backend support Two findings from an independent review of this branch. _install_salt went straight to create, fsync, link, unlink on every call. All but the first process finds the salt already published, so each hook paid an fsync to discover that, on a path documented as appending a line and returning. Hooks are separate processes firing on every tool call inside a few-second budget. Measured: cold process one fsync, warm process zero, same salt. The deepseek README said the backend recognizes DEEPSEEK_HARNESS so usage surfaces by name. It does not yet. That value, along with STRANDS, ZAPIER, MEM0_PLUGIN, PI_AGENT and VERCEL_AI_SDK, buckets into OTHERS until mem0ai/platform#3602 ships, so the README now states the dependency and links it. The neighbouring comment in mem0-strands was already accurate and is unchanged: it says recognized values live in the allowlist without claiming this one is in it. 265 passed, 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- integrations/agent-plugin-core/python/telemetry.py | 12 ++++++++++++ integrations/antigravity-plugin/core/telemetry.py | 12 ++++++++++++ integrations/claude-code-plugin/core/telemetry.py | 12 ++++++++++++ integrations/codex-plugin/core/telemetry.py | 12 ++++++++++++ integrations/cursor-plugin/core/telemetry.py | 12 ++++++++++++ integrations/deepseek-plugin/README.md | 2 +- integrations/kimi-plugin/core/telemetry.py | 12 ++++++++++++ integrations/mem0-agent-plugin/core/telemetry.py | 12 ++++++++++++ 8 files changed, 85 insertions(+), 1 deletion(-) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index d86873d3d..132de5b0c 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -133,6 +133,18 @@ def _install_salt() -> str: return _salt_cache path = _salt_path() + # Read before writing. Hooks are separate processes firing on every tool + # call, so all but the first find the salt already published; going straight + # to create-fsync-link-unlink meant every one of them paid an fsync to + # discover that, on a path whose whole promise is appending a line and + # returning. + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + if _salt_cache: + return _salt_cache + except OSError: + pass + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index d86873d3d..132de5b0c 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -133,6 +133,18 @@ def _install_salt() -> str: return _salt_cache path = _salt_path() + # Read before writing. Hooks are separate processes firing on every tool + # call, so all but the first find the salt already published; going straight + # to create-fsync-link-unlink meant every one of them paid an fsync to + # discover that, on a path whose whole promise is appending a line and + # returning. + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + if _salt_cache: + return _salt_cache + except OSError: + pass + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index d86873d3d..132de5b0c 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -133,6 +133,18 @@ def _install_salt() -> str: return _salt_cache path = _salt_path() + # Read before writing. Hooks are separate processes firing on every tool + # call, so all but the first find the salt already published; going straight + # to create-fsync-link-unlink meant every one of them paid an fsync to + # discover that, on a path whose whole promise is appending a line and + # returning. + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + if _salt_cache: + return _salt_cache + except OSError: + pass + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index d86873d3d..132de5b0c 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -133,6 +133,18 @@ def _install_salt() -> str: return _salt_cache path = _salt_path() + # Read before writing. Hooks are separate processes firing on every tool + # call, so all but the first find the salt already published; going straight + # to create-fsync-link-unlink meant every one of them paid an fsync to + # discover that, on a path whose whole promise is appending a line and + # returning. + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + if _salt_cache: + return _salt_cache + except OSError: + pass + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index d86873d3d..132de5b0c 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -133,6 +133,18 @@ def _install_salt() -> str: return _salt_cache path = _salt_path() + # Read before writing. Hooks are separate processes firing on every tool + # call, so all but the first find the salt already published; going straight + # to create-fsync-link-unlink meant every one of them paid an fsync to + # discover that, on a path whose whole promise is appending a line and + # returning. + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + if _salt_cache: + return _salt_cache + except OSError: + pass + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) diff --git a/integrations/deepseek-plugin/README.md b/integrations/deepseek-plugin/README.md index bcd333311..d5cb3345a 100644 --- a/integrations/deepseek-plugin/README.md +++ b/integrations/deepseek-plugin/README.md @@ -86,7 +86,7 @@ Per-call `userId` overrides are rejected unless the operator enables `allowUserO ## Telemetry -Writes are tagged `source="DEEPSEEK_HARNESS"`, which the Mem0 backend recognizes so usage surfaces by name rather than bucketing into `OTHERS`. +Writes are tagged `source="DEEPSEEK_HARNESS"`. That value has to exist in the backend's `EventSource` enum for usage to surface by name; until it does, these writes read as `OTHERS`. It is added by [mem0ai/platform#3602](https://github.com/mem0ai/platform/pull/3602), which has to ship before this claim is true. The plugin also sends usage events (which tool ran, duration, result counts, coarse failure kind) so Mem0 can tell how the plugin is used and where it breaks. These are **not anonymous**: when an API key is configured they are sent under your Mem0 account email, the same way the SDK attributes its own. Queries, memory text, and entity ids are never sent. Turn it off with `MEM0_TELEMETRY=false`. diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index d86873d3d..132de5b0c 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -133,6 +133,18 @@ def _install_salt() -> str: return _salt_cache path = _salt_path() + # Read before writing. Hooks are separate processes firing on every tool + # call, so all but the first find the salt already published; going straight + # to create-fsync-link-unlink meant every one of them paid an fsync to + # discover that, on a path whose whole promise is appending a line and + # returning. + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + if _salt_cache: + return _salt_cache + except OSError: + pass + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index d86873d3d..132de5b0c 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -133,6 +133,18 @@ def _install_salt() -> str: return _salt_cache path = _salt_path() + # Read before writing. Hooks are separate processes firing on every tool + # call, so all but the first find the salt already published; going straight + # to create-fsync-link-unlink meant every one of them paid an fsync to + # discover that, on a path whose whole promise is appending a line and + # returning. + try: + _salt_cache = path.read_text(encoding="utf-8").strip() + if _salt_cache: + return _salt_cache + except OSError: + pass + temporary = path.with_name(f"{path.name}.{os.getpid()}.tmp") try: path.parent.mkdir(parents=True, exist_ok=True) From 4edfaabc0604637a4c44b22aeea2f83212eeff97 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Thu, 17 Sep 2026 19:28:08 +0530 Subject: [PATCH 26/30] fix(plugins): collect quarantined batches instead of leaving them on disk forever Review finding. _sweep_debris globbed only *.partial. The *.corrupt files this PR writes when a batch cannot be decoded are matched by no glob in the module, so they accumulated for the life of the install. Collected on the expiry window rather than the stale window, deliberately: a quarantined batch is the only remaining evidence of events that could not be delivered, so someone chasing a report of missing telemetry has to be able to find a recent one. Debris keeps the short window; it carries nothing. One test, asserting both halves: a recent quarantine survives and an expired one does not. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- .../agent-plugin-core/python/telemetry.py | 18 +++++++++++++--- .../tests/test_spool_delivery.py | 21 +++++++++++++++++++ .../antigravity-plugin/core/telemetry.py | 18 +++++++++++++--- .../claude-code-plugin/core/telemetry.py | 18 +++++++++++++--- integrations/codex-plugin/core/telemetry.py | 18 +++++++++++++--- integrations/cursor-plugin/core/telemetry.py | 18 +++++++++++++--- integrations/kimi-plugin/core/telemetry.py | 18 +++++++++++++--- .../mem0-agent-plugin/core/telemetry.py | 18 +++++++++++++--- 8 files changed, 126 insertions(+), 21 deletions(-) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index f46e1bf55..9084c8a24 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -462,10 +462,16 @@ def _claim_spool() -> Path | None: def _sweep_debris(directory: Path) -> None: - """Remove temp files orphaned by a crash between write and rename. + """Remove files nothing else will ever pick up again. - Neither glob in this module matches *.partial, so nothing else would ever - clean them up. + *.partial is a temp file orphaned by a crash between write and rename. + *.corrupt is a batch quarantined for undecodable content. No glob in this + module matches either, so without this they accumulate on disk for the life + of the install. + + Quarantined batches are kept far longer than debris: they are the only + evidence left of events that could not be delivered, and someone diagnosing + a report of missing telemetry has to be able to find one. """ now = time.time() for debris in directory.glob("telemetry-*.partial"): @@ -474,6 +480,12 @@ def _sweep_debris(directory: Path) -> None: debris.unlink() except OSError: continue + for quarantined in directory.glob("telemetry-*.corrupt"): + try: + if now - quarantined.stat().st_mtime > CLAIM_EXPIRY_SECONDS: + quarantined.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/agent-plugin-core/tests/test_spool_delivery.py b/integrations/agent-plugin-core/tests/test_spool_delivery.py index ac0bf6b22..03434177a 100644 --- a/integrations/agent-plugin-core/tests/test_spool_delivery.py +++ b/integrations/agent-plugin-core/tests/test_spool_delivery.py @@ -409,3 +409,24 @@ def test_partial_files_are_swept(telemetry): telemetry.flush() assert not debris.exists() + + +def test_quarantined_batches_are_eventually_collected(telemetry): + """Nothing re-globs .corrupt, so without a sweep they live on disk forever. + + Kept much longer than .partial debris on purpose: a quarantined batch is the + only remaining evidence of events that could not be delivered. + """ + directory = telemetry.memory_core.data_dir() + directory.mkdir(parents=True, exist_ok=True) + fresh = directory / "telemetry-1-aaaaaaaa-a0.corrupt" + old = directory / "telemetry-2-bbbbbbbb-a0.corrupt" + for path in (fresh, old): + path.write_text("torn", encoding="utf-8") + expired = time.time() - (telemetry.CLAIM_EXPIRY_SECONDS + 60) + os.utime(old, (expired, expired)) + + telemetry._sweep_debris(directory) + + assert fresh.exists(), "a recent quarantine was discarded before anyone could look at it" + assert not old.exists(), "an expired quarantine was left on disk forever" diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index f46e1bf55..9084c8a24 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -462,10 +462,16 @@ def _claim_spool() -> Path | None: def _sweep_debris(directory: Path) -> None: - """Remove temp files orphaned by a crash between write and rename. + """Remove files nothing else will ever pick up again. - Neither glob in this module matches *.partial, so nothing else would ever - clean them up. + *.partial is a temp file orphaned by a crash between write and rename. + *.corrupt is a batch quarantined for undecodable content. No glob in this + module matches either, so without this they accumulate on disk for the life + of the install. + + Quarantined batches are kept far longer than debris: they are the only + evidence left of events that could not be delivered, and someone diagnosing + a report of missing telemetry has to be able to find one. """ now = time.time() for debris in directory.glob("telemetry-*.partial"): @@ -474,6 +480,12 @@ def _sweep_debris(directory: Path) -> None: debris.unlink() except OSError: continue + for quarantined in directory.glob("telemetry-*.corrupt"): + try: + if now - quarantined.stat().st_mtime > CLAIM_EXPIRY_SECONDS: + quarantined.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index f46e1bf55..9084c8a24 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -462,10 +462,16 @@ def _claim_spool() -> Path | None: def _sweep_debris(directory: Path) -> None: - """Remove temp files orphaned by a crash between write and rename. + """Remove files nothing else will ever pick up again. - Neither glob in this module matches *.partial, so nothing else would ever - clean them up. + *.partial is a temp file orphaned by a crash between write and rename. + *.corrupt is a batch quarantined for undecodable content. No glob in this + module matches either, so without this they accumulate on disk for the life + of the install. + + Quarantined batches are kept far longer than debris: they are the only + evidence left of events that could not be delivered, and someone diagnosing + a report of missing telemetry has to be able to find one. """ now = time.time() for debris in directory.glob("telemetry-*.partial"): @@ -474,6 +480,12 @@ def _sweep_debris(directory: Path) -> None: debris.unlink() except OSError: continue + for quarantined in directory.glob("telemetry-*.corrupt"): + try: + if now - quarantined.stat().st_mtime > CLAIM_EXPIRY_SECONDS: + quarantined.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index f46e1bf55..9084c8a24 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -462,10 +462,16 @@ def _claim_spool() -> Path | None: def _sweep_debris(directory: Path) -> None: - """Remove temp files orphaned by a crash between write and rename. + """Remove files nothing else will ever pick up again. - Neither glob in this module matches *.partial, so nothing else would ever - clean them up. + *.partial is a temp file orphaned by a crash between write and rename. + *.corrupt is a batch quarantined for undecodable content. No glob in this + module matches either, so without this they accumulate on disk for the life + of the install. + + Quarantined batches are kept far longer than debris: they are the only + evidence left of events that could not be delivered, and someone diagnosing + a report of missing telemetry has to be able to find one. """ now = time.time() for debris in directory.glob("telemetry-*.partial"): @@ -474,6 +480,12 @@ def _sweep_debris(directory: Path) -> None: debris.unlink() except OSError: continue + for quarantined in directory.glob("telemetry-*.corrupt"): + try: + if now - quarantined.stat().st_mtime > CLAIM_EXPIRY_SECONDS: + quarantined.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index f46e1bf55..9084c8a24 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -462,10 +462,16 @@ def _claim_spool() -> Path | None: def _sweep_debris(directory: Path) -> None: - """Remove temp files orphaned by a crash between write and rename. + """Remove files nothing else will ever pick up again. - Neither glob in this module matches *.partial, so nothing else would ever - clean them up. + *.partial is a temp file orphaned by a crash between write and rename. + *.corrupt is a batch quarantined for undecodable content. No glob in this + module matches either, so without this they accumulate on disk for the life + of the install. + + Quarantined batches are kept far longer than debris: they are the only + evidence left of events that could not be delivered, and someone diagnosing + a report of missing telemetry has to be able to find one. """ now = time.time() for debris in directory.glob("telemetry-*.partial"): @@ -474,6 +480,12 @@ def _sweep_debris(directory: Path) -> None: debris.unlink() except OSError: continue + for quarantined in directory.glob("telemetry-*.corrupt"): + try: + if now - quarantined.stat().st_mtime > CLAIM_EXPIRY_SECONDS: + quarantined.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index f46e1bf55..9084c8a24 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -462,10 +462,16 @@ def _claim_spool() -> Path | None: def _sweep_debris(directory: Path) -> None: - """Remove temp files orphaned by a crash between write and rename. + """Remove files nothing else will ever pick up again. - Neither glob in this module matches *.partial, so nothing else would ever - clean them up. + *.partial is a temp file orphaned by a crash between write and rename. + *.corrupt is a batch quarantined for undecodable content. No glob in this + module matches either, so without this they accumulate on disk for the life + of the install. + + Quarantined batches are kept far longer than debris: they are the only + evidence left of events that could not be delivered, and someone diagnosing + a report of missing telemetry has to be able to find one. """ now = time.time() for debris in directory.glob("telemetry-*.partial"): @@ -474,6 +480,12 @@ def _sweep_debris(directory: Path) -> None: debris.unlink() except OSError: continue + for quarantined in directory.glob("telemetry-*.corrupt"): + try: + if now - quarantined.stat().st_mtime > CLAIM_EXPIRY_SECONDS: + quarantined.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index f46e1bf55..9084c8a24 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -462,10 +462,16 @@ def _claim_spool() -> Path | None: def _sweep_debris(directory: Path) -> None: - """Remove temp files orphaned by a crash between write and rename. + """Remove files nothing else will ever pick up again. - Neither glob in this module matches *.partial, so nothing else would ever - clean them up. + *.partial is a temp file orphaned by a crash between write and rename. + *.corrupt is a batch quarantined for undecodable content. No glob in this + module matches either, so without this they accumulate on disk for the life + of the install. + + Quarantined batches are kept far longer than debris: they are the only + evidence left of events that could not be delivered, and someone diagnosing + a report of missing telemetry has to be able to find one. """ now = time.time() for debris in directory.glob("telemetry-*.partial"): @@ -474,6 +480,12 @@ def _sweep_debris(directory: Path) -> None: debris.unlink() except OSError: continue + for quarantined in directory.glob("telemetry-*.corrupt"): + try: + if now - quarantined.stat().st_mtime > CLAIM_EXPIRY_SECONDS: + quarantined.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: From 3a72dfdc52303efa8d105148685d9c09b95e250f Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Thu, 17 Sep 2026 19:29:13 +0530 Subject: [PATCH 27/30] fix(integrations): reserve our own slot in the client stack, and drop whole entries Two review findings on this PR. All three client-stack implementations appended our entry and then trimmed to four, so whenever a caller already sent four entries the one dropped was exactly the one the function exists to add. We vanished from our own stack while every caller claim survived. The character cap was worse: slicing the joined string severs an identifier, and the platform parses the fragment as a real client, so a truncated tail arrives as a client literally named "me". Both caps now drop whole entries and the reserved slot is ours, in the Python SDK, the TypeScript SDK and pi-agent. mcp-server has the same fix on the platform branch. The deepseek comment claimed the backend's allowlist recognizes DEEPSEEK_HARNESS. This PR introduced that wording, replacing a neutral one. It is not true until mem0ai/platform#3602 ships, so it now states the dependency. Two pi-agent tests: our entry survives a full caller stack, and every surviving entry is whole rather than a severed tail. Python side verified directly, a 4-entry caller stack keeps mem0-python and long entries are dropped whole. 312 passed 8 skipped, pi-agent 96, bundles clean, TS SDK builds. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- integrations/deepseek-plugin/src/index.ts | 5 +-- .../pi-agent-plugin/src/attribution.test.ts | 27 +++++++++++++++ .../pi-agent-plugin/src/attribution.ts | 27 +++++++++++---- mem0-ts/src/client/mem0.ts | 28 ++++++++++++++-- mem0/client/main.py | 33 ++++++++++++------- 5 files changed, 97 insertions(+), 23 deletions(-) diff --git a/integrations/deepseek-plugin/src/index.ts b/integrations/deepseek-plugin/src/index.ts index 2d24b498a..3ac86f4b0 100644 --- a/integrations/deepseek-plugin/src/index.ts +++ b/integrations/deepseek-plugin/src/index.ts @@ -26,8 +26,9 @@ export const name = "mem0"; export const inject = ["tools", "systemPrompt"]; // Tags writes so Mem0's backend attributes them to this integration in -// telemetry. The backend's KNOWN_EVENT_SOURCES allowlist recognizes this value; -// anything outside it buckets into "OTHERS". +// telemetry. Values outside the backend's KNOWN_EVENT_SOURCES allowlist bucket +// into "OTHERS"; this one is added by mem0ai/platform#3602 and reads as OTHERS +// until that ships. const SOURCE = "DEEPSEEK_HARNESS"; const DEFAULT_SEARCH_LIMIT = 10; diff --git a/integrations/pi-agent-plugin/src/attribution.test.ts b/integrations/pi-agent-plugin/src/attribution.test.ts index 79d938c62..f90d28da3 100644 --- a/integrations/pi-agent-plugin/src/attribution.test.ts +++ b/integrations/pi-agent-plugin/src/attribution.test.ts @@ -51,3 +51,30 @@ describe("applySurfaceHeaders", () => { expect(headers["X-Mem0-Client"].length).toBeLessThanOrEqual(200); }); }); + +describe("client stack bounding", () => { + it("keeps our own entry when the caller already filled the stack", () => { + // The defect: pushing then trimming to four dropped exactly the entry this + // function exists to add, so we vanished from our own stack. + const mem0 = client({ "X-Mem0-Client": "a/1, b/2, c/3, d/4" }); + applySurfaceHeaders(mem0); + const stack = (mem0 as unknown as { headers: Record }).headers["X-Mem0-Client"]; + + expect(stack).toMatch(/mem0-pi-agent\//); + expect(stack.split(",").length).toBeLessThanOrEqual(4); + }); + + it("drops whole entries at the character cap, never a fragment", () => { + const long = `${"n".repeat(90)}/1.0, ${"m".repeat(90)}/1.0, ${"o".repeat(90)}/1.0`; + const mem0 = client({ "X-Mem0-Client": long }); + applySurfaceHeaders(mem0); + const stack = (mem0 as unknown as { headers: Record }).headers["X-Mem0-Client"]; + + expect(stack.length).toBeLessThanOrEqual(200); + expect(stack.endsWith("/0.0.0") || /mem0-pi-agent\/[\w.\-]+$/.test(stack)).toBe(true); + // Every surviving entry is whole: name/version, no severed tail. + for (const entry of stack.split(",")) { + expect(entry.trim()).toMatch(/^[^/]+\/[^/]+$/); + } + }); +}); diff --git a/integrations/pi-agent-plugin/src/attribution.ts b/integrations/pi-agent-plugin/src/attribution.ts index 7ab3ea6d6..2cbc9a73e 100644 --- a/integrations/pi-agent-plugin/src/attribution.ts +++ b/integrations/pi-agent-plugin/src/attribution.ts @@ -18,7 +18,26 @@ const PLUGIN_VERSION = (() => { })(); const MAX_STACK_ENTRIES = 4; -const MAX_HEADER_CHARS = 200; +const MAX_STACK_CHARS = 200; + +/** + * Append our own entry and bound the result, dropping WHOLE entries. + * + * Neither cap cuts characters: slicing the joined string severs an identifier + * and leaves a fragment the platform parses as a real client name. And the + * reserved slot is ours, since it is the only entry this layer can vouch for. + */ +function boundedStack(callerEntries: string[], own: string): string { + const kept: string[] = []; + let budget = MAX_STACK_CHARS - own.length; + for (const entry of callerEntries.slice(0, MAX_STACK_ENTRIES - 1)) { + const cost = entry.length + ", ".length; + if (cost > budget) break; + budget -= cost; + kept.push(entry); + } + return [...kept, own].join(", "); +} /** * Stamp surface identity onto the shared client, once, at construction. @@ -42,9 +61,5 @@ export function applySurfaceHeaders(client: MemoryClient): void { .split(",") .map((part) => part.trim()) .filter(Boolean); - existing.push(`mem0-pi-agent/${PLUGIN_VERSION}`); - headers["X-Mem0-Client"] = existing - .slice(0, MAX_STACK_ENTRIES) - .join(", ") - .slice(0, MAX_HEADER_CHARS); + headers["X-Mem0-Client"] = boundedStack(existing, `mem0-pi-agent/${PLUGIN_VERSION}`); } diff --git a/mem0-ts/src/client/mem0.ts b/mem0-ts/src/client/mem0.ts index ddea270a2..33e03f0c2 100644 --- a/mem0-ts/src/client/mem0.ts +++ b/mem0-ts/src/client/mem0.ts @@ -103,6 +103,30 @@ declare const __MEM0_SDK_VERSION__: string | undefined; const SDK_VERSION = typeof __MEM0_SDK_VERSION__ !== "undefined" ? __MEM0_SDK_VERSION__ : "dev"; +const MAX_STACK_ENTRIES = 4; +const MAX_STACK_CHARS = 200; + +/** + * Append our own entry and bound the result, dropping WHOLE entries. + * + * Neither cap cuts characters: slicing the joined string severs an identifier + * and leaves a fragment the platform parses as a real client name. And the + * reserved slot is ours. Pushing first and then trimming to four dropped exactly + * the entry this exists to add whenever a caller already sent four, so we + * vanished from our own stack while every caller claim survived. + */ +function boundedStack(callerEntries: string[], own: string): string { + const kept: string[] = []; + let budget = MAX_STACK_CHARS - own.length; + for (const entry of callerEntries.slice(0, MAX_STACK_ENTRIES - 1)) { + const cost = entry.length + ", ".length; + if (cost > budget) break; + budget -= cost; + kept.push(entry); + } + return [...kept, own].join(", "); +} + /** * Surface-identity headers. * @@ -121,10 +145,8 @@ function surfaceHeaders(): Record { .map((part) => part.trim()) .filter(Boolean) : []; - entries.push(`mem0-js/${SDK_VERSION}`); - const headers: Record = { - "X-Mem0-Client": entries.slice(0, 4).join(", ").slice(0, 200), + "X-Mem0-Client": boundedStack(entries, `mem0-js/${SDK_VERSION}`), }; const source = (env.MEM0_SOURCE ?? "").trim(); if (source) headers["X-Mem0-Source"] = source; diff --git a/mem0/client/main.py b/mem0/client/main.py index abdf61bca..65f2212b0 100644 --- a/mem0/client/main.py +++ b/mem0/client/main.py @@ -103,8 +103,7 @@ def _apply_client_headers(client: Any, api_key: str, user_id: str) -> None: outer_stack = existing.get("X-Mem0-Client") if outer_stack: entries = [part.strip() for part in str(outer_stack).split(",") if part.strip()] - entries.append(f"mem0-python/{_sdk_version()}") - mine["X-Mem0-Client"] = _bounded_stack(entries) + mine["X-Mem0-Client"] = _bounded_stack(entries, f"mem0-python/{_sdk_version()}") for name, value in mine.items(): if name in ("X-Mem0-Source", "X-Application") and existing.get(name): @@ -112,19 +111,29 @@ def _apply_client_headers(client: Any, api_key: str, user_id: str) -> None: existing[name] = value -def _bounded_stack(entries) -> str: - """Join stack entries within the cap, dropping whole entries not characters. +MAX_STACK_ENTRIES = 4 +MAX_STACK_CHARS = 200 - A blunt slice cut mid-identifier and left a fragment that parses as a real - client name. + +def _bounded_stack(caller_entries, own: str) -> str: + """Append our own entry and bound the result, dropping WHOLE entries. + + Two rules, and the second is the one that was wrong. Neither cap cuts + characters: a blunt slice severs an identifier and leaves a fragment that + parses as a real client name. And the reserved slot is OURS. Appending first + and then trimming to four dropped exactly the entry this function exists to + add, every time a caller already sent four, so the SDK vanished from its own + stack while the caller's claims all survived. """ - out = [] - for entry in list(entries)[:4]: - candidate = ", ".join(out + [entry]) - if len(candidate) > 200: + kept = [] + budget = MAX_STACK_CHARS - len(own) + for entry in list(caller_entries)[: MAX_STACK_ENTRIES - 1]: + cost = len(entry) + len(", ") + if cost > budget: break - out.append(entry) - return ", ".join(out) + budget -= cost + kept.append(entry) + return ", ".join(kept + [own]) def _client_headers(api_key: str, user_id: str) -> Dict[str, str]: From df4b88685b6d958d577f0247488f6ff3c880ec7f Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Thu, 17 Sep 2026 19:40:17 +0530 Subject: [PATCH 28/30] fix(client): repair the missed _bounded_stack call site, and test that a client constructs Reported as a blocker by an independent re-review, and correctly: the previous commit changed _bounded_stack to take the caller's entries and our own entry separately, updated _apply_client_headers, and missed _client_stack. That runs on every construction path, so every MemoryClient(...) raised TypeError. A total SDK outage, introduced by the fix for a cosmetic truncation bug. The whole suite stayed green because nothing constructed a client. That is the actual defect here, so the test file exists as much for the gap as for the bug: it builds a client, asserts the header reaches it, and covers the two bounding rules directly. Confirmed it fails against the broken call site and passes against the repaired one. AsyncMemoryClient is deliberately not constructed: its validation path makes a real request to /v1/ping/, and a unit test needing the network is worse than none. It shares _client_headers with the sync client, which is what the construction test guards. tests/test_client_surface_headers.py 5 passed, plugin suites 312 passed 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- mem0/client/main.py | 4 +- tests/test_client_surface_headers.py | 65 ++++++++++++++++++++++++++++ 2 files changed, 66 insertions(+), 3 deletions(-) create mode 100644 tests/test_client_surface_headers.py diff --git a/mem0/client/main.py b/mem0/client/main.py index 65f2212b0..3a82d9e5a 100644 --- a/mem0/client/main.py +++ b/mem0/client/main.py @@ -164,10 +164,8 @@ def _client_headers(api_key: str, user_id: str) -> Dict[str, str]: def _client_stack() -> str: """This SDK appended to any stack an outer layer already declared.""" existing = os.getenv("MEM0_CLIENT_STACK", "").strip() - mine = f"mem0-python/{_sdk_version()}" entries = [part.strip() for part in existing.split(",") if part.strip()] if existing else [] - entries.append(mine) - return _bounded_stack(entries) + return _bounded_stack(entries, f"mem0-python/{_sdk_version()}") class MemoryClient: diff --git a/tests/test_client_surface_headers.py b/tests/test_client_surface_headers.py new file mode 100644 index 000000000..a2602a5bc --- /dev/null +++ b/tests/test_client_surface_headers.py @@ -0,0 +1,65 @@ +"""Surface-identity headers, and that a client can be constructed at all. + +The construction test exists because it was not there: a signature change to +_bounded_stack missed the _client_stack call site, every MemoryClient(...) raised +TypeError, and the whole suite stayed green because nothing built one. +""" + +import os +from unittest.mock import patch + +import pytest + +from mem0.client.main import _bounded_stack, _client_headers, _client_stack + + +def test_a_client_can_be_constructed(): + from mem0 import MemoryClient + + # _validate_api_key normally populates org/project from the API response; + # stubbing it leaves them None, which a later accessor rejects. Set them the + # way a real validation would. This test is about construction reaching the + # header stage at all. + def _stub(self): + self.org_id, self.project_id = "org", "proj" + + with patch.object(MemoryClient, "_validate_api_key", _stub): + client = MemoryClient(api_key="m0-test") + + assert client.client.headers["X-Mem0-Client"].startswith("mem0-python/") + + +# AsyncMemoryClient is deliberately not constructed here: its validation path +# makes a real request to /v1/ping/, and a unit test that needs the network is +# worse than none. It shares _client_headers with the sync client, which is the +# code the construction test above actually guards. +def test_headers_carry_this_sdk(): + headers = _client_headers("m0-test", "u1") + assert headers["X-Mem0-Client"].startswith("mem0-python/") + + +def test_our_entry_survives_a_caller_that_already_filled_the_stack(): + # Appending first and trimming to four dropped exactly the entry the + # function exists to add. + stack = _bounded_stack(["a/1", "b/2", "c/3", "d/4"], "mem0-python/9.9.9") + + assert "mem0-python/9.9.9" in stack + assert len(stack.split(",")) <= 4 + + +def test_the_character_cap_drops_whole_entries_not_characters(): + long_entries = [f"{'n' * 90}/1.0", f"{'m' * 90}/1.0", "c/3"] + stack = _bounded_stack(long_entries, "mem0-python/9.9.9") + + assert len(stack) <= 200 + assert stack.endswith("mem0-python/9.9.9") + for entry in stack.split(","): + assert entry.strip().count("/") == 1, f"severed entry: {entry!r}" + + +def test_an_outer_stack_is_appended_to_not_replaced(): + with patch.dict(os.environ, {"MEM0_CLIENT_STACK": "openclaw/2.1.0"}): + stack = _client_stack() + + assert stack.startswith("openclaw/2.1.0") + assert "mem0-python/" in stack From afc3d02a805613e0f0535a755d37b22dab97d8c2 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Thu, 17 Sep 2026 19:44:14 +0530 Subject: [PATCH 29/30] fix(plugins): sweep temp files a killed process left behind Review finding, and the adjacent case to the one this PR already fixed. _sweep_debris collects *.partial and *.corrupt; _write_identity and _install_salt both create telemetry-*..tmp and unlink it in a finally, which a SIGKILL skips. Its own docstring reasoning, that no glob in the module matches them so nothing else ever will, applies equally. Collected on the stale window rather than the expiry window: unlike a quarantined batch a temp file carries nothing worth keeping for diagnosis. 276 passed, 8 skipped. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- integrations/agent-plugin-core/python/telemetry.py | 9 +++++++++ .../agent-plugin-core/tests/test_spool_delivery.py | 14 ++++++++++++++ integrations/antigravity-plugin/core/telemetry.py | 9 +++++++++ integrations/claude-code-plugin/core/telemetry.py | 9 +++++++++ integrations/codex-plugin/core/telemetry.py | 9 +++++++++ integrations/cursor-plugin/core/telemetry.py | 9 +++++++++ integrations/kimi-plugin/core/telemetry.py | 9 +++++++++ integrations/mem0-agent-plugin/core/telemetry.py | 9 +++++++++ 8 files changed, 77 insertions(+) diff --git a/integrations/agent-plugin-core/python/telemetry.py b/integrations/agent-plugin-core/python/telemetry.py index 9084c8a24..a4375f002 100644 --- a/integrations/agent-plugin-core/python/telemetry.py +++ b/integrations/agent-plugin-core/python/telemetry.py @@ -486,6 +486,15 @@ def _sweep_debris(directory: Path) -> None: quarantined.unlink() except OSError: continue + # The same reasoning covers *.tmp. _write_identity and _install_salt both + # create one and unlink it in a finally, which a SIGKILL skips, and no glob + # in this module matches the leftovers either. + for temporary in directory.glob("telemetry-*.tmp"): + try: + if now - temporary.stat().st_mtime > CLAIM_STALE_SECONDS: + temporary.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/agent-plugin-core/tests/test_spool_delivery.py b/integrations/agent-plugin-core/tests/test_spool_delivery.py index 03434177a..accd631a6 100644 --- a/integrations/agent-plugin-core/tests/test_spool_delivery.py +++ b/integrations/agent-plugin-core/tests/test_spool_delivery.py @@ -430,3 +430,17 @@ def test_quarantined_batches_are_eventually_collected(telemetry): assert fresh.exists(), "a recent quarantine was discarded before anyone could look at it" assert not old.exists(), "an expired quarantine was left on disk forever" + + +def test_temp_files_orphaned_by_a_kill_are_collected(telemetry): + """_write_identity and _install_salt unlink in a finally, which SIGKILL skips.""" + directory = telemetry.memory_core.data_dir() + directory.mkdir(parents=True, exist_ok=True) + orphan = directory / "telemetry-salt.999.tmp" + orphan.write_text("abandoned", encoding="utf-8") + stale = time.time() - (telemetry.CLAIM_STALE_SECONDS + 60) + os.utime(orphan, (stale, stale)) + + telemetry._sweep_debris(directory) + + assert not orphan.exists(), "a killed process left a temp file on disk forever" diff --git a/integrations/antigravity-plugin/core/telemetry.py b/integrations/antigravity-plugin/core/telemetry.py index 9084c8a24..a4375f002 100644 --- a/integrations/antigravity-plugin/core/telemetry.py +++ b/integrations/antigravity-plugin/core/telemetry.py @@ -486,6 +486,15 @@ def _sweep_debris(directory: Path) -> None: quarantined.unlink() except OSError: continue + # The same reasoning covers *.tmp. _write_identity and _install_salt both + # create one and unlink it in a finally, which a SIGKILL skips, and no glob + # in this module matches the leftovers either. + for temporary in directory.glob("telemetry-*.tmp"): + try: + if now - temporary.stat().st_mtime > CLAIM_STALE_SECONDS: + temporary.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/claude-code-plugin/core/telemetry.py b/integrations/claude-code-plugin/core/telemetry.py index 9084c8a24..a4375f002 100644 --- a/integrations/claude-code-plugin/core/telemetry.py +++ b/integrations/claude-code-plugin/core/telemetry.py @@ -486,6 +486,15 @@ def _sweep_debris(directory: Path) -> None: quarantined.unlink() except OSError: continue + # The same reasoning covers *.tmp. _write_identity and _install_salt both + # create one and unlink it in a finally, which a SIGKILL skips, and no glob + # in this module matches the leftovers either. + for temporary in directory.glob("telemetry-*.tmp"): + try: + if now - temporary.stat().st_mtime > CLAIM_STALE_SECONDS: + temporary.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/codex-plugin/core/telemetry.py b/integrations/codex-plugin/core/telemetry.py index 9084c8a24..a4375f002 100644 --- a/integrations/codex-plugin/core/telemetry.py +++ b/integrations/codex-plugin/core/telemetry.py @@ -486,6 +486,15 @@ def _sweep_debris(directory: Path) -> None: quarantined.unlink() except OSError: continue + # The same reasoning covers *.tmp. _write_identity and _install_salt both + # create one and unlink it in a finally, which a SIGKILL skips, and no glob + # in this module matches the leftovers either. + for temporary in directory.glob("telemetry-*.tmp"): + try: + if now - temporary.stat().st_mtime > CLAIM_STALE_SECONDS: + temporary.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/cursor-plugin/core/telemetry.py b/integrations/cursor-plugin/core/telemetry.py index 9084c8a24..a4375f002 100644 --- a/integrations/cursor-plugin/core/telemetry.py +++ b/integrations/cursor-plugin/core/telemetry.py @@ -486,6 +486,15 @@ def _sweep_debris(directory: Path) -> None: quarantined.unlink() except OSError: continue + # The same reasoning covers *.tmp. _write_identity and _install_salt both + # create one and unlink it in a finally, which a SIGKILL skips, and no glob + # in this module matches the leftovers either. + for temporary in directory.glob("telemetry-*.tmp"): + try: + if now - temporary.stat().st_mtime > CLAIM_STALE_SECONDS: + temporary.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/kimi-plugin/core/telemetry.py b/integrations/kimi-plugin/core/telemetry.py index 9084c8a24..a4375f002 100644 --- a/integrations/kimi-plugin/core/telemetry.py +++ b/integrations/kimi-plugin/core/telemetry.py @@ -486,6 +486,15 @@ def _sweep_debris(directory: Path) -> None: quarantined.unlink() except OSError: continue + # The same reasoning covers *.tmp. _write_identity and _install_salt both + # create one and unlink it in a finally, which a SIGKILL skips, and no glob + # in this module matches the leftovers either. + for temporary in directory.glob("telemetry-*.tmp"): + try: + if now - temporary.stat().st_mtime > CLAIM_STALE_SECONDS: + temporary.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: diff --git a/integrations/mem0-agent-plugin/core/telemetry.py b/integrations/mem0-agent-plugin/core/telemetry.py index 9084c8a24..a4375f002 100644 --- a/integrations/mem0-agent-plugin/core/telemetry.py +++ b/integrations/mem0-agent-plugin/core/telemetry.py @@ -486,6 +486,15 @@ def _sweep_debris(directory: Path) -> None: quarantined.unlink() except OSError: continue + # The same reasoning covers *.tmp. _write_identity and _install_salt both + # create one and unlink it in a finally, which a SIGKILL skips, and no glob + # in this module matches the leftovers either. + for temporary in directory.glob("telemetry-*.tmp"): + try: + if now - temporary.stat().st_mtime > CLAIM_STALE_SECONDS: + temporary.unlink() + except OSError: + continue def _claim_parked(directory: Path) -> Path | None: From 6aa1f6050337d194c167e11d040b4892913e5290 Mon Sep 17 00:00:00 2001 From: Saket Aryan Date: Thu, 17 Sep 2026 19:55:17 +0530 Subject: [PATCH 30/30] fix(client): drop the unused import CI's lint caught Left behind when the async construction test was removed. ruff check now passes on mem0/ and tests/. Claude-Session: https://claude.ai/code/session_01C7tEmH86HAr7GoAAKCEHZb --- tests/test_client_surface_headers.py | 2 -- 1 file changed, 2 deletions(-) diff --git a/tests/test_client_surface_headers.py b/tests/test_client_surface_headers.py index a2602a5bc..51d09d306 100644 --- a/tests/test_client_surface_headers.py +++ b/tests/test_client_surface_headers.py @@ -8,8 +8,6 @@ TypeError, and the whole suite stayed green because nothing built one. import os from unittest.mock import patch -import pytest - from mem0.client.main import _bounded_stack, _client_headers, _client_stack