Solution for long term memory for agent coding CLIs and to facilitate handoff between different agent vendors
Rust
feat(relay): queue external lifecycle events across restarts
Éverton Toffanetto410cbf0d1360
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.ymlindex 2d10a901..8e0033cb 100644--- a/.github/workflows/ci.yml+++ b/.github/workflows/ci.yml@@ -71,6 +71,18 @@ jobs:if: matrix.os == 'ubuntu-latest'run: echo "TAILWIND_BUILD=1" >> "$GITHUB_ENV"- run: cargo test --workspace --all-targets+ - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0+ with:+ enable-cache: false+ - name: Build the external lifecycle relay+ env:+ CARGO_TARGET_DIR: ${{ github.workspace }}/target+ run: cargo build --locked --manifest-path companions/ai-memory-relay/Cargo.toml+ - name: External lifecycle delivery against the real server+ run: >+ uv run --no-project python tests/e2e/external_relay_smoke.py+ --ai-memory-bin "${{ github.workspace }}/target/debug/ai-memory"+ --relay-bin "${{ github.workspace }}/target/debug/ai-memory-relay"- name: Vendored tailwind.css is currentif: matrix.os == 'ubuntu-latest'run: git diff --exit-code -- crates/ai-memory-web/static/tailwind.css@@ -84,13 +96,13 @@ jobs:# Add the `windows` label to a pull request that touches path handling,# file locking, or git plumbing.- # The companion importer is deliberately outside the root workspace- # (its own [workspace] in companions/ai-memory-importer/Cargo.toml), so- # none of the jobs above compile it. Gate it here with the same- # fmt/clippy/test trio docs/companion-crates.md prescribes, or a- # toolchain bump / convention change rots it silently.+ # Companions have their own workspaces and need separate checks.companions:- name: companions (ai-memory-importer)+ name: companions (${{ matrix.companion }})+ strategy:+ fail-fast: false+ matrix:+ companion: [ai-memory-importer, ai-memory-relay]runs-on: ubuntu-lateststeps:- uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1@@ -99,10 +111,10 @@ jobs:components: rustfmt, clippy- uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2with:- workspaces: companions/ai-memory-importer- - run: cargo fmt --check --manifest-path companions/ai-memory-importer/Cargo.toml- - run: cargo clippy --manifest-path companions/ai-memory-importer/Cargo.toml --all-targets -- -D warnings- - run: cargo test --manifest-path companions/ai-memory-importer/Cargo.toml+ workspaces: companions/${{ matrix.companion }}+ - run: cargo fmt --check --manifest-path companions/${{ matrix.companion }}/Cargo.toml+ - run: cargo clippy --locked --manifest-path companions/${{ matrix.companion }}/Cargo.toml --all-targets -- -D warnings+ - run: cargo test --locked --manifest-path companions/${{ matrix.companion }}/Cargo.toml# Build the release binary on its own so a release-only failure# (LTO crash, codegen issue, dead-code-with-debug-assertions) doesn't@@ -266,6 +278,12 @@ jobs:log-level: warncommand: checkarguments: --all-features+ - name: Relay dependency policy+ uses: EmbarkStudios/cargo-deny-action@3c6349835b2b7b196a839186cb8b78e02f7b5f25 # v2+ with:+ log-level: warn+ command: check+ arguments: --manifest-path companions/ai-memory-relay/Cargo.toml --all-featuresaudit:name: cargo-audit@@ -281,6 +299,7 @@ jobs:--ignore RUSTSEC-2024-0320--ignore RUSTSEC-2026-0194--ignore RUSTSEC-2026-0195+ - run: cargo audit --file companions/ai-memory-relay/Cargo.lockgitleaks:name: gitleaks (secret scan)diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.ymlindex b56ecc9d..f089ebe1 100644--- a/.github/workflows/windows.yml+++ b/.github/workflows/windows.yml@@ -66,3 +66,24 @@ jobs:- uses: dtolnay/rust-toolchain@4cda84d5c5c54efe2404f9d843567869ab1699d4 # stable- uses: Swatinem/rust-cache@f0d9c3887740aee45f6153b24b3a6b815192ec16 # v2- run: cargo test --workspace --all-targets+ - name: Check the external lifecycle relay+ env:+ CARGO_TARGET_DIR: ${{ github.workspace }}/target+ run: |+ cargo fmt --check --manifest-path companions/ai-memory-relay/Cargo.toml+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }+ cargo clippy --locked --manifest-path companions/ai-memory-relay/Cargo.toml --all-targets -- -D warnings+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }+ cargo test --locked --manifest-path companions/ai-memory-relay/Cargo.toml+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }+ cargo build --locked --manifest-path companions/ai-memory-relay/Cargo.toml+ if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE }+ - uses: astral-sh/setup-uv@bec219d24cd3e171d82865faccec33120bb574f4 # v10.1.0+ with:+ enable-cache: false+ - name: External lifecycle delivery against the real server+ run: >+ uv run --no-project python tests/e2e/external_relay_smoke.py+ --ai-memory-bin "${{ github.workspace }}/target/debug/ai-memory.exe"+ --relay-bin "${{ github.workspace }}/target/debug/ai-memory-relay.exe"+ --timeout-seconds 120diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 596ad74e..085d67ed 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -8,6 +8,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0## [Unreleased]### Added+- Added the optional `ai-memory-relay` companion for external lifecycle events.+ It queues events locally and sends ordered batches through the public hook API,+ using stable event identities for retries. The package has its own workspace+ and does not change the server's capture or storage defaults. (#821)- Added per-execution `AI_MEMORY_CAPTURE_OWNER` context for external lifecycleproducers. Updated native hooks, script bundles and generated integrationssuppress capture while preserving supported handoff delivery and MCP recall.diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 3d00d76f..02f2abb8 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -87,6 +87,11 @@ then use their own repositories without inheriting the checkout being pushed.The publishing Git process and other hook code retain their configuration.Run the installer again to update an existing installation.+Companions have separate Cargo workspaces. Check each changed companion with+`cargo fmt`, `cargo clippy --all-targets -- -D warnings`, and `cargo test`, passing+its `--manifest-path`. Changes to the lifecycle relay also need the real-server+test documented in [its README](companions/ai-memory-relay/README.md#validation).+Integration tests live in `tests/suite/` per crate and compile into thecrate's own test harness (declare a new file with `mod name;` in`tests/suite/mod.rs`); only the CLI keeps a separate test binary, because itsdiff --git a/README.md b/README.mdindex e40fd2d6..7a071320 100644--- a/README.md+++ b/README.md@@ -411,7 +411,7 @@ diagram, crate breakdown, schema notes, and invariants.| [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) | Operational summary: data flow, crate layout, cross-cutting invariants, schema. || [`docs/design-decisions.md`](docs/design-decisions.md) | The full v1 spec. || [`docs/managed-harness-contributions.md`](docs/managed-harness-contributions.md) | Protocol and acceptance bar for adding managed resume, transcript import, and startup context delivery to another harness. |-| [`docs/companion-crates.md`](docs/companion-crates.md) | Boundary and plan for optional companion projects, including the standalone importer at [`companions/ai-memory-importer`](companions/ai-memory-importer). |+| [`docs/companion-crates.md`](docs/companion-crates.md) | Optional companion projects: the [importer](companions/ai-memory-importer) and [external lifecycle relay](companions/ai-memory-relay). || [`docs/external-lifecycle.md`](docs/external-lifecycle.md) | External lifecycle producers: per-execution native capture suppression, preserved handoffs, batch ingestion and stable retry identity. || [`docs/auto-improvement-loop.md`](docs/auto-improvement-loop.md) | Auto-improvement design notes: scheduled review, auto-approval default, manual review opt-in, pending proposal storage, and curator work. |diff --git a/companions/ai-memory-relay/Cargo.lock b/companions/ai-memory-relay/Cargo.locknew file mode 100644index 00000000..13ea88d2--- /dev/null+++ b/companions/ai-memory-relay/Cargo.lock@@ -0,0 +1,1717 @@+# This file is automatically @generated by Cargo.+# It is not intended for manual editing.+version = 4++[[package]]+name = "ahash"+version = "0.8.12"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"+dependencies = [+ "cfg-if",+ "once_cell",+ "version_check",+ "zerocopy",+]++[[package]]+name = "ai-memory-relay"+version = "0.1.0"+dependencies = [+ "anyhow",+ "clap",+ "fs2",+ "reqwest",+ "rusqlite",+ "serde",+ "serde_json",+ "sha2",+ "tempfile",+ "url",+]++[[package]]+name = "anstream"+version = "1.0.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "824a212faf96e9acacdbd09febd34438f8f711fb84e09a8916013cd7815ca28d"+dependencies = [+ "anstyle",+ "anstyle-parse",+ "anstyle-query",+ "anstyle-wincon",+ "colorchoice",+ "is_terminal_polyfill",+ "utf8parse",+]++[[package]]+name = "anstyle"+version = "1.0.14"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000"++[[package]]+name = "anstyle-parse"+version = "1.0.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "52ce7f38b242319f7cabaa6813055467063ecdc9d355bbb4ce0c68908cd8130e"+dependencies = [+ "utf8parse",+]++[[package]]+name = "anstyle-query"+version = "1.1.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "40c48f72fd53cd289104fc64099abca73db4166ad86ea0b4341abe65af83dadc"+dependencies = [+ "windows-sys 0.61.2",+]++[[package]]+name = "anstyle-wincon"+version = "3.0.11"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "291e6a250ff86cd4a820112fb8898808a366d8f9f58ce16d1f538353ad55747d"+dependencies = [+ "anstyle",+ "once_cell_polyfill",+ "windows-sys 0.61.2",+]++[[package]]+name = "anyhow"+version = "1.0.104"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"++[[package]]+name = "atomic-waker"+version = "1.1.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1505bd5d3d116872e7271a6d4e16d81d0c8570876c8de68093a09ac269d8aac0"++[[package]]+name = "base64"+version = "0.22.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"++[[package]]+name = "bitflags"+version = "2.13.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"++[[package]]+name = "block-buffer"+version = "0.10.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"+dependencies = [+ "generic-array",+]++[[package]]+name = "bumpalo"+version = "3.20.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "72f5acc6cb2ba439de613abc23857ec3d78374d8ed5ac84e9d11336e87da8649"++[[package]]+name = "bytes"+version = "1.12.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"++[[package]]+name = "cc"+version = "1.4.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "54413ede23c2daf518f35156dfde027feb2374004d63bd497f983c8db9c0e313"+dependencies = [+ "find-msvc-tools",+ "shlex",+]++[[package]]+name = "cfg-if"+version = "1.0.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4e7648175b45a9a48536d676f68d918270699102aa8dab5496df06904c914600"++[[package]]+name = "cfg_aliases"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f079e83a288787bcd14a6aea84cee5c87a67c5a3e660c30f557a3d24761b3527"++[[package]]+name = "chacha20"+version = "0.10.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"+dependencies = [+ "cfg-if",+ "cpufeatures 0.3.1",+ "rand_core",+]++[[package]]+name = "clap"+version = "4.6.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "aa8876b300ab35ba921adea3dfd70157a46249b33f95c9084ae5709785478946"+dependencies = [+ "clap_builder",+ "clap_derive",+]++[[package]]+name = "clap_builder"+version = "4.6.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ec0797fb7aeb1406c84efac526901f7ec3ead2124f946b494e72879d4b54704d"+dependencies = [+ "anstream",+ "anstyle",+ "clap_lex",+ "strsim",+]++[[package]]+name = "clap_derive"+version = "4.6.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f9c751b79415d4e559e3d1fcf128e09e720eb673a06d26cf6f392d37d75b66e0"+dependencies = [+ "heck",+ "proc-macro2",+ "quote",+ "syn 3.0.6",+]++[[package]]+name = "clap_lex"+version = "1.1.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1c133bc6a41be0d194c306b5506d15e6feeea7b1d6604bd3f8310dfb2ca96486"++[[package]]+name = "colorchoice"+version = "1.0.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1d07550c9036bf2ae0c684c4297d503f838287c83c53686d05370d0e139ae570"++[[package]]+name = "core-foundation"+version = "0.10.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b2a6cd9ae233e7f62ba4e9353e81a88df7fc8a5987b8d445b4d90c879bd156f6"+dependencies = [+ "core-foundation-sys",+ "libc",+]++[[package]]+name = "core-foundation-sys"+version = "0.8.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"++[[package]]+name = "cpufeatures"+version = "0.2.17"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"+dependencies = [+ "libc",+]++[[package]]+name = "cpufeatures"+version = "0.3.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5ca28b0ae3115b884660db4118d803791fd6756b6e88f39c0f3f7859060d7566"+dependencies = [+ "libc",+]++[[package]]+name = "crypto-common"+version = "0.1.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"+dependencies = [+ "generic-array",+ "typenum",+]++[[package]]+name = "digest"+version = "0.10.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"+dependencies = [+ "block-buffer",+ "crypto-common",+]++[[package]]+name = "displaydoc"+version = "0.2.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c6232dd377dcc64799954cbd3a9bb882e9cdc1308ccd87b1c098f1fb2eaf82a8"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.6",+]++[[package]]+name = "errno"+version = "0.3.14"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"+dependencies = [+ "libc",+ "windows-sys 0.61.2",+]++[[package]]+name = "fallible-iterator"+version = "0.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2acce4a10f12dc2fb14a218589d4f1f62ef011b2d0cc4b3cb1bba8e94da14649"++[[package]]+name = "fallible-streaming-iterator"+version = "0.1.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7360491ce676a36bf9bb3c56c1aa791658183a54d2744120f27285738d90465a"++[[package]]+name = "fastrand"+version = "2.5.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "da7c62ceae207dd37ea5b845da6a0696c799f85e97da1ab5b7910be3c1c80223"++[[package]]+name = "find-msvc-tools"+version = "0.1.13"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ef25905e51abafe4dcea6c15fec58c57b601cdbd0ee53d22ea1d3016c587d39b"++[[package]]+name = "form_urlencoded"+version = "1.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cb4cb245038516f5f85277875cdaa4f7d2c9a0fa0468de06ed190163b1581fcf"+dependencies = [+ "percent-encoding",+]++[[package]]+name = "fs2"+version = "0.4.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9564fc758e15025b46aa6643b1b77d047d1a56a1aea6e01002ac0c7026876213"+dependencies = [+ "libc",+ "winapi",+]++[[package]]+name = "futures-channel"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b1f9e3d69d39e4862ffed03ed071a76f9a13ba1d9109d355b0f0aa6b15e393c4"+dependencies = [+ "futures-core",+ "futures-sink",+]++[[package]]+name = "futures-core"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "92d699e522242e69e3003b94ecc1f960f3a5e015aa7c5d7486e65ad01dd94f5e"++[[package]]+name = "futures-io"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "53c0fa8157de1303bfffdaa1cc2a673bfffb60102f76b0ef4441659124373fed"++[[package]]+name = "futures-sink"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1944426bf7d03f1d14f708785e4b33efd750b36d48a157b836b3efc15ede8e1d"++[[package]]+name = "futures-task"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cd417de3d1d015fc3bfd2b1ea46dfc7bab72ef86f1cc7cc9c78e728b34a6d1fd"++[[package]]+name = "futures-util"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0d50a92467f8ba5dd6e3ee5d4bd04d73ab2e4e1c44474a0674821dfce14b79bc"+dependencies = [+ "futures-core",+ "futures-io",+ "futures-sink",+ "futures-task",+ "memchr",+ "pin-project-lite",+ "slab",+]++[[package]]+name = "generic-array"+version = "0.14.7"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"+dependencies = [+ "typenum",+ "version_check",+]++[[package]]+name = "getrandom"+version = "0.2.17"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ff2abc00be7fca6ebc474524697ae276ad847ad0a6b3faa4bcb027e9a4614ad0"+dependencies = [+ "cfg-if",+ "js-sys",+ "libc",+ "wasi",+ "wasm-bindgen",+]++[[package]]+name = "getrandom"+version = "0.4.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "300e883d756b2e4ec94e02791f39b04b522276138852cfc41d9fb7e904106099"+dependencies = [+ "cfg-if",+ "js-sys",+ "libc",+ "r-efi",+ "rand_core",+ "wasm-bindgen",+]++[[package]]+name = "hashbrown"+version = "0.14.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"+dependencies = [+ "ahash",+]++[[package]]+name = "hashlink"+version = "0.9.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af"+dependencies = [+ "hashbrown",+]++[[package]]+name = "heck"+version = "0.5.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"++[[package]]+name = "http"+version = "1.5.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "918d3568bebf352712bc2ef3d46a8bcf1a75b373be6539de198e9105cbbf9ce0"+dependencies = [+ "bytes",+ "itoa",+]++[[package]]+name = "http-body"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ca2a8f2913ee65f60facd6a5905613afaa448497a0230cc41ce022d93290bc2c"+dependencies = [+ "bytes",+ "http",+]++[[package]]+name = "http-body-util"+version = "0.1.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "23169fe34a5fbcdd3f3862e78fb9b6fccd5f02a6dc6f732547005d45631ce71c"+dependencies = [+ "bytes",+ "futures-core",+ "http",+ "http-body",+ "pin-project-lite",+]++[[package]]+name = "httparse"+version = "1.10.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6dbf3de79e51f3d586ab4cb9d5c3e2c14aa28ed23d180cf89b4df0454a69cc87"++[[package]]+name = "hyper"+version = "1.11.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "27b501faa50e7a26c3d3560ca625132f4078a17771f4810baf70475ae48cbe43"+dependencies = [+ "atomic-waker",+ "bytes",+ "futures-channel",+ "futures-core",+ "http",+ "http-body",+ "httparse",+ "itoa",+ "pin-project-lite",+ "smallvec",+ "tokio",+ "want",+]++[[package]]+name = "hyper-rustls"+version = "0.27.10"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "dfa8e654703247911e29c23fbeaa261834bd9bb74efba2f9acddc37bfb127f53"+dependencies = [+ "http",+ "hyper",+ "hyper-util",+ "rustls",+ "rustls-native-certs",+ "tokio",+ "tokio-rustls",+ "tower-service",+]++[[package]]+name = "hyper-util"+version = "0.1.20"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "96547c2556ec9d12fb1578c4eaf448b04993e7fb79cbaad930a656880a6bdfa0"+dependencies = [+ "base64",+ "bytes",+ "futures-channel",+ "futures-util",+ "http",+ "http-body",+ "hyper",+ "ipnet",+ "libc",+ "percent-encoding",+ "pin-project-lite",+ "socket2",+ "tokio",+ "tower-service",+ "tracing",+]++[[package]]+name = "icu_collections"+version = "2.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "fa68d21081c4a05d5a901a1c62add574c77048b6a1c67be3b50ce0b60d4ca513"+dependencies = [+ "displaydoc",+ "potential_utf",+ "utf8_iter",+ "yoke",+ "zerofrom",+ "zerovec",+]++[[package]]+name = "icu_locale_core"+version = "2.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d56e28588da92eee5c3201a6eff33fabdd49b62269c8938d4ff050ce4d900deb"+dependencies = [+ "displaydoc",+ "litemap",+ "tinystr",+ "writeable",+ "zerovec",+]++[[package]]+name = "icu_normalizer"+version = "2.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "12f9cf5f235641ed274641dd81c3f28d870e276763d0797aeeab72317b1c646f"+dependencies = [+ "icu_collections",+ "icu_normalizer_data",+ "icu_properties",+ "icu_provider",+ "smallvec",+ "zerovec",+]++[[package]]+name = "icu_normalizer_data"+version = "2.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1563da1ed3e0b3bf3d74c9b85917ac9c56464d2f57242270c09c9e752f8021a0"++[[package]]+name = "icu_properties"+version = "2.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7e7ca276ad3145661a65914e6daf131ca5120cd3dcee8f8f3214b8875184a148"+dependencies = [+ "displaydoc",+ "icu_collections",+ "icu_locale_core",+ "icu_properties_data",+ "icu_provider",+ "zerotrie",+ "zerovec",+]++[[package]]+name = "icu_properties_data"+version = "2.3.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e590f038c1464a96894fd6d10127e90a8be4509f56ff7ecef851b15cee0b7caa"++[[package]]+name = "icu_provider"+version = "2.3.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d27bbb9d3abbefac45d55f647c9de1d44aafcd1186eb91879afef17c396c3e73"+dependencies = [+ "displaydoc",+ "icu_locale_core",+ "writeable",+ "yoke",+ "zerofrom",+ "zerotrie",+ "zerovec",+]++[[package]]+name = "idna"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3b0875f23caa03898994f6ddc501886a45c7d3d62d04d2d90788d47be1b1e4de"+dependencies = [+ "idna_adapter",+ "smallvec",+ "utf8_iter",+]++[[package]]+name = "idna_adapter"+version = "1.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cb68373c0d6620ef8105e855e7745e18b0d00d3bdb07fb532e434244cdb9a714"+dependencies = [+ "icu_normalizer",+ "icu_properties",+]++[[package]]+name = "ipnet"+version = "2.12.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "791930b43c0d5973160d90a8f3894509f2b273430f5c5c73b668636d0287c5c0"++[[package]]+name = "is_terminal_polyfill"+version = "1.70.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a6cb138bb79a146c1bd460005623e142ef0181e3d0219cb493e02f7d08a35695"++[[package]]+name = "itoa"+version = "1.0.18"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682"++[[package]]+name = "js-sys"+version = "0.3.105"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ce57d20d1ea864ce2ac172ab472d409214f4fd359f0b2a2775abdf522e2af99e"+dependencies = [+ "cfg-if",+ "futures-util",+ "wasm-bindgen",+]++[[package]]+name = "libc"+version = "0.2.189"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"++[[package]]+name = "libsqlite3-sys"+version = "0.30.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2e99fb7a497b1e3339bc746195567ed8d3e24945ecd636e3619d20b9de9e9149"+dependencies = [+ "cc",+ "pkg-config",+ "vcpkg",+]++[[package]]+name = "linux-raw-sys"+version = "0.12.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "32a66949e030da00e8c7d4434b251670a91556f4144941d37452769c25d58a53"++[[package]]+name = "litemap"+version = "0.8.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "47d9d19d1d6efa0109d2f65ff4c85cddd50bd572e5a00127ab10987290bcefae"++[[package]]+name = "log"+version = "0.4.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f9f8bd3e56ce4dfc153cf470fffbfa98c7620958b312ca5c3a4b8d5181fd13c6"++[[package]]+name = "lru-slab"+version = "0.1.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f"++[[package]]+name = "memchr"+version = "2.8.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cf8baf1c55e62ffcace7a9f06f4bd9cd3f0c4beb022d3b367256b91b87513d98"++[[package]]+name = "mio"+version = "1.2.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4b18443e9c262bfe8fa82f51666e2642c53393f7e5c27b3e1aeab922cff5b9d8"+dependencies = [+ "libc",+ "wasi",+ "windows-sys 0.61.2",+]++[[package]]+name = "once_cell"+version = "1.21.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"++[[package]]+name = "once_cell_polyfill"+version = "1.70.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "384b8ab6d37215f3c5301a95a4accb5d64aa607f1fcb26a11b5303878451b4fe"++[[package]]+name = "openssl-probe"+version = "0.2.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7c87def4c32ab89d880effc9e097653c8da5d6ef28e6b539d313baaacfbafcbe"++[[package]]+name = "percent-encoding"+version = "2.3.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9b4f627cb1b25917193a259e49bdad08f671f8d9708acfd5fe0a8c1455d87220"++[[package]]+name = "pin-project-lite"+version = "0.2.17"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd"++[[package]]+name = "pkg-config"+version = "0.3.34"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f6b464fbc74e149a392436b17d523f769e057cb6877f6a5c4618bc6f11800548"++[[package]]+name = "potential_utf"+version = "0.1.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d83eb9bc6d8e5cf568e7a1101d60ee05e81ed50ea106026f3d18deeb046d7661"+dependencies = [+ "zerovec",+]++[[package]]+name = "proc-macro2"+version = "1.0.107"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"+dependencies = [+ "unicode-ident",+]++[[package]]+name = "quinn"+version = "0.11.12"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4051e23e9185c255a7e33ef59cdbca87a22d359052eecd22fc6b901fb37d9d11"+dependencies = [+ "bytes",+ "cfg_aliases",+ "pin-project-lite",+ "quinn-proto",+ "quinn-udp",+ "rustc-hash",+ "rustls",+ "socket2",+ "thiserror",+ "tokio",+ "tracing",+ "web-time",+]++[[package]]+name = "quinn-proto"+version = "0.11.18"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a9746dbde176634f4f2f1faf2404e30a31b2bc1e9cafb5329c95d8177a18c9fc"+dependencies = [+ "bytes",+ "getrandom 0.4.3",+ "lru-slab",+ "rand",+ "rand_pcg",+ "ring",+ "rustc-hash",+ "rustls",+ "rustls-pki-types",+ "slab",+ "thiserror",+ "tinyvec",+ "tracing",+ "web-time",+]++[[package]]+name = "quinn-udp"+version = "0.5.15"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "35a133f956daabe89a61a685c2649f13d82d5aa4bd5d12d1277e1072a21c0694"+dependencies = [+ "cfg_aliases",+ "libc",+ "once_cell",+ "socket2",+ "tracing",+ "windows-sys 0.61.2",+]++[[package]]+name = "quote"+version = "1.0.47"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"+dependencies = [+ "proc-macro2",+]++[[package]]+name = "r-efi"+version = "6.0.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f8dcc9c7d52a811697d2151c701e0d08956f92b0e24136cf4cf27b57a6a0d9bf"++[[package]]+name = "rand"+version = "0.10.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "65c9fb96cbc91e3478eaae79a69fcd3f1ae4ad052e471fe6732fff548984b4af"+dependencies = [+ "chacha20",+ "getrandom 0.4.3",+ "rand_core",+]++[[package]]+name = "rand_core"+version = "0.10.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "63b8176103e19a2643978565ca18b50549f6101881c443590420e4dc998a3c69"++[[package]]+name = "rand_pcg"+version = "0.10.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "caa0f4137e1c0a72f4c651489402276c8e8e1cf081f3b0ba156d2cbeef09e86a"+dependencies = [+ "rand_core",+]++[[package]]+name = "reqwest"+version = "0.12.28"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "eddd3ca559203180a307f12d114c268abf583f59b03cb906fd0b3ff8646c1147"+dependencies = [+ "base64",+ "bytes",+ "futures-channel",+ "futures-core",+ "futures-util",+ "http",+ "http-body",+ "http-body-util",+ "hyper",+ "hyper-rustls",+ "hyper-util",+ "js-sys",+ "log",+ "percent-encoding",+ "pin-project-lite",+ "quinn",+ "rustls",+ "rustls-native-certs",+ "rustls-pki-types",+ "serde",+ "serde_json",+ "serde_urlencoded",+ "sync_wrapper",+ "tokio",+ "tokio-rustls",+ "tower",+ "tower-http",+ "tower-service",+ "url",+ "wasm-bindgen",+ "wasm-bindgen-futures",+ "web-sys",+]++[[package]]+name = "ring"+version = "0.17.14"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a4689e6c2294d81e88dc6261c768b63bc4fcdb852be6d1352498b114f61383b7"+dependencies = [+ "cc",+ "cfg-if",+ "getrandom 0.2.17",+ "libc",+ "untrusted",+ "windows-sys 0.52.0",+]++[[package]]+name = "rusqlite"+version = "0.32.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e"+dependencies = [+ "bitflags",+ "fallible-iterator",+ "fallible-streaming-iterator",+ "hashlink",+ "libsqlite3-sys",+ "smallvec",+]++[[package]]+name = "rustc-hash"+version = "2.1.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"++[[package]]+name = "rustix"+version = "1.1.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "891efababe418670775f199f0d233d84843c227a0949a883ce15b37c78d6629d"+dependencies = [+ "bitflags",+ "errno",+ "libc",+ "linux-raw-sys",+ "windows-sys 0.61.2",+]++[[package]]+name = "rustls"+version = "0.23.45"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0d41d731c7d2f962d1ccc364cec258de3c0e93b38c2fb3ba97ac74513048d634"+dependencies = [+ "once_cell",+ "ring",+ "rustls-pki-types",+ "rustls-webpki",+ "subtle",+ "zeroize",+]++[[package]]+name = "rustls-native-certs"+version = "0.8.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "dab5152771c58876a2146916e53e35057e1a4dfa2b9df0f0305b07f611fdea4d"+dependencies = [+ "openssl-probe",+ "rustls-pki-types",+ "schannel",+ "security-framework",+]++[[package]]+name = "rustls-pki-types"+version = "1.15.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "2f4925028c7eb5d1fcdaf196971378ed9d2c1c4efc7dc5d011256f76c99c0a96"+dependencies = [+ "web-time",+ "zeroize",+]++[[package]]+name = "rustls-webpki"+version = "0.103.15"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f3c3cf1d8b1e7d4927e2d154c3fcb02979afb9939629c62cd9048d4f07b60ac2"+dependencies = [+ "ring",+ "rustls-pki-types",+ "untrusted",+]++[[package]]+name = "rustversion"+version = "1.0.23"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "cf54715a573b99ac80df0bc206da022bcd442c974952c7b9720069370852e21f"++[[package]]+name = "ryu"+version = "1.0.23"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9774ba4a74de5f7b1c1451ed6cd5285a32eddb5cccb8cc655a4e50009e06477f"++[[package]]+name = "schannel"+version = "0.1.29"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "91c1b7e4904c873ef0710c1f407dde2e6287de2bebc1bbbf7d430bb7cbffd939"+dependencies = [+ "windows-sys 0.61.2",+]++[[package]]+name = "security-framework"+version = "3.7.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b7f4bc775c73d9a02cde8bf7b2ec4c9d12743edf609006c7facc23998404cd1d"+dependencies = [+ "bitflags",+ "core-foundation",+ "core-foundation-sys",+ "libc",+ "security-framework-sys",+]++[[package]]+name = "security-framework-sys"+version = "2.17.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6ce2691df843ecc5d231c0b14ece2acc3efb62c0a398c7e1d875f3983ce020e3"+dependencies = [+ "core-foundation-sys",+ "libc",+]++[[package]]+name = "serde"+version = "1.0.229"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4148590afebada386688f18773da617792bf2ef03ffc1e4cbd2b1d45b023e0ba"+dependencies = [+ "serde_core",+ "serde_derive",+]++[[package]]+name = "serde_core"+version = "1.0.229"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "67dca2c9c51e58a4791a4b1ed58308b39c64224d349a935ab5039aa360942a48"+dependencies = [+ "serde_derive",+]++[[package]]+name = "serde_derive"+version = "1.0.229"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e7a5d71263a5a7d47b41f6b3f06ba276f10cc18b0931f1799f710578e2309348"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.6",+]++[[package]]+name = "serde_json"+version = "1.0.151"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c841b55ecdae098c80dcae9cf767f6f8a0c2cdb3416bbef72181df4d0fe73f14"+dependencies = [+ "itoa",+ "memchr",+ "serde",+ "serde_core",+ "zmij",+]++[[package]]+name = "serde_urlencoded"+version = "0.7.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d3491c14715ca2294c4d6a88f15e84739788c1d030eed8c110436aafdaa2f3fd"+dependencies = [+ "form_urlencoded",+ "itoa",+ "ryu",+ "serde",+]++[[package]]+name = "sha2"+version = "0.10.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a7507d819769d01a365ab707794a4084392c824f54a7a6a7862f8c3d0892b283"+dependencies = [+ "cfg-if",+ "cpufeatures 0.2.17",+ "digest",+]++[[package]]+name = "shlex"+version = "2.0.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f8fadd59c855ef2080decdef8ff161eb6661b86933c9d82e5ba29dc602a55aba"++[[package]]+name = "slab"+version = "0.4.12"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0c790de23124f9ab44544d7ac05d60440adc586479ce501c1d6d7da3cd8c9cf5"++[[package]]+name = "smallvec"+version = "1.16.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ba467056f1b547ed52077911161fc86985becbc60e8e1857c8a144dab0def891"++[[package]]+name = "socket2"+version = "0.6.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "c3d1e2c7f27f8d4cb10542a02c49005dbd6e93095799d6f3be745fae9f8fedd4"+dependencies = [+ "libc",+ "windows-sys 0.61.2",+]++[[package]]+name = "stable_deref_trait"+version = "1.2.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6ce2be8dc25455e1f91df71bfa12ad37d7af1092ae736f3a6cd0e37bc7810596"++[[package]]+name = "strsim"+version = "0.11.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "7da8b5736845d9f2fcb837ea5d9e2628564b3b043a70948a3f0b778838c5fb4f"++[[package]]+name = "subtle"+version = "2.6.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "13c2bddecc57b384dee18652358fb23172facb8a2c51ccc10d74c157bdea3292"++[[package]]+name = "syn"+version = "2.0.119"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "872831b642d1a07999a962a351ed35b955ea2cfc8f3862091e2a240a84f17297"+dependencies = [+ "proc-macro2",+ "quote",+ "unicode-ident",+]++[[package]]+name = "syn"+version = "3.0.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8593e8e72159ed2257d083c7a454a85cbf854f37a0966d8d483aff8c8a3ebcee"+dependencies = [+ "proc-macro2",+ "quote",+ "unicode-ident",+]++[[package]]+name = "sync_wrapper"+version = "1.0.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0bf256ce5efdfa370213c1dabab5935a12e49f2c58d15e9eac2870d3b4f27263"+dependencies = [+ "futures-core",+]++[[package]]+name = "synstructure"+version = "0.14.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "901704edd0dfe137f1987838ee4f259e4e063c31371bdb423f7ae38ec6f77f02"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.6",+]++[[package]]+name = "tempfile"+version = "3.27.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "32497e9a4c7b38532efcdebeef879707aa9f794296a4f0244f6f69e9bc8574bd"+dependencies = [+ "fastrand",+ "getrandom 0.4.3",+ "once_cell",+ "rustix",+ "windows-sys 0.61.2",+]++[[package]]+name = "thiserror"+version = "2.0.20"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ec86235f5fcc2a73650310756d2ac5b138a5780bbbdfae3eeccec992c435ba4f"+dependencies = [+ "thiserror-impl",+]++[[package]]+name = "thiserror-impl"+version = "2.0.20"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "bc04cd3e1236dd4a98afca4569f2deb3f120e5422a4023be2cb683f8486292af"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.6",+]++[[package]]+name = "tinystr"+version = "0.8.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b1e27c91459209c2986af3dcf603a5a74a4368754ce37414f59acc971167f643"+dependencies = [+ "displaydoc",+ "zerovec",+]++[[package]]+name = "tinyvec"+version = "1.13.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "fd3ca314f692efd6c868f8408f53fe444634a845f96c028b97d35f6a1f79f0ee"++[[package]]+name = "tokio"+version = "1.53.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "202caea871b69668250d242070849eb495be178ed697a3e98aebce5bc81a0bed"+dependencies = [+ "bytes",+ "libc",+ "mio",+ "pin-project-lite",+ "socket2",+ "windows-sys 0.61.2",+]++[[package]]+name = "tokio-rustls"+version = "0.26.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b0c85f2c3ef0b1cd58b36682f4b17aaa995f0e5db534d85692b4903abce21f67"+dependencies = [+ "rustls",+ "tokio",+]++[[package]]+name = "tower"+version = "0.5.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ebe5ef63511595f1344e2d5cfa636d973292adc0eec1f0ad45fae9f0851ab1d4"+dependencies = [+ "futures-core",+ "futures-util",+ "pin-project-lite",+ "sync_wrapper",+ "tokio",+ "tower-layer",+ "tower-service",+]++[[package]]+name = "tower-http"+version = "0.6.11"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"+dependencies = [+ "bitflags",+ "bytes",+ "futures-util",+ "http",+ "http-body",+ "pin-project-lite",+ "tower",+ "tower-layer",+ "tower-service",+ "url",+]++[[package]]+name = "tower-layer"+version = "0.3.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "121c2a6cda46980bb0fcd1647ffaf6cd3fc79a013de288782836f6df9c48780e"++[[package]]+name = "tower-service"+version = "0.3.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8df9b6e13f2d32c91b9bd719c00d1958837bc7dec474d94952798cc8e69eeec3"++[[package]]+name = "tracing"+version = "0.1.44"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "63e71662fa4b2a2c3a26f570f037eb95bb1f85397f3cd8076caed2f026a6d100"+dependencies = [+ "pin-project-lite",+ "tracing-core",+]++[[package]]+name = "tracing-core"+version = "0.1.36"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "db97caf9d906fbde555dd62fa95ddba9eecfd14cb388e4f491a66d74cd5fb79a"+dependencies = [+ "once_cell",+]++[[package]]+name = "try-lock"+version = "0.2.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"++[[package]]+name = "typenum"+version = "1.20.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b6f5e870be6c3b371b77fe0ee0bafb859fa4964b4404c27de1d380043c4dda20"++[[package]]+name = "unicode-ident"+version = "1.0.26"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d245f478577f809a851594d02313b640fb437e0bb33866753cff937863096954"++[[package]]+name = "untrusted"+version = "0.9.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8ecb6da28b8a351d773b68d5825ac39017e680750f980f3a1a85cd8dd28a47c1"++[[package]]+name = "url"+version = "2.5.8"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ff67a8a4397373c3ef660812acab3268222035010ab8680ec4215f38ba3d0eed"+dependencies = [+ "form_urlencoded",+ "idna",+ "percent-encoding",+ "serde",+]++[[package]]+name = "utf8_iter"+version = "1.0.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "b6c140620e7ffbb22c2dee59cafe6084a59b5ffc27a8859a5f0d494b5d52b6be"++[[package]]+name = "utf8parse"+version = "0.2.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "06abde3611657adf66d383f00b093d7faecc7fa57071cce2578660c9f1010821"++[[package]]+name = "vcpkg"+version = "0.2.15"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"++[[package]]+name = "version_check"+version = "0.9.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"++[[package]]+name = "want"+version = "0.3.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "bfa7760aed19e106de2c7c0b581b509f2f25d3dacaf737cb82ac61bc6d760b0e"+dependencies = [+ "try-lock",+]++[[package]]+name = "wasi"+version = "0.11.1+wasi-snapshot-preview1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"++[[package]]+name = "wasm-bindgen"+version = "0.2.128"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "aecb87a33d3b0c5e3b7aa46336eaf486cffafbd281b195e4c8b80d50df2351bf"+dependencies = [+ "cfg-if",+ "once_cell",+ "rustversion",+ "wasm-bindgen-macro",+ "wasm-bindgen-shared",+]++[[package]]+name = "wasm-bindgen-futures"+version = "0.4.78"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "6ef4c5d3d2cdf5c54f4231181768f5510842e350db025faf1f7163b1030ed928"+dependencies = [+ "js-sys",+ "wasm-bindgen",+]++[[package]]+name = "wasm-bindgen-macro"+version = "0.2.128"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "a690d511e3c1a8b3a55e33511e3c2c00c78415cd23650f32b808627f5696b9ed"+dependencies = [+ "quote",+ "wasm-bindgen-macro-support",+]++[[package]]+name = "wasm-bindgen-macro-support"+version = "0.2.128"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "411e4887f0071ef2d2164a9d5fdf2d20efbef78fccd3a78b0c10a1dc5295e48a"+dependencies = [+ "bumpalo",+ "proc-macro2",+ "quote",+ "syn 3.0.6",+ "wasm-bindgen-shared",+]++[[package]]+name = "wasm-bindgen-shared"+version = "0.2.128"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "81941cd78d0c92026c33e5e01312845a4cb1e9af3407f9134b100dd03144103e"+dependencies = [+ "unicode-ident",+]++[[package]]+name = "web-sys"+version = "0.3.105"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9fbddc4a036f00ec4f18c83445bd3115cb306a91da554919a099d9222fe4a7f8"+dependencies = [+ "js-sys",+ "wasm-bindgen",+]++[[package]]+name = "web-time"+version = "1.1.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5a6580f308b1fad9207618087a65c04e7a10bc77e02c8e84e9b00dd4b12fa0bb"+dependencies = [+ "js-sys",+ "wasm-bindgen",+]++[[package]]+name = "winapi"+version = "0.3.9"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "5c839a674fcd7a98952e593242ea400abe93992746761e38641405d28b00f419"+dependencies = [+ "winapi-i686-pc-windows-gnu",+ "winapi-x86_64-pc-windows-gnu",+]++[[package]]+name = "winapi-i686-pc-windows-gnu"+version = "0.4.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ac3b87c63620426dd9b991e5ce0329eff545bccbbb34f3be09ff6fb6ab51b7b6"++[[package]]+name = "winapi-x86_64-pc-windows-gnu"+version = "0.4.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "712e227841d057c1ee1cd2fb22fa7e5a5461ae8e48fa2ca79ec42cfc1931183f"++[[package]]+name = "windows-link"+version = "0.2.1"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f0805222e57f7521d6a62e36fa9163bc891acd422f971defe97d64e70d0a4fe5"++[[package]]+name = "windows-sys"+version = "0.52.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"+dependencies = [+ "windows-targets",+]++[[package]]+name = "windows-sys"+version = "0.61.2"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "ae137229bcbd6cdf0f7b80a31df61766145077ddf49416a728b02cb3921ff3fc"+dependencies = [+ "windows-link",+]++[[package]]+name = "windows-targets"+version = "0.52.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"+dependencies = [+ "windows_aarch64_gnullvm",+ "windows_aarch64_msvc",+ "windows_i686_gnu",+ "windows_i686_gnullvm",+ "windows_i686_msvc",+ "windows_x86_64_gnu",+ "windows_x86_64_gnullvm",+ "windows_x86_64_msvc",+]++[[package]]+name = "windows_aarch64_gnullvm"+version = "0.52.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"++[[package]]+name = "windows_aarch64_msvc"+version = "0.52.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"++[[package]]+name = "windows_i686_gnu"+version = "0.52.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"++[[package]]+name = "windows_i686_gnullvm"+version = "0.52.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"++[[package]]+name = "windows_i686_msvc"+version = "0.52.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"++[[package]]+name = "windows_x86_64_gnu"+version = "0.52.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"++[[package]]+name = "windows_x86_64_gnullvm"+version = "0.52.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"++[[package]]+name = "windows_x86_64_msvc"+version = "0.52.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"++[[package]]+name = "writeable"+version = "0.6.4"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"++[[package]]+name = "yoke"+version = "0.8.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "709fe23a0424b6a435d82152b1bd3fdfb0833487d5fa90d05d42762a9891fef5"+dependencies = [+ "stable_deref_trait",+ "yoke-derive",+ "zerofrom",+]++[[package]]+name = "yoke-derive"+version = "0.8.3"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "33811428bee40dbceb6d545e95754741d17a6aef9a4849f0fd62e2ba4f412a78"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.6",+ "synstructure",+]++[[package]]+name = "zerocopy"+version = "0.8.57"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "d35102a9f36d089ccae9e4c6802bc118be4487b80aaffc0ab4e0cf5ce92d2873"+dependencies = [+ "zerocopy-derive",+]++[[package]]+name = "zerocopy-derive"+version = "0.8.57"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "146c01f5ab44258da43cf276c74a2763db2ff3969c9c652c3f2de07041d0b2bc"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 2.0.119",+]++[[package]]+name = "zerofrom"+version = "0.1.8"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "0ec05a11813ea801ff6d75110ad09cd0824ddba17dfe17128ea0d5f68e6c5272"+dependencies = [+ "zerofrom-derive",+]++[[package]]+name = "zerofrom-derive"+version = "0.1.8"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "f75b4683f6c7f45248d4d64056a24298c6281e0993356d7d1b4a1a962ef10d4a"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.6",+ "synstructure",+]++[[package]]+name = "zeroize"+version = "1.9.0"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"++[[package]]+name = "zerotrie"+version = "0.2.5"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "4ea269c3bd32f0a32c321907a2ae912ba6f4649bb0fc764a15627e99a7095a3f"+dependencies = [+ "displaydoc",+ "yoke",+ "zerofrom",+]++[[package]]+name = "zerovec"+version = "0.11.8"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "bb0464e17806c1d976d5cba29399c7f08e516e279e2ba493f63123b5fca67dd8"+dependencies = [+ "yoke",+ "zerofrom",+ "zerovec-derive",+]++[[package]]+name = "zerovec-derive"+version = "0.11.6"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "34df6fc39dbd26ddc9c10e6a2984476e13acce22e64e4487636ef494369225da"+dependencies = [+ "proc-macro2",+ "quote",+ "syn 3.0.6",+]++[[package]]+name = "zmij"+version = "1.0.23"+source = "registry+https://github.com/rust-lang/crates.io-index"+checksum = "29666d0abbfad1e3dc4dcf6144730dd3a3ab225bbbdac83319345b1b44ccfc1b"diff --git a/companions/ai-memory-relay/Cargo.toml b/companions/ai-memory-relay/Cargo.tomlnew file mode 100644index 00000000..8ae374d1--- /dev/null+++ b/companions/ai-memory-relay/Cargo.toml@@ -0,0 +1,38 @@+# Separate workspace, as described in docs/companion-crates.md.+[workspace]++[package]+name = "ai-memory-relay"+version = "0.1.0"+edition = "2024"+publish = false+license = "MIT"+description = "Persistent queue for external ai-memory lifecycle events"++[[bin]]+name = "ai-memory-relay"+path = "src/main.rs"++[lints.rust]+unsafe_code = "forbid"++[dependencies]+anyhow = "1"+# Read the bearer token separately to keep it out of clap's Debug output.+clap = { version = "4", features = ["derive"] }+fs2 = "0.4"+# Native roots match the workspace (#492).+reqwest = { version = "0.12", default-features = false, features = [+ "blocking",+ "json",+ "rustls-tls-native-roots",+] }+rusqlite = { version = "0.32", features = ["bundled"] }+serde = { version = "1", features = ["derive"] }+# Default map ordering makes content comparisons independent of input key order.+serde_json = "1"+sha2 = "0.10"+url = "2"++[dev-dependencies]+tempfile = "3"diff --git a/companions/ai-memory-relay/README.md b/companions/ai-memory-relay/README.mdnew file mode 100644index 00000000..9d9ec049--- /dev/null+++ b/companions/ai-memory-relay/README.md@@ -0,0 +1,215 @@+# ai-memory-relay++A companion CLI for sending externally captured lifecycle events to ai-memory.+It records events in a local SQLite queue and sends them through `POST /hook/batch`.+Use it when an orchestrator needs delivery to survive an unavailable server or a+process restart.++The relay has its own Cargo workspace. It does not open ai-memory's database or+wiki, launch agents, or claim handoffs. See the+[external lifecycle contract](../../docs/external-lifecycle.md) for capture+ownership and the [companion policy](../../docs/companion-crates.md) for the core+boundary.++## Build and use++From the repository root:++```sh+cargo build --locked --manifest-path companions/ai-memory-relay/Cargo.toml+```++The executable is `companions/ai-memory-relay/target/debug/ai-memory-relay`, unless+`CARGO_TARGET_DIR` selects another target directory. The commands below assume+the executable is on `PATH` and an ai-memory server is running.++Initialize a queue. Its parent directory must exist; the relay creates the queue+directory itself.++```sh+ai-memory-relay init \+ --queue-dir "$HOME/.ai-memory-relay" \+ --server-url http://127.0.0.1:49374 \+ --producer my-orchestrator \+ --actor developer \+ --workspace work \+ --project example+```++This binds the queue to one destination and scope. Repeating an identical `init`+is safe. A different binding is rejected. `actor` is a stable namespace used to+derive retry keys; authentication still comes from the server's bearer token.+It does not select or impersonate a server user.++When the orchestrator launches a harness whose lifecycle it captures, pass+`AI_MEMORY_CAPTURE_OWNER=my-orchestrator` to that process. Native capture is then+suppressed as described in the lifecycle contract. Supported handoff delivery+remains active, and the agent can keep using MCP for retrieval and deliberate+memory writes. A standalone harness without that context keeps normal hooks.++The orchestrator supplies a JSON array, for example `events.json`:++```json+[+ {+ "event_id": "event-001",+ "agent": "claude-code",+ "event": "session-start",+ "body": {+ "session_id": "native-session-123",+ "cwd": "/workspace/example"+ }+ },+ {+ "event_id": "event-002",+ "agent": "claude-code",+ "event": "user-prompt-submit",+ "body": {+ "session_id": "native-session-123",+ "cwd": "/workspace/example",+ "prompt": "Check the failing test."+ }+ }+]+```++```sh+ai-memory-relay enqueue --queue-dir "$HOME/.ai-memory-relay" --file events.json+ai-memory-relay flush --queue-dir "$HOME/.ai-memory-relay"+ai-memory-relay status --queue-dir "$HOME/.ai-memory-relay"+```++`enqueue` validates the whole array and commits it in one transaction. Each body+must be an object with explicit `session_id` and `cwd` strings. Use the harness's+native identity and canonical hook event names. Other body fields keep their+values, including an `_ai_memory_capture` block. The relay does not translate+provider transcripts or infer parent agents and workflows.++For authenticated servers, supply `AI_MEMORY_AUTH_TOKEN` through the flush+process's environment. The relay does not store or print it. The destination+must use HTTP or HTTPS, with no credentials, query string or fragment in the+base URL. Redirects are refused.++## Delivery and retries++Each event gets a deterministic `ingest_key` from the producer, actor, native+agent/session identity, event name and producer-assigned `event_id`, following+the lifecycle contract. `extension` carries the producer and `source_event`+carries the event name.++Re-enqueueing the same identity and body is recognized while the pending event+or receipt remains in the queue. JSON object key order does not matter. Reusing+that identity with different content rejects the entire input array. Two equal+bodies with different event IDs remain separate events.++Only the oldest pending event from each session enters a batch. The next event+for that session is eligible after acknowledgement. This keeps `session-end`+behind earlier events while allowing other sessions to proceed. Order is the+queue's committed enqueue order; producers must serialize events within a+session before enqueueing them. Separate queue directories do not coordinate+session order.++One process can flush a queue at a time. Other processes can enqueue during a+flush. HTTP runs outside the SQLite write transaction. If a response is lost+after the server commits, the event stays pending and a retry uses the same key.++The relay validates the complete batch acknowledgement before changing its+queue. It honors both contiguous and noncontiguous accepted indexes, including+partial success in HTTP 200 or 429 responses. Malformed acknowledgements,+authentication failures and transport errors retain unacknowledged events.+A failed head blocks its own session. HTTP 429 ends the flush; the caller should+back off before scheduling another one.++An acknowledgement can also mean the server deliberately dropped an event, for+example because of capture policy or a session identity collision. A drained+queue does not prove that every event became an observation. The relay catches+a native session changing agents within one queue, but server ownership checks+still apply across queues and producers.++The server's ingest keys expire after 30 days. The relay records the first+attempt before sending and retains expired pending events without replaying+them automatically. Unsent events can remain offline longer. Keep the host+clock accurate; the retry deadline uses wall-clock timestamps. Recreating a+queue discards its attempt history and receipts, so it is not a safe way to+recover an ambiguous delivery after the retry window.++`flush` attempts at most 64 batches by default; `--max-batches` changes that+count. Requests, transport retries and the total flush duration also have finite+bounds. Unfinished work stays queued for the next invocation.++Exit codes are:++| Code | Meaning |+| --- | --- |+| `0` | Command succeeded; a flush has no pending events. |+| `2` | Command failed. Inspect stderr; unacknowledged events remain queued. |+| `3` | Flush ended with events still pending. |++`status` emits a JSON object with counters, including `pending_items`,+`pending_bytes`, `pending_sessions`, `expired_items` and `receipts`. It does not+print event bodies. Receipts count acknowledgements, including policy drops.++## Local data and recovery++The queue contains producer-supplied event bodies before server sanitization.+The producer must apply its capture exclusions before enqueueing. The relay+does not load the project's `[capture] ignore_paths` settings or inspect tool+payloads for sensitive paths. Server sanitization cannot protect a local queue+that already contains those payloads.++On Unix, new queue directories use mode `0700` and files use `0600`. Existing+queue paths must already be private. Queue symlinks and Windows reparse points+are rejected. On Windows, the relay does not set ACLs; use a directory restricted+to the account that runs the orchestrator.++SQLite uses WAL mode and `synchronous=FULL`. Keep the database and its sidecar+files together. To move or back up a queue, stop producers and flush processes+first. Reopen the same queue after a restart; do not edit its SQLite tables to+mark events as delivered. An unknown queue schema is rejected.++The queue uses these limits:++| Resource | Limit |+| --- | --- |+| Pending events | 50,000 |+| Pending body bytes | 64 MiB |+| Pending events plus retained receipts | 200,000 |+| Retained session identities | 50,000 |+| One event body | 256 KiB |+| One input file | 32 MiB and 10,000 events |+| One HTTP batch | 8 MiB and 256 events |+| Acknowledgement body | 64 KiB |++Reaching a limit rejects new input instead of dropping older events. Receipts+and unused session records can expire after the 30-day retry window. Pending+events are retained. Review expired entries and producer failures before+choosing how to archive a queue; the CLI has no command that discards them+automatically. These are logical record limits, not a fixed SQLite file size.++## Validation++The package needs separate checks because it is outside the root workspace:++```sh+cargo fmt --check --manifest-path companions/ai-memory-relay/Cargo.toml+cargo clippy --locked --manifest-path companions/ai-memory-relay/Cargo.toml --all-targets -- -D warnings+cargo test --locked --manifest-path companions/ai-memory-relay/Cargo.toml+```++Run the integration test against locally built binaries:++```sh+cargo build --workspace+cargo build --locked --manifest-path companions/ai-memory-relay/Cargo.toml+uv run --no-project python tests/e2e/external_relay_smoke.py \+ --ai-memory-bin "$PWD/target/debug/ai-memory" \+ --relay-bin "$PWD/companions/ai-memory-relay/target/debug/ai-memory-relay"+```++Adjust the binary paths if `CARGO_TARGET_DIR` is set; Windows executables end in+`.exe`. The test starts an isolated real ai-memory server and invokes its native+hooks. It checks persistent observations for offline recovery, retries after a+lost response, distinct event identities and 15 concurrent sessions. It also+checks handoff delivery with native capture suppressed, rejected authentication+and acknowledged session collisions. Temporary data and logs are retained, and+the test prints their directory.diff --git a/companions/ai-memory-relay/src/ack.rs b/companions/ai-memory-relay/src/ack.rsnew file mode 100644index 00000000..67e02ca2--- /dev/null+++ b/companions/ai-memory-relay/src/ack.rs@@ -0,0 +1,98 @@+//! Acknowledgement parsing for `POST /hook/batch`.+//!+//! Validate the entire response before releasing any queued event. An+//! inconsistent acknowledgement leaves the whole batch pending for retry.++use serde::Deserialize;++/// The server's ack. Unknown fields are accepted (the server may add some);+/// a missing `accepted` is a malformed ack and preserves the batch.+#[derive(Debug, Clone, Deserialize)]+pub struct BatchAck {+ /// Contiguous leading prefix committed, oldest-first.+ pub accepted: usize,+ /// Non-contiguous committed indexes, when per-source rate limiting skipped items.+ #[serde(default)]+ pub accepted_indices: Option<Vec<usize>>,+ /// Item that failed processing after earlier skips.+ #[serde(default)]+ pub failed_index: Option<usize>,+}++/// Why an ack was refused. The batch stays pending in every case.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct AckRejected(pub String);++impl std::fmt::Display for AckRejected {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ write!(f, "{}", self.0)+ }+}++/// Validate an ack against the batch it answers, returning the indexes that may+/// be released.+///+/// `accepted` is the contiguous leading prefix *even when* `accepted_indices` is+/// present, so the two must agree. Duplicated or out-of-range indexes, a+/// disagreeing `accepted`, a `failed_index` outside the batch, and a+/// `failed_index` that also claims to be accepted are all refusals.+pub fn validate(batch_len: usize, ack: &BatchAck) -> Result<Vec<usize>, AckRejected> {+ let reject = |detail: String| Err(AckRejected(detail));+ let accepted: Vec<usize> = match &ack.accepted_indices {+ Some(indices) => {+ if let Some(bad) = indices.iter().find(|idx| **idx >= batch_len) {+ return reject(format!(+ "accepted_indices contains {bad}, outside a {batch_len}-item batch"+ ));+ }+ if indices.windows(2).any(|pair| pair[0] >= pair[1]) {+ return reject(+ "accepted_indices must be strictly ascending and duplicate-free".into(),+ );+ }+ let prefix = indices+ .iter()+ .enumerate()+ .take_while(|(pos, idx)| pos == *idx)+ .count();+ if prefix != ack.accepted {+ return reject(format!(+ "accepted={} disagrees with the {prefix}-item contiguous prefix of accepted_indices",+ ack.accepted+ ));+ }+ indices.clone()+ }+ None => {+ if ack.accepted > batch_len {+ return reject(format!(+ "accepted={} exceeds the {batch_len} items sent",+ ack.accepted+ ));+ }+ (0..ack.accepted).collect()+ }+ };+ if let Some(failed) = ack.failed_index {+ if failed >= batch_len {+ return reject(format!(+ "failed_index={failed} is outside a {batch_len}-item batch"+ ));+ }+ if accepted.contains(&failed) {+ return reject(format!(+ "failed_index={failed} is also reported as accepted"+ ));+ }+ // The server fails fast: it stops at `failed_index` and processes+ // nothing after it. An ack claiming a later item committed describes a+ // run that cannot have happened, so the batch is preserved whole.+ if let Some(after) = accepted.iter().find(|idx| **idx > failed) {+ return reject(format!(+ "accepted index {after} comes after failed_index={failed}, which the server \+ never processes past"+ ));+ }+ }+ Ok(accepted)+}diff --git a/companions/ai-memory-relay/src/fsguard.rs b/companions/ai-memory-relay/src/fsguard.rsnew file mode 100644index 00000000..5a1cba8a--- /dev/null+++ b/companions/ai-memory-relay/src/fsguard.rs@@ -0,0 +1,220 @@+//! Filesystem guards for the queue directory.+//!+//! Event bodies reach this directory before server sanitization. Unix paths+//! must be private; existing permissions are checked without changing them.+//!+//! Windows: only symlink/reparse-point rejection is implemented. No ACL+//! hardening is performed, so a queue directory there is exactly as private as+//! the operator made it.++use std::path::{Component, Path, PathBuf};++use anyhow::{Context, Result, bail};++/// SQLite sidecars that must be checked alongside the database itself.+pub const SIDECARS: &[&str] = &[+ "relay.sqlite-wal",+ "relay.sqlite-shm",+ "relay.sqlite-journal",+];+/// The queue database file name.+pub const DB_FILE: &str = "relay.sqlite";++/// Reject a path that is a symlink or a Windows reparse point.+///+/// A missing path is fine: it is about to be created inside a directory that+/// was itself checked.+pub fn reject_symlink(path: &Path) -> Result<()> {+ let meta = match std::fs::symlink_metadata(path) {+ Ok(meta) => meta,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()),+ Err(e) => return Err(e).with_context(|| format!("inspect {}", path.display())),+ };+ if meta.file_type().is_symlink() {+ bail!(+ "{} is a symlink; the relay refuses to follow one into a queue directory",+ path.display()+ );+ }+ #[cfg(windows)]+ {+ use std::os::windows::fs::MetadataExt;+ const FILE_ATTRIBUTE_REPARSE_POINT: u32 = 0x400;+ if meta.file_attributes() & FILE_ATTRIBUTE_REPARSE_POINT != 0 {+ bail!(+ "{} is a reparse point; the relay refuses to follow one into a queue directory",+ path.display()+ );+ }+ }+ Ok(())+}++/// Check one queue file: not a symlink/reparse point, a regular file, not+/// hardlinked elsewhere, and owner-only on Unix. A missing file passes.+pub fn check_queue_file(path: &Path) -> Result<()> {+ reject_symlink(path)?;+ let meta = match std::fs::symlink_metadata(path) {+ Ok(meta) => meta,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => return Ok(()),+ Err(e) => return Err(e).with_context(|| format!("inspect {}", path.display())),+ };+ if !meta.is_file() {+ bail!(+ "{} exists but is not a regular file; refusing to use it as queue state",+ path.display()+ );+ }+ #[cfg(unix)]+ {+ use std::os::unix::fs::MetadataExt;+ use std::os::unix::fs::PermissionsExt;+ if meta.nlink() > 1 {+ bail!(+ "{} has {} hard links; refusing to write queue state through a shared inode",+ path.display(),+ meta.nlink()+ );+ }+ let mode = meta.permissions().mode();+ if mode & 0o077 != 0 {+ bail!(+ "{} is mode {:o}; queue state must be owner-only (chmod 600) \+ (existing permissions are unchanged)",+ path.display(),+ mode & 0o7777+ );+ }+ }+ Ok(())+}++/// Prepare `--queue-dir`.+///+/// A directory the relay creates is created owner-only. An existing directory+/// must already be private and must be either empty or an existing relay queue;+/// anything else is refused untouched, so pointing the relay at a shared+/// directory can never re-permission it.+pub fn prepare_queue_dir(dir: &Path) -> Result<PathBuf> {+ if dir.components().any(|c| c == Component::ParentDir) {+ bail!(+ "--queue-dir must not contain a `..` component: {}",+ dir.display()+ );+ }+ reject_symlink(dir)?;+ match std::fs::symlink_metadata(dir) {+ Ok(meta) if !meta.is_dir() => bail!("--queue-dir {} is not a directory", dir.display()),+ Ok(_) => check_existing_dir(dir)?,+ Err(e) if e.kind() == std::io::ErrorKind::NotFound => create_private_dir(dir)?,+ Err(e) => return Err(e).with_context(|| format!("inspect {}", dir.display())),+ }+ for name in std::iter::once(DB_FILE).chain(SIDECARS.iter().copied()) {+ check_queue_file(&dir.join(name))?;+ }+ std::fs::canonicalize(dir).with_context(|| format!("resolve {}", dir.display()))+}++/// An existing directory must be private and dedicated to this queue.+fn check_existing_dir(dir: &Path) -> Result<()> {+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ let mode = std::fs::metadata(dir)?.permissions().mode();+ if mode & 0o077 != 0 {+ bail!(+ "--queue-dir {} is mode {:o}; it must be owner-only (chmod 700) before the relay \+ will store event bodies in it. The relay does not re-permission a directory it \+ did not create",+ dir.display(),+ mode & 0o7777+ );+ }+ }+ let mut foreign = Vec::new();+ for entry in std::fs::read_dir(dir).with_context(|| format!("read {}", dir.display()))? {+ let name = entry?.file_name();+ let name = name.to_string_lossy().to_string();+ let known = name == DB_FILE || name == "flush.lock" || SIDECARS.contains(&name.as_str());+ if !known {+ foreign.push(name);+ }+ }+ if !foreign.is_empty() {+ foreign.sort();+ foreign.truncate(5);+ bail!(+ "--queue-dir {} already holds unrelated files ({}); point the relay at an empty or \+ existing queue directory instead of sharing one",+ dir.display(),+ foreign.join(", ")+ );+ }+ Ok(())+}++#[cfg(unix)]+fn create_private_dir(dir: &Path) -> Result<()> {+ use std::os::unix::fs::DirBuilderExt;+ if let Some(parent) = dir.parent()+ && !parent.as_os_str().is_empty()+ && !parent.exists()+ {+ bail!(+ "parent of --queue-dir {} does not exist; create it deliberately first",+ dir.display()+ );+ }+ std::fs::DirBuilder::new()+ .mode(0o700)+ .create(dir)+ .with_context(|| format!("create {}", dir.display()))+}++#[cfg(not(unix))]+fn create_private_dir(dir: &Path) -> Result<()> {+ if let Some(parent) = dir.parent()+ && !parent.as_os_str().is_empty()+ && !parent.exists()+ {+ bail!(+ "parent of --queue-dir {} does not exist; create it deliberately first",+ dir.display()+ );+ }+ std::fs::create_dir(dir).with_context(|| format!("create {}", dir.display()))+}++/// Create a queue file owner-only, or leave an existing one alone.+///+/// SQLite copies the database mode onto its sidecars. Set 0600 at creation so+/// WAL and SHM files are private from their first write.+#[cfg(unix)]+pub fn create_private_file(path: &Path) -> Result<()> {+ use std::os::unix::fs::OpenOptionsExt;+ match std::fs::OpenOptions::new()+ .create_new(true)+ .write(true)+ .mode(0o600)+ .open(path)+ {+ Ok(_) => Ok(()),+ // Another process won the race and made it; its own guard applies.+ Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => Ok(()),+ Err(e) => Err(e).with_context(|| format!("create {}", path.display())),+ }+}++/// No ACL hardening on non-Unix targets; documented in the README.+#[cfg(not(unix))]+pub fn create_private_file(path: &Path) -> Result<()> {+ match std::fs::OpenOptions::new()+ .create_new(true)+ .write(true)+ .open(path)+ {+ Ok(_) => Ok(()),+ Err(e) if e.kind() == std::io::ErrorKind::AlreadyExists => Ok(()),+ Err(e) => Err(e).with_context(|| format!("create {}", path.display())),+ }+}diff --git a/companions/ai-memory-relay/src/http.rs b/companions/ai-memory-relay/src/http.rsnew file mode 100644index 00000000..59b14b38--- /dev/null+++ b/companions/ai-memory-relay/src/http.rs@@ -0,0 +1,200 @@+//! The only network surface: `POST <server>/hook/batch`.+//!+//! Per-item URLs are always constructed here from the bound destination and the+//! queue's own fields. An input file can never steer a request anywhere.++use std::io::Read;+use std::time::Duration;++use anyhow::{Context, Result, bail};+use url::Url;++use crate::queue::{Binding, PendingItem};++/// Bearer material. Never stored on disk, never printed, never in a Debug line.+pub struct Token(String);++impl std::fmt::Debug for Token {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ f.write_str("Token(<redacted>)")+ }+}++impl Token {+ /// Read `AI_MEMORY_AUTH_TOKEN` from the environment of *this* flush.+ ///+ /// The value is never echoed, not even when it is rejected.+ pub fn from_env() -> Result<Option<Self>> {+ let Ok(raw) = std::env::var("AI_MEMORY_AUTH_TOKEN") else {+ return Ok(None);+ };+ let trimmed = raw.trim();+ if trimmed.is_empty() {+ return Ok(None);+ }+ if trimmed.chars().any(|c| c.is_control()) {+ bail!("AI_MEMORY_AUTH_TOKEN contains control characters; refusing to build a request");+ }+ Ok(Some(Self(trimmed.to_owned())))+ }++ fn expose(&self) -> &str {+ &self.0+ }+}++/// Normalize and harden `--server-url`.+///+/// http/https only, a host, no userinfo, no query, no fragment. No host+/// allowlist: a remote HTTPS server is a legitimate deployment.+pub fn normalize_server_url(raw: &str) -> Result<String> {+ let url = Url::parse(raw).context("invalid --server-url")?;+ if !matches!(url.scheme(), "http" | "https") {+ bail!("--server-url must be http or https, got {:?}", url.scheme());+ }+ if !url.username().is_empty() || url.password().is_some() {+ bail!("--server-url must not carry userinfo; pass credentials in AI_MEMORY_AUTH_TOKEN");+ }+ if url.query().is_some() {+ bail!("--server-url must not carry a query string");+ }+ if url.fragment().is_some() {+ bail!("--server-url must not carry a fragment");+ }+ let host = url.host_str().context("--server-url needs a host")?;+ let authority = match url.port() {+ Some(port) => format!("{host}:{port}"),+ None => host.to_owned(),+ };+ let path = url.path().trim_end_matches('/');+ Ok(format!("{}://{}{}", url.scheme(), authority, path))+}++/// The `{url, body}` pair the batch endpoint expects.+#[derive(Debug, serde::Serialize)]+pub struct BatchItem {+ pub url: String,+ pub body: serde_json::Value,+}++/// Build one item's hook URL from the binding plus the queued event.+///+/// `extension` carries the producer namespace, `source_event` repeats the+/// canonical event explicitly (both are required to preserve provenance), and+/// `ingest_key` is the stable key persisted with the event at enqueue time.+pub fn item_url(base: &str, binding: &Binding, item: &PendingItem) -> String {+ let query = url::form_urlencoded::Serializer::new(String::new())+ .append_pair("event", &item.event)+ .append_pair("agent", &item.agent)+ .append_pair("workspace", &binding.workspace)+ .append_pair("project", &binding.project)+ .append_pair("extension", &binding.producer)+ .append_pair("source_event", &item.event)+ .append_pair("ingest_key", &item.ingest_key)+ .finish();+ format!("{base}/hook?{query}")+}++/// Largest ack body the relay will read. A 256-index ack is under 2 KiB; 64 KiB+/// leaves room for future fields while refusing to stream an unbounded response+/// from a server that is not behaving like ai-memory.+pub const MAX_ACK_BYTES: usize = 64 * 1024;++/// One completed HTTP exchange. The body is bounded and never logged.+pub struct Delivery {+ pub status: u16,+ pub body: Vec<u8>,+}++impl std::fmt::Debug for Delivery {+ // Length only: an ack body is server output, and output never becomes a log+ // line here by accident.+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ f.debug_struct("Delivery")+ .field("status", &self.status)+ .field("body_bytes", &self.body.len())+ .finish()+ }+}++/// Blocking batch sender.+pub struct Sender {+ client: reqwest::blocking::Client,+ base: String,+ token: Option<Token>,+}++impl std::fmt::Debug for Sender {+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ f.debug_struct("Sender")+ .field("base", &self.base)+ .field("token", &self.token)+ .finish()+ }+}++impl Sender {+ /// Build the client. Redirects are disabled: a 3xx from the ingestion+ /// endpoint must never resend the bearer header, or the batch, elsewhere.+ /// The read timeout is per request, because a batch's budget scales with the+ /// number of items it carries.+ pub fn new(base: String, token: Option<Token>, connect_timeout: Duration) -> Result<Self> {+ let client = reqwest::blocking::Client::builder()+ .redirect(reqwest::redirect::Policy::none())+ .connect_timeout(connect_timeout)+ .build()+ .context("build HTTP client")?;+ Ok(Self {+ client,+ base,+ token,+ })+ }++ /// POST one batch under an explicit timeout.+ ///+ /// Transport failures carry a short class label only: never the request, the+ /// response, or the bearer header.+ pub fn post_batch(&self, items: &[BatchItem], timeout: Duration) -> Result<Delivery> {+ let mut request = self+ .client+ .post(format!("{}/hook/batch", self.base))+ .timeout(timeout)+ .json(items);+ if let Some(token) = &self.token {+ request = request.bearer_auth(token.expose());+ }+ let response = request.send().map_err(|e| {+ anyhow::anyhow!("hook batch transport failure: {}", transport_class(&e))+ })?;+ let status = response.status().as_u16();+ // Bounded read: `bytes()` would accept whatever the peer sends.+ let mut body = Vec::new();+ let mut limited = response.take(MAX_ACK_BYTES as u64 + 1);+ if limited.read_to_end(&mut body).is_err() {+ body.clear();+ }+ if body.len() > MAX_ACK_BYTES {+ bail!(+ "hook batch ack exceeded {MAX_ACK_BYTES} bytes; refusing to parse it \+ (the batch stays pending)"+ );+ }+ Ok(Delivery { status, body })+ }+}++/// A short, content-free label for a transport error.+fn transport_class(error: &reqwest::Error) -> &'static str {+ if error.is_timeout() {+ "timeout"+ } else if error.is_connect() {+ "connect"+ } else if error.is_redirect() {+ "redirect refused"+ } else if error.is_request() {+ "request"+ } else {+ "io"+ }+}diff --git a/companions/ai-memory-relay/src/identity.rs b/companions/ai-memory-relay/src/identity.rsnew file mode 100644index 00000000..672e989d--- /dev/null+++ b/companions/ai-memory-relay/src/identity.rs@@ -0,0 +1,224 @@+//! Envelope validation and the stable retry identity.+//!+//! Validate input before enqueueing so malformed events cannot block a batch.+//! Body values, including `_ai_memory_capture`, are preserved for the server.+//! These checks do not sanitize locally queued content.++use serde::Deserialize;+use sha2::{Digest, Sha256};++/// `extension` accepts up to 64 ASCII token characters (docs/external-lifecycle.md).+pub const MAX_PRODUCER_LEN: usize = 64;+/// A stable adapter-side operator namespace. Never a bearer token.+pub const MAX_ACTOR_LEN: usize = 64;+/// `source_event` accepts 128 (docs/external-lifecycle.md).+pub const MAX_EVENT_LEN: usize = 128;+/// Producer-assigned event id. It only feeds the ingest-key hash, so it is+/// bounded free-form text rather than a+/// token: an orchestrator numbering events `run/123/event/2` is normal.+pub const MAX_EVENT_ID_LEN: usize = 128;+/// Wire `agent` such as `claude-code` or `codex`.+pub const MAX_AGENT_LEN: usize = 64;+/// Workspace / project names, URL-encoded into the item query.+pub const MAX_SCOPE_LEN: usize = 128;+/// Native session id, preserved exactly as the harness minted it.+pub const MAX_SESSION_ID_LEN: usize = 256;+/// Native cwd, preserved exactly as the harness reported it.+pub const MAX_CWD_LEN: usize = 4096;+/// Canonicalized body bytes accepted for one event.+pub const MAX_BODY_BYTES: usize = 256 * 1024;+/// Items in one `POST /hook/batch` (server: `MAX_HOOK_BATCH_ITEMS`).+pub const MAX_BATCH_ITEMS: usize = 256;+/// Server ingest keys expire after 30 days; nothing older may be auto-resent.+pub const RETRY_WINDOW_MS: i64 = 30 * 24 * 60 * 60 * 1000;++/// Lifecycle events that end an execution. A terminal event may only ship once+/// it is its session's oldest pending item, so it can never pass an earlier one.+pub const TERMINAL_EVENTS: &[&str] = &["session-end"];++/// One item of the `enqueue --file` input array.+///+/// `deny_unknown_fields` applies to the envelope only. `body` is an opaque+/// object: unknown keys inside it (a harness payload field, the+/// `_ai_memory_capture` protocol block) are preserved untouched.+#[derive(Debug, Deserialize)]+#[serde(deny_unknown_fields)]+pub struct InputEvent {+ /// Producer-assigned id, unique within the producer/actor/agent/session tuple.+ pub event_id: String,+ /// Wire agent of the live harness (`claude-code`, `codex`, ...).+ pub agent: String,+ /// Canonical lifecycle event name, used for both `event` and `source_event`.+ pub event: String,+ /// Harness payload, delivered verbatim.+ pub body: serde_json::Value,+}++/// A validated event, ready to be persisted and later replayed unchanged.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct ValidEvent {+ pub event_id: String,+ pub agent: String,+ pub event: String,+ pub session_id: String,+ pub cwd: String,+ /// Canonical JSON of the body exactly as supplied (sorted keys, no reformatting+ /// of values). The bytes delivered later are these bytes.+ pub body_json: String,+ pub body_sha256: String,+ pub ingest_key: String,+}++impl ValidEvent {+ /// True when this event ends the execution for its session.+ pub fn is_terminal(&self) -> bool {+ TERMINAL_EVENTS.contains(&self.event.as_str())+ }+}++/// `extension`, `source_event` and `ingest_key` share the server's token+/// alphabet: letters, digits, `.`, `_`, `-` and `:`.+fn is_token(value: &str, max: usize) -> bool {+ !value.is_empty()+ && value.len() <= max+ && value+ .bytes()+ .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'-' | b':'))+}++/// Free-form identity text (session id, cwd, scope names): bounded, non-blank,+/// and free of control characters that would corrupt a URL or a log line.+fn is_plain(value: &str, max: usize) -> bool {+ !value.trim().is_empty()+ && value.chars().count() <= max+ && !value.chars().any(|c| c.is_control())+}++/// Validate the fields that identify a producer namespace.+pub fn check_producer(producer: &str) -> Result<(), String> {+ is_token(producer, MAX_PRODUCER_LEN)+ .then_some(())+ .ok_or_else(|| format!("--producer must be 1..={MAX_PRODUCER_LEN} token characters"))+}++/// Validate the adapter-side operator namespace.+pub fn check_actor(actor: &str) -> Result<(), String> {+ is_token(actor, MAX_ACTOR_LEN)+ .then_some(())+ .ok_or_else(|| format!("--actor must be 1..={MAX_ACTOR_LEN} token characters"))+}++/// Validate a workspace or project name.+pub fn check_scope(label: &str, value: &str) -> Result<(), String> {+ is_plain(value, MAX_SCOPE_LEN)+ .then_some(())+ .ok_or_else(|| format!("--{label} must be 1..={MAX_SCOPE_LEN} printable characters"))+}++/// The retry identity from `docs/external-lifecycle.md`, byte-for-byte.+///+/// The tuple defines the namespace of `event_id`. Payload content does not+/// contribute to the key, so a restarted producer can derive the same identity.+pub fn ingest_key(+ producer: &str,+ actor: &str,+ agent: &str,+ session_id: &str,+ source_event: &str,+ event_id: &str,+) -> String {+ let identity = serde_json::to_string(&[+ "external-capture-v1",+ producer,+ actor,+ agent,+ session_id,+ source_event,+ event_id,+ ])+ .expect("a fixed-size array of strings always serializes");+ let digest = Sha256::digest(identity.as_bytes());+ let mut key = String::with_capacity(64);+ for byte in digest {+ use std::fmt::Write as _;+ let _ = write!(key, "{byte:02x}");+ }+ key+}++/// Validate one input item against every bound above.+///+/// Errors name the array index and the producer's own `event_id`. They never+/// quote body content: an invalid payload must not become a log line.+pub fn validate(+ index: usize,+ input: InputEvent,+ producer: &str,+ actor: &str,+) -> Result<ValidEvent, String> {+ let at = |detail: &str| format!("item {index}: {detail}");+ if !is_plain(&input.event_id, MAX_EVENT_ID_LEN) {+ return Err(at(&format!(+ "event_id must be 1..={MAX_EVENT_ID_LEN} printable characters"+ )));+ }+ let tag = format!("item {index} (event_id {}): ", input.event_id);+ let at = |detail: &str| format!("{tag}{detail}");+ if !is_token(&input.agent, MAX_AGENT_LEN) {+ return Err(at(&format!(+ "agent must be 1..={MAX_AGENT_LEN} token characters"+ )));+ }+ if !is_token(&input.event, MAX_EVENT_LEN) {+ return Err(at(&format!(+ "event must be 1..={MAX_EVENT_LEN} token characters"+ )));+ }+ let serde_json::Value::Object(body) = &input.body else {+ return Err(at("body must be a JSON object"));+ };+ let Some(serde_json::Value::String(session_id)) = body.get("session_id") else {+ return Err(at("body.session_id must be an explicit string"));+ };+ if !is_plain(session_id, MAX_SESSION_ID_LEN) {+ return Err(at(&format!(+ "body.session_id must be 1..={MAX_SESSION_ID_LEN} printable characters"+ )));+ }+ let Some(serde_json::Value::String(cwd)) = body.get("cwd") else {+ return Err(at("body.cwd must be an explicit string"));+ };+ if !is_plain(cwd, MAX_CWD_LEN) {+ return Err(at(&format!(+ "body.cwd must be 1..={MAX_CWD_LEN} printable characters"+ )));+ }+ let (session_id, cwd) = (session_id.clone(), cwd.clone());+ let body_json = serde_json::to_string(&input.body).map_err(|_| at("body is not encodable"))?;+ if body_json.len() > MAX_BODY_BYTES {+ return Err(at(&format!(+ "body is {} bytes, over the {MAX_BODY_BYTES}-byte limit",+ body_json.len()+ )));+ }+ let digest = Sha256::digest(body_json.as_bytes());+ let body_sha256 = digest.iter().map(|b| format!("{b:02x}")).collect();+ let ingest_key = ingest_key(+ producer,+ actor,+ &input.agent,+ &session_id,+ &input.event,+ &input.event_id,+ );+ Ok(ValidEvent {+ event_id: input.event_id,+ agent: input.agent,+ event: input.event,+ session_id,+ cwd,+ body_json,+ body_sha256,+ ingest_key,+ })+}diff --git a/companions/ai-memory-relay/src/lib.rs b/companions/ai-memory-relay/src/lib.rsnew file mode 100644index 00000000..7a1a3a36--- /dev/null+++ b/companions/ai-memory-relay/src/lib.rs@@ -0,0 +1,28 @@+//! Persistent queue for external lifecycle events sent through `POST /hook/batch`.+//!+//! The queue is separate from ai-memory's database and wiki. Events leave it+//! after a validated acknowledgement, which may include a server policy drop.+//! Pending events remain on disk when delivery fails or their retry window+//! expires; reaching a capacity limit rejects new input.+//!+//! Bodies retain their input values before server sanitization. Producers must+//! apply capture exclusions before enqueueing and protect the queue directory.++pub mod ack;+pub mod fsguard;+pub mod http;+pub mod identity;+pub mod queue;+pub mod relay;++/// Wall-clock milliseconds since the Unix epoch.+///+/// Used for the retry window, which is why it is clamped at 0 rather than+/// panicking on a pre-epoch clock: a nonsensical clock must not take the process+/// down mid-flush.+pub fn now_ms() -> i64 {+ std::time::SystemTime::now()+ .duration_since(std::time::UNIX_EPOCH)+ .map(|d| i64::try_from(d.as_millis()).unwrap_or(i64::MAX))+ .unwrap_or(0)+}diff --git a/companions/ai-memory-relay/src/main.rs b/companions/ai-memory-relay/src/main.rsnew file mode 100644index 00000000..6a4fbea1--- /dev/null+++ b/companions/ai-memory-relay/src/main.rs@@ -0,0 +1,113 @@+//! Thin CLI over [`ai_memory_relay::relay`]. Parse, call, print, exit.++use std::path::PathBuf;++use ai_memory_relay::relay::{self, FlushOptions, Report};+use clap::{Parser, Subcommand};++/// Queue external lifecycle events for ai-memory.+///+/// Exit codes: 0 success, 2 failure, 3 flush ended with events pending.+#[derive(Debug, Parser)]+#[command(name = "ai-memory-relay", version, about, long_about = None)]+struct Cli {+ #[command(subcommand)]+ command: Command,+}++#[derive(Debug, Subcommand)]+enum Command {+ /// Bind a queue directory to one destination, producer, actor and scope.+ Init {+ #[arg(long)]+ queue_dir: PathBuf,+ /// http(s) base URL of the ai-memory server. No userinfo, query or fragment.+ #[arg(long)]+ server_url: String,+ /// Producer namespace, sent as `extension` (also your `AI_MEMORY_CAPTURE_OWNER`).+ #[arg(long)]+ producer: String,+ /// Stable adapter-side operator namespace. Never a bearer token.+ #[arg(long)]+ actor: String,+ #[arg(long)]+ workspace: String,+ #[arg(long)]+ project: String,+ },+ /// Add events from a JSON array file. All-or-nothing.+ Enqueue {+ #[arg(long)]+ queue_dir: PathBuf,+ /// `[{"event_id","agent","event","body"}]`; body needs explicit `session_id` and `cwd`.+ #[arg(long)]+ file: PathBuf,+ },+ /// Deliver pending events through POST /hook/batch.+ Flush {+ #[arg(long)]+ queue_dir: PathBuf,+ /// Batches attempted in one flush. Finite by default: a flush never loops+ /// forever, and what it does not deliver stays queued for the next run.+ #[arg(long, default_value_t = 64)]+ max_batches: usize,+ },+ /// Payload-free counters for the queue, as JSON.+ Status {+ #[arg(long)]+ queue_dir: PathBuf,+ },+}++fn main() {+ let cli = Cli::parse();+ let outcome = match cli.command {+ Command::Init {+ queue_dir,+ server_url,+ producer,+ actor,+ workspace,+ project,+ } => relay::init(+ &queue_dir,+ &server_url,+ &producer,+ &actor,+ &workspace,+ &project,+ ),+ Command::Enqueue { queue_dir, file } => relay::enqueue(&queue_dir, &file),+ Command::Flush {+ queue_dir,+ max_batches,+ } => relay::flush(+ &queue_dir,+ &FlushOptions {+ max_batches: max_batches.max(1),+ },+ ),+ Command::Status { queue_dir } => relay::status(&queue_dir),+ };+ std::process::exit(finish(outcome));+}++fn finish(outcome: anyhow::Result<Report>) -> i32 {+ match outcome {+ Ok(report) => {+ for line in &report.summary {+ println!("{line}");+ }+ if let Some(failure) = &report.failure {+ eprintln!("error: {failure}");+ }+ report.exit_code()+ }+ Err(error) => {+ // `{error:#}` prints the context chain, which is built from paths,+ // counts and classes only.+ eprintln!("error: {error:#}");+ 2+ }+ }+}diff --git a/companions/ai-memory-relay/src/queue.rs b/companions/ai-memory-relay/src/queue.rsnew file mode 100644index 00000000..b414ae4e--- /dev/null+++ b/companions/ai-memory-relay/src/queue.rs@@ -0,0 +1,727 @@+//! The companion's own durable queue: one private SQLite database per queue+//! directory. It never opens ai-memory's database or wiki.+//!+//! The binding fixes the destination, producer identity and scope. Pending+//! events keep their body values until acknowledgement. Receipts retain keys+//! and content hashes for duplicate recognition during the retry window.+//! Session records reject a native session changing agents within one queue.++use std::collections::{HashMap, HashSet};+use std::path::{Path, PathBuf};+use std::time::Duration;++use anyhow::{Context, Result, bail};+use rusqlite::{Connection, OptionalExtension, TransactionBehavior, params};++use crate::fsguard;+use crate::identity::{MAX_BODY_BYTES, RETRY_WINDOW_MS, TERMINAL_EVENTS, ValidEvent};++/// Undelivered events allowed in one queue.+pub const MAX_PENDING_ITEMS: i64 = 50_000;+/// Undelivered body bytes allowed in one queue.+pub const MAX_PENDING_BYTES: i64 = 64 * 1024 * 1024;+/// Pending events plus retained receipts. Admission reserves one receipt for+/// each new event so acknowledgement cannot exceed the limit.+pub const MAX_RECEIPTS: i64 = 200_000;+/// Session-to-agent pins retained at once, enforced the same way.+pub const MAX_SESSION_PINS: i64 = 50_000;++const SCHEMA_VERSION: &str = "1";+const IDENTITY: &str = "ai-memory-relay-queue";++const SCHEMA: &str = "+CREATE TABLE IF NOT EXISTS meta(+ key TEXT PRIMARY KEY,+ value TEXT NOT NULL+);+CREATE TABLE IF NOT EXISTS binding(+ id INTEGER PRIMARY KEY CHECK(id = 1),+ server_url TEXT NOT NULL,+ producer TEXT NOT NULL,+ actor TEXT NOT NULL,+ workspace TEXT NOT NULL,+ project TEXT NOT NULL,+ created_at_ms INTEGER NOT NULL+);+CREATE TABLE IF NOT EXISTS pending(+ seq INTEGER PRIMARY KEY AUTOINCREMENT,+ ingest_key TEXT NOT NULL UNIQUE,+ event_id TEXT NOT NULL,+ agent TEXT NOT NULL,+ event TEXT NOT NULL,+ session_id TEXT NOT NULL,+ cwd TEXT NOT NULL,+ body_json TEXT NOT NULL,+ body_sha256 TEXT NOT NULL,+ body_bytes INTEGER NOT NULL,+ first_seen_ms INTEGER NOT NULL,+ first_attempt_ms INTEGER,+ attempts INTEGER NOT NULL DEFAULT 0,+ last_error TEXT+);+CREATE INDEX IF NOT EXISTS pending_session ON pending(agent, session_id, seq);+CREATE TABLE IF NOT EXISTS receipt(+ ingest_key TEXT PRIMARY KEY,+ body_sha256 TEXT NOT NULL,+ first_attempt_ms INTEGER NOT NULL,+ delivered_at_ms INTEGER NOT NULL+);+CREATE INDEX IF NOT EXISTS receipt_first_attempt ON receipt(first_attempt_ms);+CREATE TABLE IF NOT EXISTS session_agent(+ session_id TEXT PRIMARY KEY,+ agent TEXT NOT NULL,+ last_seen_ms INTEGER NOT NULL+);+";++/// What `init` bound this queue directory to.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct Binding {+ pub server_url: String,+ pub producer: String,+ pub actor: String,+ pub workspace: String,+ pub project: String,+}++/// Whether `init` created the binding or recognized an identical one.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+pub enum BindOutcome {+ Created,+ Recognized,+}++/// Per-file result of `enqueue`.+#[derive(Debug, Default, Clone, PartialEq, Eq)]+pub struct EnqueueReport {+ pub accepted: usize,+ /// Same id, byte-identical body: already pending or already delivered.+ pub recognized: usize,+}++/// One item selected for delivery.+#[derive(Debug, Clone)]+pub struct PendingItem {+ pub seq: i64,+ pub ingest_key: String,+ pub event_id: String,+ pub agent: String,+ pub event: String,+ pub session_id: String,+ pub body_json: String,+ pub body_bytes: i64,+ pub first_seen_ms: i64,+ pub first_attempt_ms: Option<i64>,+}++impl PendingItem {+ /// Session coordinate: one head per `(agent, session_id)` per batch.+ pub fn session(&self) -> (String, String) {+ (self.agent.clone(), self.session_id.clone())+ }+}++/// A batch plus what was held back while building it.+#[derive(Debug, Default, Clone)]+pub struct Batch {+ pub items: Vec<PendingItem>,+ /// Sessions whose head is past the retry window. The whole session is held:+ /// skipping its head and sending the next event would reorder it.+ pub blocked_sessions: usize,+ /// Sessions skipped because the byte budget filled first.+ pub budget_deferred: usize,+}++/// Counters for `status`. Deliberately payload-free.+#[derive(Debug, Default, Clone, PartialEq, Eq)]+pub struct Stats {+ pub pending_items: i64,+ pub pending_bytes: i64,+ pub pending_sessions: i64,+ pub attempted_items: i64,+ pub expired_items: i64,+ pub oldest_pending_age_ms: i64,+ pub max_attempts: i64,+ pub receipts: i64,+ pub known_sessions: i64,+}++/// The companion's queue database.+pub struct Queue {+ conn: Connection,+ path: PathBuf,+}++impl std::fmt::Debug for Queue {+ // Path only: never connection internals, never row data.+ fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {+ f.debug_struct("Queue").field("path", &self.path).finish()+ }+}++impl Queue {+ /// Open (or create) the queue database inside an already-prepared directory.+ ///+ /// Check an existing file's identity before schema writes. Schema and+ /// metadata commit together, so an interrupted initialization can reopen+ /// the empty database left by rollback.+ pub fn open(dir: &Path) -> Result<Self> {+ let path = dir.join(fsguard::DB_FILE);+ fsguard::check_queue_file(&path)?;+ for name in fsguard::SIDECARS {+ fsguard::check_queue_file(&dir.join(name))?;+ }+ if !path.exists() {+ // Own the mode before SQLite ever opens the file: the `-wal` and+ // `-shm` sidecars inherit the database's permissions, so creating it+ // under the ambient umask would make them world-readable.+ fsguard::create_private_file(&path)?;+ fsguard::check_queue_file(&path)?;+ }+ let mut conn = Connection::open(&path)+ .with_context(|| format!("open relay queue at {}", path.display()))?;+ conn.busy_timeout(Duration::from_secs(10))?;+ let state = classify(&conn, &path)?;+ conn.execute_batch(+ "PRAGMA journal_mode=WAL;\nPRAGMA synchronous=FULL;\nPRAGMA foreign_keys=ON;",+ )+ .with_context(|| format!("configure relay queue at {}", path.display()))?;+ if state != DbState::Ready {+ let tx = conn.transaction_with_behavior(TransactionBehavior::Immediate)?;+ tx.execute_batch(SCHEMA)+ .with_context(|| format!("initialize relay queue schema at {}", path.display()))?;+ tx.execute(+ "INSERT OR REPLACE INTO meta(key, value) VALUES('identity', ?1), ('schema_version', ?2)",+ params![IDENTITY, SCHEMA_VERSION],+ )?;+ tx.commit()?;+ }+ Ok(Self { conn, path })+ }++ /// Path of the database, for operator-facing messages.+ pub fn path(&self) -> &Path {+ &self.path+ }++ /// Bind the queue to a destination, producer, actor and scope.+ ///+ /// Repeated initialization must preserve the destination and identity of+ /// queued events, including events whose acknowledgement was lost.+ pub fn bind(&mut self, binding: &Binding, now_ms: i64) -> Result<BindOutcome> {+ let tx = self+ .conn+ .transaction_with_behavior(TransactionBehavior::Immediate)?;+ let outcome = match read_binding(&tx)? {+ Some(existing) if existing == *binding => BindOutcome::Recognized,+ Some(existing) => {+ let mut changed = Vec::new();+ let mut note = |label: &str, old: &str, new: &str| {+ if old != new {+ changed.push(format!("{label}: {old:?} -> {new:?}"));+ }+ };+ note("server-url", &existing.server_url, &binding.server_url);+ note("producer", &existing.producer, &binding.producer);+ note("actor", &existing.actor, &binding.actor);+ note("workspace", &existing.workspace, &binding.workspace);+ note("project", &existing.project, &binding.project);+ bail!(+ "binding mismatch: this queue is already bound ({}). \+ Use a separate --queue-dir for a different destination or identity",+ changed.join(", ")+ );+ }+ None => {+ tx.execute(+ "INSERT INTO binding(id, server_url, producer, actor, workspace, project, created_at_ms)+ VALUES(1, ?1, ?2, ?3, ?4, ?5, ?6)",+ params![+ binding.server_url,+ binding.producer,+ binding.actor,+ binding.workspace,+ binding.project,+ now_ms,+ ],+ )?;+ BindOutcome::Created+ }+ };+ tx.commit()?;+ Ok(outcome)+ }++ /// The binding, or a clear error telling the operator to run `init` first.+ pub fn binding(&self) -> Result<Binding> {+ read_binding(&self.conn)?.ok_or_else(|| {+ anyhow::anyhow!("queue is not bound yet; run `ai-memory-relay init` first")+ })+ }++ /// Persist a whole validated file, all-or-nothing.+ ///+ /// `first_seen_ms` is stamped here for reporting. It is *not* the retry+ /// clock: that starts at the first durable attempt, recorded before the+ /// first HTTP request (see [`Queue::stamp_attempt`]).+ pub fn enqueue(&mut self, events: &[ValidEvent], now_ms: i64) -> Result<EnqueueReport> {+ let tx = self+ .conn+ .transaction_with_behavior(TransactionBehavior::Immediate)?;+ let (mut items, mut bytes): (i64, i64) = tx.query_row(+ "SELECT COUNT(*), COALESCE(SUM(body_bytes), 0) FROM pending",+ [],+ |r| Ok((r.get(0)?, r.get(1)?)),+ )?;+ // Replay protection is bounded, and the bound covers pending *and*+ // receipts: every pending item becomes a receipt when it is+ // acknowledged, so counting receipts alone would let the queue commit to+ // more protection than the cap allows. Pruning stays reserved for+ // entries past the 30-day window, so a full queue refuses new ids rather+ // than forgetting a recently delivered one. A duplicate is still+ // recognized while full, because recognizing it adds nothing.+ let receipts: i64 = tx.query_row("SELECT COUNT(*) FROM receipt", [], |r| r.get(0))?;+ let mut pins: i64 = tx.query_row("SELECT COUNT(*) FROM session_agent", [], |r| r.get(0))?;+ let mut report = EnqueueReport::default();+ let mut seen_keys: HashMap<&str, &str> = HashMap::new();+ let mut seen_sessions: HashMap<&str, &str> = HashMap::new();+ for event in events {+ // A session id belongs to exactly one wire agent. Two agents on one+ // native session is the producer bug the server can only answer with+ // an acknowledged SessionCollision drop.+ let bound: Option<String> = tx+ .query_row(+ "SELECT agent FROM session_agent WHERE session_id = ?1",+ params![event.session_id],+ |r| r.get(0),+ )+ .optional()?;+ let bound = bound.or_else(|| {+ seen_sessions+ .get(event.session_id.as_str())+ .map(|a| (*a).to_owned())+ });+ if bound.is_none() {+ pins += 1;+ if pins > MAX_SESSION_PINS {+ bail!(+ "session pin table is full: {MAX_SESSION_PINS} session(s) already pinned \+ to an agent. Nothing was enqueued and no pin was forgotten; pins are \+ released as they pass the 30-day retry window"+ );+ }+ }+ if let Some(bound) = bound+ && bound != event.agent+ {+ bail!(+ "session identity conflict: session {:?} is already bound to agent {:?} in \+ this queue, but item with event_id {} claims agent {:?}. Nothing was \+ enqueued; a native session belongs to one harness",+ event.session_id,+ bound,+ event.event_id,+ event.agent+ );+ }+ seen_sessions.insert(&event.session_id, &event.agent);++ if let Some(previous) = seen_keys.insert(&event.ingest_key, &event.body_sha256)+ && previous != event.body_sha256+ {+ bail!(collision_message(+ &event.ingest_key,+ "another item in this file"+ ));+ }+ let known: Option<String> = tx+ .query_row(+ "SELECT body_sha256 FROM pending WHERE ingest_key = ?1+ UNION ALL+ SELECT body_sha256 FROM receipt WHERE ingest_key = ?1",+ params![event.ingest_key],+ |r| r.get(0),+ )+ .optional()?;+ if let Some(known) = known {+ if known != event.body_sha256 {+ bail!(collision_message(+ &event.ingest_key,+ "an item already recorded in this queue"+ ));+ }+ report.recognized += 1;+ continue;+ }+ let body_bytes = event.body_json.len() as i64;+ items += 1;+ bytes += body_bytes;+ if items > MAX_PENDING_ITEMS || bytes > MAX_PENDING_BYTES {+ bail!(+ "queue is full: {items} items / {bytes} bytes would exceed the \+ {MAX_PENDING_ITEMS}-item / {MAX_PENDING_BYTES}-byte limit. Nothing was \+ enqueued and nothing was dropped; flush the queue first"+ );+ }+ // Reserve the receipt this item will need once it is acknowledged.+ let protected = receipts + items;+ if protected > MAX_RECEIPTS {+ bail!(+ "replay protection is full: {receipts} acknowledged key(s) plus {items} \+ pending would need {protected} slots, over the {MAX_RECEIPTS} limit. \+ Nothing was enqueued and nothing was forgotten; slots are released as \+ entries pass the 30-day retry window, or start a fresh --queue-dir"+ );+ }+ tx.execute(+ "INSERT INTO pending(+ ingest_key, event_id, agent, event, session_id, cwd,+ body_json, body_sha256, body_bytes, first_seen_ms)+ VALUES(?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10)",+ params![+ event.ingest_key,+ event.event_id,+ event.agent,+ event.event,+ event.session_id,+ event.cwd,+ event.body_json,+ event.body_sha256,+ body_bytes,+ now_ms,+ ],+ )?;+ report.accepted += 1;+ }+ for (session_id, agent) in seen_sessions {+ tx.execute(+ "INSERT INTO session_agent(session_id, agent, last_seen_ms) VALUES(?1, ?2, ?3)+ ON CONFLICT(session_id) DO UPDATE SET last_seen_ms = excluded.last_seen_ms",+ params![session_id, agent, now_ms],+ )?;+ }+ tx.commit()?;+ Ok(report)+ }++ /// Pick at most one pending head per `(agent, session_id)`, oldest first,+ /// within both an item count and a wire-byte budget.+ ///+ /// One head per session per batch is what makes a partial acknowledgement+ /// safe: two events of one session are never in flight together, so no ack+ /// subset can commit event 2 while event 1 is still pending, and a terminal+ /// event can never overtake an earlier one. `deferred` holds sessions this+ /// flush already stopped on; they are skipped without touching their order.+ pub fn select_batch(+ &self,+ limit: usize,+ byte_budget: usize,+ now_ms: i64,+ deferred: &HashSet<(String, String)>,+ cost_of: impl Fn(&PendingItem) -> usize,+ ) -> Result<Batch> {+ let limit = limit.clamp(1, crate::identity::MAX_BATCH_ITEMS);+ let mut stmt = self.conn.prepare(+ "SELECT seq, ingest_key, event_id, agent, event, session_id, body_json,+ body_bytes, first_seen_ms, first_attempt_ms+ FROM pending ORDER BY seq ASC",+ )?;+ let mut rows = stmt.query([])?;+ let mut seen: HashSet<(String, String)> = HashSet::new();+ let mut batch = Batch::default();+ let mut spent = 0usize;+ while let Some(row) = rows.next()? {+ if batch.items.len() >= limit {+ break;+ }+ let item = PendingItem {+ seq: row.get(0)?,+ ingest_key: row.get(1)?,+ event_id: row.get(2)?,+ agent: row.get(3)?,+ event: row.get(4)?,+ session_id: row.get(5)?,+ body_json: row.get(6)?,+ body_bytes: row.get(7)?,+ first_seen_ms: row.get(8)?,+ first_attempt_ms: row.get(9)?,+ };+ let session = item.session();+ if !seen.insert(session.clone()) {+ continue;+ }+ if deferred.contains(&session) {+ continue;+ }+ if is_expired(item.first_attempt_ms, now_ms) {+ batch.blocked_sessions += 1;+ continue;+ }+ let cost = cost_of(&item);+ if !batch.items.is_empty() && spent + cost > byte_budget {+ batch.budget_deferred += 1;+ continue;+ }+ debug_assert!(+ !TERMINAL_EVENTS.contains(&item.event.as_str()) || self.session_head(&item)?,+ "a terminal event was selected while its session had an older pending item"+ );+ spent += cost;+ batch.items.push(item);+ }+ Ok(batch)+ }++ fn session_head(&self, item: &PendingItem) -> Result<bool> {+ let older: i64 = self.conn.query_row(+ "SELECT COUNT(*) FROM pending WHERE agent = ?1 AND session_id = ?2 AND seq < ?3",+ params![item.agent, item.session_id, item.seq],+ |r| r.get(0),+ )?;+ Ok(older == 0)+ }++ /// Record the durable start of the retry window, **before** the request.+ ///+ /// `COALESCE` is the whole point: a restart, a lost ack, or a later retry+ /// never moves the clock forward, so the 30-day guard measures from the+ /// first time this event was actually put on the wire.+ pub fn stamp_attempt(&mut self, keys: &[String], now_ms: i64) -> Result<()> {+ let tx = self+ .conn+ .transaction_with_behavior(TransactionBehavior::Immediate)?;+ for key in keys {+ tx.execute(+ "UPDATE pending+ SET first_attempt_ms = COALESCE(first_attempt_ms, ?2),+ attempts = attempts + 1+ WHERE ingest_key = ?1",+ params![key, now_ms],+ )?;+ }+ tx.commit()?;+ Ok(())+ }++ /// Move acknowledged items to compact receipts, in one transaction.+ ///+ /// An acknowledgement means delivered *or* deliberately dropped by server+ /// policy (a capture-protocol drop, a subagent drop, a session-collision+ /// drop). It never promises an observation was written.+ pub fn confirm(&mut self, keys: &[String], now_ms: i64) -> Result<usize> {+ if keys.is_empty() {+ return Ok(0);+ }+ let tx = self+ .conn+ .transaction_with_behavior(TransactionBehavior::Immediate)?;+ let mut moved = 0;+ for key in keys {+ let row: Option<(String, Option<i64>, i64)> = tx+ .query_row(+ "SELECT body_sha256, first_attempt_ms, first_seen_ms+ FROM pending WHERE ingest_key = ?1",+ params![key],+ |r| Ok((r.get(0)?, r.get(1)?, r.get(2)?)),+ )+ .optional()?;+ let Some((body_sha256, first_attempt_ms, first_seen_ms)) = row else {+ continue;+ };+ tx.execute(+ "INSERT INTO receipt(ingest_key, body_sha256, first_attempt_ms, delivered_at_ms)+ VALUES(?1, ?2, ?3, ?4)+ ON CONFLICT(ingest_key) DO UPDATE SET delivered_at_ms = excluded.delivered_at_ms",+ params![+ key,+ body_sha256,+ first_attempt_ms.unwrap_or(first_seen_ms),+ now_ms+ ],+ )?;+ tx.execute("DELETE FROM pending WHERE ingest_key = ?1", params![key])?;+ moved += 1;+ }+ tx.commit()?;+ Ok(moved)+ }++ /// Charge one item with a delivery failure. The class is a short label,+ /// never a server body and never payload.+ pub fn record_failure(&mut self, key: &str, class: &str) -> Result<()> {+ let class: String = class.chars().filter(|c| !c.is_control()).take(80).collect();+ self.conn.execute(+ "UPDATE pending SET last_error = ?2 WHERE ingest_key = ?1",+ params![key, class],+ )?;+ Ok(())+ }++ /// Release expired receipts and session records without pending events.+ pub fn prune(&mut self, now_ms: i64) -> Result<usize> {+ let cutoff = now_ms.saturating_sub(RETRY_WINDOW_MS);+ let tx = self+ .conn+ .transaction_with_behavior(TransactionBehavior::Immediate)?;+ let receipts = tx.execute(+ "DELETE FROM receipt WHERE first_attempt_ms < ?1",+ params![cutoff],+ )?;+ let sessions = tx.execute(+ "DELETE FROM session_agent WHERE last_seen_ms < ?1+ AND session_id NOT IN (SELECT session_id FROM pending)",+ params![cutoff],+ )?;+ tx.commit()?;+ Ok(receipts + sessions)+ }++ /// Payload-free counters.+ pub fn stats(&self, now_ms: i64) -> Result<Stats> {+ let cutoff = now_ms.saturating_sub(RETRY_WINDOW_MS);+ let (pending_items, pending_bytes, oldest, max_attempts, attempted_items) =+ self.conn.query_row(+ "SELECT COUNT(*), COALESCE(SUM(body_bytes), 0), COALESCE(MIN(first_seen_ms), 0),+ COALESCE(MAX(attempts), 0), COUNT(first_attempt_ms)+ FROM pending",+ [],+ |r| {+ Ok((+ r.get::<_, i64>(0)?,+ r.get::<_, i64>(1)?,+ r.get::<_, i64>(2)?,+ r.get::<_, i64>(3)?,+ r.get::<_, i64>(4)?,+ ))+ },+ )?;+ let pending_sessions: i64 = self.conn.query_row(+ "SELECT COUNT(*) FROM (SELECT DISTINCT agent, session_id FROM pending)",+ [],+ |r| r.get(0),+ )?;+ let expired_items: i64 = self.conn.query_row(+ "SELECT COUNT(*) FROM pending WHERE first_attempt_ms IS NOT NULL+ AND first_attempt_ms <= ?1",+ params![cutoff],+ |r| r.get(0),+ )?;+ let receipts: i64 = self+ .conn+ .query_row("SELECT COUNT(*) FROM receipt", [], |r| r.get(0))?;+ let known_sessions: i64 =+ self.conn+ .query_row("SELECT COUNT(*) FROM session_agent", [], |r| r.get(0))?;+ Ok(Stats {+ pending_items,+ pending_bytes,+ pending_sessions,+ attempted_items,+ expired_items,+ oldest_pending_age_ms: if pending_items == 0 {+ 0+ } else {+ now_ms.saturating_sub(oldest)+ },+ max_attempts,+ receipts,+ known_sessions,+ })+ }+}++/// Past the retry window an event may not be auto-resent.+///+/// Refuse the boundary itself. This comparison depends on an accurate host+/// clock; a backwards clock change can extend retries past server key expiry.+pub fn is_expired(first_attempt_ms: Option<i64>, now_ms: i64) -> bool {+ match first_attempt_ms {+ Some(started) => now_ms.saturating_sub(started) >= RETRY_WINDOW_MS,+ None => false,+ }+}++fn collision_message(key: &str, other: &str) -> String {+ format!(+ "identity collision: ingest key {key} was already used by {other} with different content. \+ The same producer event id must always carry the same body; nothing was enqueued. \+ Body content is deliberately not shown. Per-body limit: {MAX_BODY_BYTES} bytes"+ )+}++/// What an existing file turned out to be.+///+/// Schema and identity commit together. Recovery therefore accepts an empty+/// database or an identified queue; generic table names do not establish ownership.+#[derive(Debug, Clone, Copy, PartialEq, Eq)]+enum DbState {+ /// A SQLite file with no user objects: empty, or rolled back to empty.+ Fresh,+ /// A relay queue of this exact schema version.+ Ready,+}++/// Classify an existing file before touching it. Never mutates.+fn classify(conn: &Connection, path: &Path) -> Result<DbState> {+ let refuse = |detail: String| -> anyhow::Error {+ anyhow::anyhow!(+ "{} is not a usable relay queue ({detail}); nothing was modified. \+ Point --queue-dir at an empty directory or restore the original queue",+ path.display()+ )+ };+ // Tables, views, triggers and standalone indexes all count: any user object+ // means the file belongs to something, and that something is not this relay+ // unless it also carries the identity row.+ let objects: Result<i64, rusqlite::Error> = conn.query_row(+ "SELECT COUNT(*) FROM sqlite_master WHERE name NOT LIKE 'sqlite_%'",+ [],+ |r| r.get(0),+ );+ // A file that is not a SQLite database fails right here, before any write.+ let objects = objects.map_err(|e| refuse(format!("cannot read its object list: {e}")))?;+ if objects == 0 {+ return Ok(DbState::Fresh);+ }+ let rows: Result<Vec<(String, String)>, rusqlite::Error> = (|| {+ let mut stmt =+ conn.prepare("SELECT key, value FROM meta WHERE key IN ('identity','schema_version')")?;+ let mapped = stmt.query_map([], |r| Ok((r.get(0)?, r.get(1)?)))?;+ mapped.collect()+ })();+ let meta: HashMap<String, String> = rows+ .map_err(|e| refuse(format!("it carries no readable relay metadata: {e}")))?+ .into_iter()+ .collect();+ match (+ meta.get("identity").map(String::as_str),+ meta.get("schema_version").map(String::as_str),+ ) {+ (Some(IDENTITY), Some(SCHEMA_VERSION)) => Ok(DbState::Ready),+ (Some(IDENTITY), Some(other)) => Err(refuse(format!(+ "schema version {other} but this build speaks {SCHEMA_VERSION}"+ ))),+ (Some(other), _) => Err(refuse(format!("identity is {other:?}"))),+ _ => Err(refuse(+ "it holds user objects but no relay identity row".into(),+ )),+ }+}++fn read_binding(conn: &Connection) -> Result<Option<Binding>> {+ Ok(conn+ .query_row(+ "SELECT server_url, producer, actor, workspace, project FROM binding WHERE id = 1",+ [],+ |r| {+ Ok(Binding {+ server_url: r.get(0)?,+ producer: r.get(1)?,+ actor: r.get(2)?,+ workspace: r.get(3)?,+ project: r.get(4)?,+ })+ },+ )+ .optional()?)+}diff --git a/companions/ai-memory-relay/src/relay.rs b/companions/ai-memory-relay/src/relay.rsnew file mode 100644index 00000000..c1b7482a--- /dev/null+++ b/companions/ai-memory-relay/src/relay.rs@@ -0,0 +1,556 @@+//! CLI command operations and reports.+//!+//! Reports include queue metadata and counts. Event bodies and bearer tokens+//! are kept out of diagnostics.++use std::collections::HashSet;+use std::io::Read;+use std::path::Path;+use std::time::{Duration, Instant};++use anyhow::{Context, Result, bail};++use crate::ack::{self, BatchAck};+use crate::fsguard;+use crate::http::{self, BatchItem, Sender, Token};+use crate::identity::{self, InputEvent, MAX_BATCH_ITEMS, ValidEvent};+use crate::queue::{self, Batch, BindOutcome, Binding, PendingItem, Queue};++/// Largest `enqueue --file` input accepted, before parsing.+pub const MAX_INPUT_BYTES: u64 = 32 * 1024 * 1024;+/// Most events accepted from one input file.+pub const MAX_INPUT_ITEMS: usize = 10_000;+/// Wire-byte budget for one batch. The server's `/hook` body limit is 10 MiB+/// (`serve.rs`); core's own spool drain uses 8 MiB, and so does this.+pub const MAX_BATCH_BYTES: usize = 8 * 1024 * 1024;+/// JSON framing charged per item on top of its URL and body: `{"url":"","body":},`.+const ITEM_FRAMING_BYTES: usize = 32;+/// Transport retries per batch, on top of the first attempt.+const TRANSPORT_RETRIES: usize = 2;+/// Request timeout budget per item; a batch gets this times its item count.+const PER_EVENT_TIMEOUT: Duration = Duration::from_secs(2);+/// Absolute ceiling for one batch request, however many items it carries.+const MAX_BATCH_TIMEOUT: Duration = Duration::from_secs(120);+/// Wall-clock ceiling for one whole flush.+const TOTAL_BUDGET: Duration = Duration::from_secs(900);+/// Ceiling for one backoff sleep between transport retries.+const MAX_BACKOFF: Duration = Duration::from_secs(2);+/// TCP connect timeout.+const CONNECT_TIMEOUT: Duration = Duration::from_secs(10);++/// The one knob a `flush` exposes. Everything else is a constant above, so the+/// public surface cannot be tuned into an unbounded run.+#[derive(Debug, Clone)]+pub struct FlushOptions {+ /// Batches attempted in one flush. Finite by construction.+ pub max_batches: usize,+}++impl Default for FlushOptions {+ fn default() -> Self {+ Self { max_batches: 64 }+ }+}++/// What a command wants the process to exit with.+#[derive(Debug, Clone, PartialEq, Eq)]+pub struct Report {+ pub summary: Vec<String>,+ /// Work remains: unacknowledged items are still queued.+ pub pending: bool,+ /// Something went wrong. The queue is intact either way.+ pub failure: Option<String>,+}++impl Report {+ fn ok(summary: Vec<String>) -> Self {+ Self {+ summary,+ pending: false,+ failure: None,+ }+ }++ /// 0 = drained, 2 = failure, 3 = nothing lost but work remains.+ pub fn exit_code(&self) -> i32 {+ if self.failure.is_some() {+ 2+ } else if self.pending {+ 3+ } else {+ 0+ }+ }+}++/// `init`: bind a queue directory to one destination, producer, actor and scope.+pub fn init(+ dir: &Path,+ server_url: &str,+ producer: &str,+ actor: &str,+ workspace: &str,+ project: &str,+) -> Result<Report> {+ identity::check_producer(producer).map_err(anyhow::Error::msg)?;+ identity::check_actor(actor).map_err(anyhow::Error::msg)?;+ identity::check_scope("workspace", workspace).map_err(anyhow::Error::msg)?;+ identity::check_scope("project", project).map_err(anyhow::Error::msg)?;+ let binding = Binding {+ server_url: http::normalize_server_url(server_url)?,+ producer: producer.to_owned(),+ actor: actor.to_owned(),+ workspace: workspace.to_owned(),+ project: project.to_owned(),+ };+ let dir = fsguard::prepare_queue_dir(dir)?;+ let mut queue = Queue::open(&dir)?;+ let outcome = queue.bind(&binding, crate::now_ms())?;+ let verb = match outcome {+ BindOutcome::Created => "bound",+ BindOutcome::Recognized => "already bound (identical)",+ };+ Ok(Report::ok(vec![+ format!("queue {verb}: {}", queue.path().display()),+ format!("server: {}", binding.server_url),+ format!("producer: {}", binding.producer),+ format!("actor: {}", binding.actor),+ format!("scope: {}/{}", binding.workspace, binding.project),+ ]))+}++/// `enqueue`: validate a whole file, then persist it all-or-nothing.+pub fn enqueue(dir: &Path, file: &Path) -> Result<Report> {+ let dir = fsguard::prepare_queue_dir(dir)?;+ let mut queue = Queue::open(&dir)?;+ let binding = queue.binding()?;+ let events = read_input(file, &binding)?;+ let report = queue.enqueue(&events, crate::now_ms())?;+ let stats = queue.stats(crate::now_ms())?;+ Ok(Report::ok(vec![+ format!(+ "enqueued {} event(s), recognized {} duplicate(s)",+ report.accepted, report.recognized+ ),+ format!(+ "pending now: {} event(s) across {} session(s), {} byte(s)",+ stats.pending_items, stats.pending_sessions, stats.pending_bytes+ ),+ ]))+}++/// Read and validate an input file without ever quoting its content back.+fn read_input(file: &Path, binding: &Binding) -> Result<Vec<ValidEvent>> {+ let meta =+ std::fs::metadata(file).with_context(|| format!("read --file {}", file.display()))?;+ if meta.len() > MAX_INPUT_BYTES {+ bail!(+ "--file {} is {} bytes, over the {MAX_INPUT_BYTES}-byte input limit",+ file.display(),+ meta.len()+ );+ }+ let mut raw = Vec::new();+ std::fs::File::open(file)+ .with_context(|| format!("open --file {}", file.display()))?+ .take(MAX_INPUT_BYTES + 1)+ .read_to_end(&mut raw)+ .with_context(|| format!("read --file {}", file.display()))?;+ // The metadata check above is an early out; this is the one that counts,+ // because the file can grow between `stat` and `read`.+ if raw.len() as u64 > MAX_INPUT_BYTES {+ bail!(+ "--file {} is over the {MAX_INPUT_BYTES}-byte input limit",+ file.display()+ );+ }+ let input: Vec<InputEvent> = serde_json::from_slice(&raw).map_err(|e| {+ // Category plus position only. `Display` on a serde error can quote the+ // offending value ("invalid type: string \"...\""), and an event body is+ // exactly the thing that must not reach a terminal or a log.+ anyhow::anyhow!(+ "--file {} is not a valid event array ({} error at line {}, column {}): expected \+ [{{\"event_id\",\"agent\",\"event\",\"body\"}}, ...]",+ file.display(),+ match e.classify() {+ serde_json::error::Category::Io => "io",+ serde_json::error::Category::Syntax => "syntax",+ serde_json::error::Category::Data => "schema",+ serde_json::error::Category::Eof => "truncated input",+ },+ e.line(),+ e.column()+ )+ })?;+ if input.is_empty() {+ bail!("--file {} contains no events", file.display());+ }+ if input.len() > MAX_INPUT_ITEMS {+ bail!(+ "--file {} carries {} events, over the {MAX_INPUT_ITEMS}-event input limit",+ file.display(),+ input.len()+ );+ }+ input+ .into_iter()+ .enumerate()+ .map(|(index, event)| {+ identity::validate(index, event, &binding.producer, &binding.actor)+ .map_err(anyhow::Error::msg)+ })+ .collect()+}++/// `status`: payload-free counters for the queue, as one stable JSON object.+///+/// Machine-readable on purpose: an operator script (and the end-to-end smoke+/// test) reads `pending_items` from it. Every field here is a count, a name the+/// operator chose, or a path. No event body, no cwd, no token.+pub fn status(dir: &Path) -> Result<Report> {+ let dir = fsguard::prepare_queue_dir(dir)?;+ let queue = Queue::open(&dir)?;+ let binding = queue.binding()?;+ let stats = queue.stats(crate::now_ms())?;+ let document = serde_json::json!({+ "queue": queue.path().display().to_string(),+ "server_url": binding.server_url,+ "producer": binding.producer,+ "actor": binding.actor,+ "workspace": binding.workspace,+ "project": binding.project,+ "pending_items": stats.pending_items,+ "pending_bytes": stats.pending_bytes,+ "pending_sessions": stats.pending_sessions,+ "attempted_items": stats.attempted_items,+ "expired_items": stats.expired_items,+ "oldest_pending_age_ms": stats.oldest_pending_age_ms,+ "max_attempts": stats.max_attempts,+ "receipts": stats.receipts,+ "known_sessions": stats.known_sessions,+ "limits": {+ "pending_items": queue::MAX_PENDING_ITEMS,+ "pending_bytes": queue::MAX_PENDING_BYTES,+ "receipts": queue::MAX_RECEIPTS,+ "known_sessions": queue::MAX_SESSION_PINS,+ "body_bytes": crate::identity::MAX_BODY_BYTES,+ "batch_items": MAX_BATCH_ITEMS,+ "batch_bytes": MAX_BATCH_BYTES,+ },+ "retry_window_ms": crate::identity::RETRY_WINDOW_MS,+ "ack_means": "delivered or dropped by server policy, not that an observation was written",+ });+ Ok(Report::ok(vec![serde_json::to_string_pretty(&document)?]))+}++/// `flush`: deliver pending events, oldest first, one head per session per batch.+pub fn flush(dir: &Path, options: &FlushOptions) -> Result<Report> {+ let dir = fsguard::prepare_queue_dir(dir)?;+ let lock_path = dir.join("flush.lock");+ fsguard::check_queue_file(&lock_path)?;+ if !lock_path.exists() {+ fsguard::create_private_file(&lock_path)?;+ fsguard::check_queue_file(&lock_path)?;+ }+ let lock = std::fs::OpenOptions::new()+ .truncate(false)+ .write(true)+ .open(&lock_path)+ .with_context(|| format!("open {}", lock_path.display()))?;+ // Serialize flushes across processes. The lock file itself is never removed:+ // releasing the lock is dropping the handle.+ if fs2::FileExt::try_lock_exclusive(&lock).is_err() {+ bail!(+ "another flush already holds {}; run one flush at a time",+ lock_path.display()+ );+ }+ let result = flush_locked(&dir, options);+ let _ = fs2::FileExt::unlock(&lock);+ result+}++fn flush_locked(dir: &Path, options: &FlushOptions) -> Result<Report> {+ let mut queue = Queue::open(dir)?;+ let binding = queue.binding()?;+ queue.prune(crate::now_ms())?;+ let token = Token::from_env()?;+ let authenticated = token.is_some();+ let sender = Sender::new(binding.server_url.clone(), token, CONNECT_TIMEOUT)?;++ let started = Instant::now();+ let mut deferred: HashSet<(String, String)> = HashSet::new();+ let mut delivered = 0usize;+ let mut batches = 0usize;+ let mut blocked_sessions = 0usize;+ let mut failure: Option<String> = None;+ let mut backed_off = false;++ for _ in 0..options.max_batches {+ // Cheap pre-check, so an exhausted budget does not buy another round of+ // selection and stamping. The binding one is taken just before the send.+ if TOTAL_BUDGET.checked_sub(started.elapsed()).is_none() {+ break;+ }+ let now = crate::now_ms();+ let base = binding.server_url.clone();+ let for_cost = binding.clone();+ let batch: Batch =+ queue.select_batch(MAX_BATCH_ITEMS, MAX_BATCH_BYTES, now, &deferred, |item| {+ item_cost(&base, &for_cost, item)+ })?;+ blocked_sessions = batch.blocked_sessions;+ if batch.items.is_empty() {+ break;+ }+ batches += 1;+ let keys: Vec<String> = batch.items.iter().map(|i| i.ingest_key.clone()).collect();+ // Durable, and before the request: a lost ack must not restart the+ // 30-day clock on the next run.+ queue.stamp_attempt(&keys, now)?;+ let items: Vec<BatchItem> = batch+ .items+ .iter()+ .map(|item| {+ Ok(BatchItem {+ url: http::item_url(&binding.server_url, &binding, item),+ body: serde_json::from_str(&item.body_json)+ .context("stored body is no longer valid JSON")?,+ })+ })+ .collect::<Result<Vec<_>>>()?;+ // Selection checked the retry window once; a retry inside this batch can+ // still cross it. Carry the batch's tightest expiry into the sender so+ // every attempt is re-checked against it.+ //+ // Both clocks are read here, after stamping and JSON building: measuring+ // from a `now` captured before that preparation would hand the batch+ // however long the preparation took as extra allowance.+ let send_now = crate::now_ms();+ let ttl_left = batch+ .items+ .iter()+ .map(|item| ttl_remaining(item.first_attempt_ms.unwrap_or(now), send_now))+ .min()+ .unwrap_or(Duration::ZERO);+ let Some(remaining) = TOTAL_BUDGET.checked_sub(started.elapsed()) else {+ break;+ };+ let delivery = match send_with_retries(&sender, &items, remaining, ttl_left) {+ Ok(delivery) => delivery,+ Err(e) => {+ // Transport failure: everything stays pending, by definition.+ for item in &batch.items {+ queue.record_failure(&item.ingest_key, "transport")?;+ }+ failure = Some(format!("{e} (all {} item(s) kept)", batch.items.len()));+ break;+ }+ };++ // An ack is only meaningful on 200 and 429. Every other status keeps the+ // whole batch, whatever its body claims.+ if !matches!(delivery.status, 200 | 429) {+ let detail = match delivery.status {+ 401 | 403 => {+ if authenticated {+ "server rejected the bearer token (AI_MEMORY_AUTH_TOKEN)"+ } else {+ "server requires authentication; set AI_MEMORY_AUTH_TOKEN"+ }+ }+ 413 => {+ "the server refused the batch as too large. The relay's own batch bounds \+ are fixed; record smaller event bodies at the producer, or raise the \+ server's body limit"+ }+ _ => "unexpected status",+ };+ for item in &batch.items {+ queue.record_failure(&item.ingest_key, &format!("http {}", delivery.status))?;+ }+ failure = Some(format!(+ "HTTP {} from /hook/batch: {detail}; all {} item(s) kept pending",+ delivery.status,+ batch.items.len()+ ));+ break;+ }++ let parsed: BatchAck = match serde_json::from_slice(&delivery.body) {+ Ok(parsed) => parsed,+ Err(_) => {+ for item in &batch.items {+ queue.record_failure(&item.ingest_key, "malformed ack")?;+ }+ failure = Some(format!(+ "HTTP {} from /hook/batch with an unreadable ack ({} byte(s)); \+ all {} item(s) kept pending",+ delivery.status,+ delivery.body.len(),+ batch.items.len()+ ));+ break;+ }+ };+ let accepted = match ack::validate(batch.items.len(), &parsed) {+ Ok(accepted) => accepted,+ Err(rejected) => {+ for item in &batch.items {+ queue.record_failure(&item.ingest_key, "inconsistent ack")?;+ }+ failure = Some(format!(+ "HTTP {} from /hook/batch with an inconsistent ack ({rejected}); \+ all {} item(s) kept pending",+ delivery.status,+ batch.items.len()+ ));+ break;+ }+ };++ // Only now, after the whole response was validated, does anything leave+ // the queue.+ let confirmed: Vec<String> = accepted+ .iter()+ .filter_map(|idx| batch.items.get(*idx))+ .map(|item| item.ingest_key.clone())+ .collect();+ delivered += queue.confirm(&confirmed, crate::now_ms())?;++ if let Some(failed_index) = parsed.failed_index+ && let Some(item) = batch.items.get(failed_index)+ {+ queue.record_failure(&item.ingest_key, "server reported failed_index")?;+ }+ // The server stops at failed_index. Keep later, untried sessions+ // eligible; otherwise one failed head could block them on every flush.+ // Defer the failed head and earlier rate-limited items for this flush.+ for (position, item) in batch.items.iter().enumerate() {+ if accepted.contains(&position) {+ continue;+ }+ let untried = parsed.failed_index.is_some_and(|failed| position > failed);+ if !untried {+ deferred.insert(item.session());+ }+ }++ if delivery.status == 429 {+ backed_off = true;+ break;+ }+ }++ let stats = queue.stats(crate::now_ms())?;+ let mut summary = vec![format!(+ "acknowledged {delivered} event(s) in {batches} batch(es); {} still pending across {} session(s)",+ stats.pending_items, stats.pending_sessions+ )];+ if backed_off {+ summary.push(+ "server answered 429: the acknowledged items were applied and the flush stopped. \+ Back off before the next run"+ .to_owned(),+ );+ }+ if !deferred.is_empty() {+ summary.push(format!(+ "{} session(s) deferred to a later flush (a failed or rate-limited head); \+ their later events were never sent ahead of it",+ deferred.len()+ ));+ }+ if blocked_sessions > 0 {+ summary.push(format!(+ "{blocked_sessions} session(s) held: their oldest event passed the 30-day retry \+ window. The relay will not resend those automatically; they are retained for you"+ ));+ }+ summary.push(+ "acknowledged means delivered or dropped by server policy, not that an observation \+ was written"+ .to_owned(),+ );+ Ok(Report {+ summary,+ pending: stats.pending_items > 0,+ failure,+ })+}++/// How long an event may still be auto-resent, measured from its first durable+/// attempt. Zero means the 30-day window is spent.+///+/// Accuracy depends on a stable host clock: the relay carries no time source of+/// its own, so a clock that jumps stretches or shortens this measurement.+pub fn ttl_remaining(first_attempt_ms: i64, now_ms: i64) -> Duration {+ let spent = now_ms.saturating_sub(first_attempt_ms);+ let left = identity::RETRY_WINDOW_MS.saturating_sub(spent);+ Duration::from_millis(u64::try_from(left).unwrap_or(0))+}++/// Retry a batch a finite number of times under one shared deadline.+///+/// Two clocks bound it. `remaining` is the flush budget left when the batch+/// started; `ttl_left` is how long the batch's oldest item may still be resent.+/// Every request *and* every backoff sleep is drawn from the tighter of the two+/// and recomputed, so three attempts can neither overrun the budget nor put an+/// event on the wire after its retry window closed mid-flush.+fn send_with_retries(+ sender: &Sender,+ items: &[BatchItem],+ remaining: Duration,+ ttl_left: Duration,+) -> Result<http::Delivery> {+ let start = Instant::now();+ let deadline = start + remaining.min(ttl_left);+ let ttl_deadline = start + ttl_left;+ let mut attempt = 0usize;+ loop {+ if Instant::now() >= ttl_deadline {+ bail!(+ "hook batch not sent: the batch's oldest event reached the 30-day retry window \+ mid-flush; it is retained, not resent"+ );+ }+ let left = deadline.saturating_duration_since(Instant::now());+ if left.is_zero() {+ bail!("hook batch transport failure: flush budget exhausted");+ }+ match sender.post_batch(items, batch_timeout(items.len(), left)) {+ Ok(delivery) => return Ok(delivery),+ Err(e) => {+ if attempt >= TRANSPORT_RETRIES {+ return Err(e);+ }+ let backoff = Duration::from_millis(250)+ .saturating_mul(1u32 << attempt.min(8))+ .min(MAX_BACKOFF)+ .min(deadline.saturating_duration_since(Instant::now()));+ if backoff.is_zero() {+ return Err(e);+ }+ attempt += 1;+ std::thread::sleep(backoff);+ }+ }+ }+}++/// Wire cost of one item, used for the batch byte budget.+pub fn item_cost(base: &str, binding: &Binding, item: &PendingItem) -> usize {+ http::item_url(base, binding, item).len() + item.body_json.len() + ITEM_FRAMING_BYTES+}++/// Per-event timeout scaled by item count, capped twice: by an absolute maximum+/// and by whatever is left of the flush budget. Mirrors core's spool drain.+pub fn batch_timeout(items: usize, remaining: Duration) -> Duration {+ let items = u32::try_from(items.max(1)).unwrap_or(u32::MAX);+ PER_EVENT_TIMEOUT+ .checked_mul(items)+ .unwrap_or(Duration::MAX)+ .min(MAX_BATCH_TIMEOUT)+ .min(remaining)+ .max(Duration::from_millis(1))+}diff --git a/companions/ai-memory-relay/tests/relay.rs b/companions/ai-memory-relay/tests/relay.rsnew file mode 100644index 00000000..3ef35e58--- /dev/null+++ b/companions/ai-memory-relay/tests/relay.rs@@ -0,0 +1,1342 @@+//! Behavioral tests for the relay.+//!+//! Every fixture is kept (`TempDir::keep()`): when one of these fails, the queue+//! database and the request bodies it produced are the evidence, and the test+//! prints where they are. Nothing here deletes a file.+//!+//! Scripted HTTP responses cover partial acknowledgements and delivery errors.+//! The real-server test in tests/e2e/external_relay_smoke.py checks persistence.++use std::collections::HashMap;+use std::io::{Read, Write};+use std::net::{SocketAddr, TcpListener, TcpStream};+use std::path::{Path, PathBuf};+use std::sync::{Arc, Mutex};+use std::thread;++use ai_memory_relay::ack::{self, BatchAck};+use ai_memory_relay::identity::{self, InputEvent, ValidEvent};+use ai_memory_relay::queue::Queue;+use ai_memory_relay::relay::{self, FlushOptions};++// ---------------------------------------------------------------- fixtures++/// A kept sandbox. The path is printed so a failure points at the evidence.+fn fixture(name: &str) -> PathBuf {+ let root = tempfile::TempDir::new().unwrap().keep();+ let root = root.join(name);+ std::fs::create_dir_all(&root).unwrap();+ println!("fixture {name}: {}", root.display());+ root+}++fn queue_dir(root: &Path) -> PathBuf {+ root.join("queue")+}++fn bind(root: &Path, server: &str) -> PathBuf {+ let dir = queue_dir(root);+ relay::init(&dir, server, "example.runtime", "operator-a", "team", "app").unwrap();+ dir+}++fn event(event_id: &str, agent: &str, name: &str, session: &str) -> serde_json::Value {+ serde_json::json!({+ "event_id": event_id,+ "agent": agent,+ "event": name,+ "body": {"session_id": session, "cwd": "/work/app", "prompt": "continue"},+ })+}++fn write_events(root: &Path, file: &str, events: serde_json::Value) -> PathBuf {+ let path = root.join(file);+ std::fs::write(&path, serde_json::to_vec_pretty(&events).unwrap()).unwrap();+ path+}++fn enqueue(dir: &Path, root: &Path, file: &str, events: serde_json::Value) -> anyhow::Result<()> {+ let path = write_events(root, file, events);+ relay::enqueue(dir, &path).map(|_| ())+}++fn valid(event_id: &str, agent: &str, name: &str, session: &str) -> ValidEvent {+ let input: InputEvent = serde_json::from_value(event(event_id, agent, name, session)).unwrap();+ identity::validate(0, input, "example.runtime", "operator-a").unwrap()+}++/// Read through the public status surface rather than reopening the database.+fn pending_count(dir: &Path) -> i64 {+ let report = relay::status(dir).unwrap();+ let document: serde_json::Value = serde_json::from_str(&report.summary[0]).unwrap();+ document["pending_items"].as_i64().unwrap()+}++// ---------------------------------------------------------------- HTTP stub++/// One scripted response.+enum Reply {+ /// Status plus a JSON body.+ Json(u16, String),+ /// `200 {"accepted": <however many items arrived>}`. Used where the test is+ /// about batching, not about a specific ack shape.+ AcceptAll,+ /// Accept the request, read it, then close without answering: the shape of a+ /// lost response after the server already committed the batch.+ Close,+ /// A 302 the relay must refuse to follow.+ Redirect(String),+}++struct Stub {+ addr: SocketAddr,+ bodies: Arc<Mutex<Vec<serde_json::Value>>>,+ heads: Arc<Mutex<Vec<String>>>,+}++impl Stub {+ fn url(&self) -> String {+ format!("http://{}", self.addr)+ }++ fn bodies(&self) -> Vec<serde_json::Value> {+ self.bodies.lock().unwrap().clone()+ }++ fn heads(&self) -> Vec<String> {+ self.heads.lock().unwrap().clone()+ }++ /// Event ids, per request, in wire order.+ fn sent_event_ids(&self) -> Vec<Vec<String>> {+ self.bodies()+ .iter()+ .map(|batch| {+ batch+ .as_array()+ .unwrap()+ .iter()+ .map(|item| {+ query_of(item["url"].as_str().unwrap())+ .get("ingest_key")+ .cloned()+ .unwrap()+ })+ .collect()+ })+ .collect()+ }+}++fn stub(replies: Vec<Reply>) -> Stub {+ let listener = TcpListener::bind("127.0.0.1:0").unwrap();+ let addr = listener.local_addr().unwrap();+ let bodies = Arc::new(Mutex::new(Vec::new()));+ let heads = Arc::new(Mutex::new(Vec::new()));+ let (b, h) = (Arc::clone(&bodies), Arc::clone(&heads));+ thread::spawn(move || {+ for reply in replies {+ let Ok((mut socket, _)) = listener.accept() else {+ return;+ };+ let (head, body) = read_request(&mut socket);+ h.lock().unwrap().push(head);+ let mut items = 0usize;+ if let Ok(parsed) = serde_json::from_slice::<serde_json::Value>(&body) {+ items = parsed.as_array().map(Vec::len).unwrap_or(0);+ b.lock().unwrap().push(parsed);+ }+ match reply {+ Reply::Json(status, payload) => respond(&mut socket, status, &payload),+ Reply::AcceptAll => {+ respond(&mut socket, 200, &format!(r#"{{"accepted":{items}}}"#))+ }+ Reply::Redirect(location) => {+ let _ = write!(+ socket,+ "HTTP/1.1 302 Found\r\nlocation: {location}\r\ncontent-length: 0\r\n\+ connection: close\r\n\r\n"+ );+ let _ = socket.flush();+ }+ Reply::Close => drop(socket),+ }+ }+ });+ Stub {+ addr,+ bodies,+ heads,+ }+}++fn read_request(socket: &mut TcpStream) -> (String, Vec<u8>) {+ let mut bytes = Vec::new();+ let mut buffer = [0u8; 8192];+ let header_end = loop {+ let Ok(read) = socket.read(&mut buffer) else {+ return (String::new(), Vec::new());+ };+ if read == 0 {+ return (String::from_utf8_lossy(&bytes).to_string(), Vec::new());+ }+ bytes.extend_from_slice(&buffer[..read]);+ if let Some(at) = bytes.windows(4).position(|w| w == b"\r\n\r\n") {+ break at + 4;+ }+ };+ let head = String::from_utf8_lossy(&bytes[..header_end]).to_string();+ let length = head+ .lines()+ .find_map(|line| {+ let (name, value) = line.split_once(':')?;+ name.eq_ignore_ascii_case("content-length")+ .then(|| value.trim().parse::<usize>().ok())?+ })+ .unwrap_or(0);+ while bytes.len() - header_end < length {+ let Ok(read) = socket.read(&mut buffer) else {+ break;+ };+ if read == 0 {+ break;+ }+ bytes.extend_from_slice(&buffer[..read]);+ }+ let body = bytes[header_end..].to_vec();+ (head, body)+}++fn respond(socket: &mut TcpStream, status: u16, body: &str) {+ let reason = match status {+ 200 => "OK",+ 401 => "Unauthorized",+ 413 => "Payload Too Large",+ 429 => "Too Many Requests",+ 500 => "Internal Server Error",+ _ => "Status",+ };+ let _ = write!(+ socket,+ "HTTP/1.1 {status} {reason}\r\ncontent-type: application/json\r\n\+ content-length: {}\r\nconnection: close\r\n\r\n{body}",+ body.len()+ );+ let _ = socket.flush();+}++fn query_of(url: &str) -> HashMap<String, String> {+ let query = url.split_once('?').map(|(_, q)| q).unwrap_or_default();+ url::form_urlencoded::parse(query.as_bytes())+ .map(|(k, v)| (k.into_owned(), v.into_owned()))+ .collect()+}++fn flush(dir: &Path) -> ai_memory_relay::relay::Report {+ relay::flush(dir, &FlushOptions::default()).unwrap()+}++// ------------------------------------------------------------- ack contract++#[test]+fn ack_releases_the_contiguous_prefix_when_indices_are_absent() {+ let parsed: BatchAck = serde_json::from_str(r#"{"accepted":2}"#).unwrap();+ assert_eq!(ack::validate(4, &parsed).unwrap(), vec![0, 1]);+}++#[test]+fn ack_releases_exactly_the_reported_indices_when_they_have_a_gap() {+ // The shape a per-source rate limit produces: item 1 skipped, 2 committed.+ let parsed: BatchAck =+ serde_json::from_str(r#"{"accepted":1,"accepted_indices":[0,2]}"#).unwrap();+ assert_eq!(ack::validate(3, &parsed).unwrap(), vec![0, 2]);+}++#[test]+fn ack_accepts_an_explicitly_empty_index_list() {+ let parsed: BatchAck = serde_json::from_str(r#"{"accepted":0,"accepted_indices":[]}"#).unwrap();+ assert_eq!(ack::validate(3, &parsed).unwrap(), Vec::<usize>::new());+}++#[test]+fn an_inconsistent_ack_preserves_the_whole_batch() {+ // Each of these would otherwise release an item the server never committed.+ let cases = [+ // index outside the batch+ (3, r#"{"accepted":0,"accepted_indices":[0,9]}"#),+ // duplicate index+ (3, r#"{"accepted":1,"accepted_indices":[0,0]}"#),+ // descending indexes+ (3, r#"{"accepted":0,"accepted_indices":[2,1]}"#),+ // `accepted` disagreeing with the contiguous prefix+ (3, r#"{"accepted":2,"accepted_indices":[0,2]}"#),+ // prefix longer than the batch+ (2, r#"{"accepted":5}"#),+ // failure outside the batch+ (2, r#"{"accepted":1,"failed_index":7}"#),+ // the failed item also claimed as accepted+ (+ 3,+ r#"{"accepted":0,"accepted_indices":[1],"failed_index":1}"#,+ ),+ // an acceptance after the item the server stopped on+ (+ 3,+ r#"{"accepted":0,"accepted_indices":[2],"failed_index":1}"#,+ ),+ ];+ for (len, payload) in cases {+ let parsed: BatchAck = serde_json::from_str(payload).unwrap();+ assert!(+ ack::validate(len, &parsed).is_err(),+ "should have been refused: {payload}"+ );+ }+}++#[test]+fn an_ack_without_accepted_is_unreadable_rather_than_zero() {+ // Defaulting a missing `accepted` to 0 would be safe; defaulting it to+ // anything else would not. Parsing must fail so the caller keeps the batch.+ assert!(serde_json::from_str::<BatchAck>(r#"{"failed_index":0}"#).is_err());+}++// --------------------------------------------------------- delivery outcomes++#[test]+fn a_partial_noncontiguous_ack_releases_only_the_acknowledged_items() {+ let root = fixture("partial-ack");+ let server = stub(vec![+ Reply::Json(200, r#"{"accepted":1,"accepted_indices":[0,2]}"#.into()),+ Reply::Json(200, r#"{"accepted":1}"#.into()),+ Reply::Json(200, r#"{"accepted":0,"accepted_indices":[]}"#.into()),+ ]);+ let dir = bind(&root, &server.url());+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([+ event("e-a", "claude-code", "session-start", "s-a"),+ event("e-b", "claude-code", "session-start", "s-b"),+ event("e-c", "codex", "session-start", "s-c"),+ ]),+ )+ .unwrap();++ let report = flush(&dir);+ assert!(report.failure.is_none(), "{report:?}");+ // s-b was skipped by the server, so exactly one event is still queued.+ assert_eq!(pending_count(&dir), 1);+ assert!(report.pending);+ assert_eq!(report.exit_code(), 3);+}++#[test]+fn a_lost_response_keeps_the_batch_and_retries_the_same_ingest_key() {+ let root = fixture("lost-response");+ // Three closes: the first attempt plus both transport retries.+ let server = stub(vec![+ Reply::Close,+ Reply::Close,+ Reply::Close,+ Reply::Json(200, r#"{"accepted":1}"#.into()),+ ]);+ let dir = bind(&root, &server.url());+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([event("e-1", "claude-code", "session-start", "s-1")]),+ )+ .unwrap();++ let first = flush(&dir);+ assert!(first.failure.is_some(), "a lost response is a failure");+ assert_eq!(pending_count(&dir), 1, "nothing may be released");++ let second = flush(&dir);+ assert!(second.failure.is_none(), "{second:?}");+ assert_eq!(pending_count(&dir), 0);++ let sent = server.sent_event_ids();+ assert_eq!(sent.len(), 4, "3 attempts then the successful retry");+ assert!(+ sent.windows(2).all(|pair| pair[0] == pair[1]),+ "the retry must carry the identical ingest key: {sent:?}"+ );+}++#[test]+fn a_reopened_queue_recognizes_an_acknowledged_event() {+ let root = fixture("restart-after-ack");+ let server = stub(vec![Reply::Json(200, r#"{"accepted":1}"#.into())]);+ let dir = bind(&root, &server.url());+ let payload = serde_json::json!([event("e-1", "claude-code", "session-start", "s-1")]);+ enqueue(&dir, &root, "in.json", payload.clone()).unwrap();+ flush(&dir);+ assert_eq!(pending_count(&dir), 0);++ // Reopening the queue must find the persisted receipt.+ enqueue(&dir, &root, "in.json", payload).unwrap();+ assert_eq!(pending_count(&dir), 0, "a delivered id must not come back");+ assert_eq!(server.bodies().len(), 1, "and must not be re-sent");+}++#[test]+fn an_unauthenticated_rejection_keeps_everything_pending() {+ let root = fixture("auth-rejected");+ let server = stub(vec![Reply::Json(401, r#"{"error":"unauthorized"}"#.into())]);+ let dir = bind(&root, &server.url());+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([+ event("e-1", "claude-code", "session-start", "s-1"),+ event("e-2", "codex", "session-start", "s-2"),+ ]),+ )+ .unwrap();++ let report = flush(&dir);+ let failure = report.failure.clone().expect("401 is a failure");+ assert!(failure.contains("HTTP 401"), "{failure}");+ assert_eq!(pending_count(&dir), 2);+ assert_eq!(report.exit_code(), 2);+}++#[test]+fn a_body_bearing_status_that_is_not_200_or_429_is_never_parsed_as_an_ack() {+ // A 413 whose body happens to be a well-formed ack must still release+ // nothing: only 200 and 429 carry a meaningful acknowledgement.+ for status in [413u16, 500] {+ let root = fixture(&format!("status-{status}"));+ let server = stub(vec![Reply::Json(status, r#"{"accepted":2}"#.into())]);+ let dir = bind(&root, &server.url());+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([+ event("e-1", "claude-code", "session-start", "s-1"),+ event("e-2", "codex", "session-start", "s-2"),+ ]),+ )+ .unwrap();++ let report = flush(&dir);+ assert!(report.failure.is_some(), "HTTP {status} must fail");+ assert_eq!(+ pending_count(&dir),+ 2,+ "HTTP {status} must not release anything"+ );+ }+}++#[test]+fn a_429_applies_its_acknowledged_items_and_then_stops() {+ let root = fixture("rate-limited");+ let server = stub(vec![Reply::Json(429, r#"{"accepted":1}"#.into())]);+ let dir = bind(&root, &server.url());+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([+ event("e-1", "claude-code", "session-start", "s-1"),+ event("e-2", "codex", "session-start", "s-2"),+ ]),+ )+ .unwrap();++ let report = flush(&dir);+ assert!(+ report.failure.is_none(),+ "a 429 is backpressure, not failure"+ );+ assert_eq!(+ pending_count(&dir),+ 1,+ "the acked item is gone, the other stays"+ );+ assert_eq!(server.bodies().len(), 1, "the flush stopped after the 429");+ assert!(+ report.summary.iter().any(|line| line.contains("429")),+ "{report:?}"+ );+}++#[test]+fn a_redirect_is_refused_and_the_batch_never_reaches_the_second_host() {+ let root = fixture("redirect");+ let elsewhere = TcpListener::bind("127.0.0.1:0").unwrap();+ elsewhere.set_nonblocking(true).unwrap();+ let elsewhere_addr = elsewhere.local_addr().unwrap();+ let server = stub(vec![+ Reply::Redirect(format!("http://{elsewhere_addr}/hook/batch")),+ Reply::Redirect(format!("http://{elsewhere_addr}/hook/batch")),+ Reply::Redirect(format!("http://{elsewhere_addr}/hook/batch")),+ ]);+ let dir = bind(&root, &server.url());+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([event("e-1", "claude-code", "session-start", "s-1")]),+ )+ .unwrap();++ let report = flush(&dir);+ assert!(report.failure.is_some(), "a 302 is not an acknowledgement");+ assert_eq!(pending_count(&dir), 1);+ assert!(+ elsewhere.accept().is_err(),+ "the redirect target must never be contacted"+ );+}++// ------------------------------------------------------------ session order++#[test]+fn a_batch_carries_one_head_per_session_in_enqueue_order() {+ let root = fixture("session-heads");+ let server = stub(vec![Reply::AcceptAll, Reply::AcceptAll, Reply::AcceptAll]);+ let dir = bind(&root, &server.url());+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([+ event("a-1", "claude-code", "session-start", "s-a"),+ event("a-2", "claude-code", "user-prompt-submit", "s-a"),+ event("a-3", "claude-code", "session-end", "s-a"),+ event("b-1", "codex", "session-start", "s-b"),+ event("b-2", "codex", "session-end", "s-b"),+ ]),+ )+ .unwrap();++ let report = flush(&dir);+ assert!(report.failure.is_none(), "{report:?}");+ assert_eq!(pending_count(&dir), 0);++ let batches = server.bodies();+ assert_eq!(batches.len(), 3, "5 events, 2 sessions: 3 rounds");+ let names: Vec<Vec<String>> = batches+ .iter()+ .map(|batch| {+ batch+ .as_array()+ .unwrap()+ .iter()+ .map(|item| query_of(item["url"].as_str().unwrap())["event"].clone())+ .collect()+ })+ .collect();+ assert_eq!(+ names,+ vec![+ vec!["session-start".to_string(), "session-start".to_string()],+ vec!["user-prompt-submit".to_string(), "session-end".to_string()],+ vec!["session-end".to_string()],+ ],+ "each batch takes the oldest event of each session, never two of one"+ );+ // The terminal event of s-a went last, after both of its predecessors.+ let sessions: Vec<Vec<String>> = batches+ .iter()+ .map(|batch| {+ batch+ .as_array()+ .unwrap()+ .iter()+ .map(|item| item["body"]["session_id"].as_str().unwrap().to_string())+ .collect()+ })+ .collect();+ assert_eq!(sessions[2], vec!["s-a".to_string()]);+}++#[test]+fn a_failed_head_defers_its_own_session_without_stalling_an_untried_one() {+ let root = fixture("poison-head");+ let server = stub(vec![+ // The server stopped on item 0 and never looked at item 1.+ Reply::Json(+ 200,+ r#"{"accepted":0,"accepted_indices":[],"failed_index":0}"#.into(),+ ),+ Reply::Json(200, r#"{"accepted":1}"#.into()),+ ]);+ let dir = bind(&root, &server.url());+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([+ event("a-1", "claude-code", "session-start", "s-poison"),+ event("a-2", "claude-code", "session-end", "s-poison"),+ event("b-1", "codex", "session-start", "s-healthy"),+ ]),+ )+ .unwrap();++ let report = flush(&dir);+ assert!(report.failure.is_none(), "{report:?}");++ let sent = server.bodies();+ assert_eq!(sent.len(), 2, "the flush kept going after the failed head");+ let second: Vec<String> = sent[1]+ .as_array()+ .unwrap()+ .iter()+ .map(|item| item["body"]["session_id"].as_str().unwrap().to_string())+ .collect();+ assert_eq!(+ second,+ vec!["s-healthy".to_string()],+ "the untried session must be retried in the same flush, alone"+ );+ assert_eq!(+ pending_count(&dir),+ 2,+ "both poisoned events stay: the head failed and its successor never passes it"+ );+}++// ------------------------------------------------------------ queue identity++#[test]+fn an_identical_reinit_is_recognized_and_a_changed_binding_is_refused() {+ let root = fixture("rebind");+ let dir = bind(&root, "http://127.0.0.1:9/");+ relay::init(+ &dir,+ "http://127.0.0.1:9/",+ "example.runtime",+ "operator-a",+ "team",+ "app",+ )+ .expect("an identical re-init is a no-op");++ let error = relay::init(+ &dir,+ "http://127.0.0.1:9/",+ "example.runtime",+ "operator-b",+ "team",+ "app",+ )+ .unwrap_err();+ assert!(error.to_string().contains("binding mismatch"), "{error:#}");+}++#[test]+fn the_same_id_with_different_content_is_refused_while_an_identical_one_is_recognized() {+ let root = fixture("collision");+ let dir = bind(&root, "http://127.0.0.1:9/");+ let original = serde_json::json!([event("e-1", "claude-code", "session-start", "s-1")]);+ enqueue(&dir, &root, "a.json", original.clone()).unwrap();++ enqueue(&dir, &root, "b.json", original).unwrap();+ assert_eq!(+ pending_count(&dir),+ 1,+ "byte-identical: recognized, not doubled"+ );++ let mut altered = event("e-1", "claude-code", "session-start", "s-1");+ altered["body"]["prompt"] = serde_json::Value::String("something else".into());+ let error = enqueue(&dir, &root, "c.json", serde_json::json!([altered])).unwrap_err();+ assert!(+ error.to_string().contains("identity collision"),+ "{error:#}"+ );+ assert_eq!(pending_count(&dir), 1, "a refused file changes nothing");+}++#[test]+fn a_session_pinned_to_one_agent_refuses_a_second_agent() {+ let root = fixture("session-agent");+ let dir = bind(&root, "http://127.0.0.1:9/");+ enqueue(+ &dir,+ &root,+ "a.json",+ serde_json::json!([event("e-1", "claude-code", "session-start", "s-1")]),+ )+ .unwrap();++ let error = enqueue(+ &dir,+ &root,+ "b.json",+ serde_json::json!([event("e-2", "codex", "user-prompt-submit", "s-1")]),+ )+ .unwrap_err();+ assert!(+ error.to_string().contains("session identity conflict"),+ "{error:#}"+ );+ assert_eq!(pending_count(&dir), 1);+}++#[test]+fn an_invalid_envelope_is_refused_with_zero_side_effects() {+ let root = fixture("invalid-envelope");+ let dir = bind(&root, "http://127.0.0.1:9/");+ let cases = [+ // unknown envelope field+ serde_json::json!([{+ "event_id": "e", "agent": "codex", "event": "session-start",+ "body": {"session_id": "s", "cwd": "/w"}, "extra": true+ }]),+ // no session id+ serde_json::json!([{+ "event_id": "e", "agent": "codex", "event": "session-start",+ "body": {"cwd": "/w"}+ }]),+ // no cwd+ serde_json::json!([{+ "event_id": "e", "agent": "codex", "event": "session-start",+ "body": {"session_id": "s"}+ }]),+ // body is not an object+ serde_json::json!([{+ "event_id": "e", "agent": "codex", "event": "session-start", "body": "text"+ }]),+ ];+ for (index, case) in cases.iter().enumerate() {+ let error = enqueue(&dir, &root, &format!("bad-{index}.json"), case.clone()).unwrap_err();+ assert!(!error.to_string().is_empty());+ assert_eq!(pending_count(&dir), 0, "case {index} must not persist");+ }+}++#[test]+fn a_schema_error_never_echoes_the_input_back() {+ let root = fixture("no-value-echo");+ let dir = bind(&root, "http://127.0.0.1:9/");+ // `deny_unknown_fields` makes serde's Display render the offending key+ // verbatim (`unknown field \`…\``). A producer that puts content in a key+ // name would then have it echoed to a terminal or a log, so the relay+ // reports the error category and position instead.+ let sentinel = "sk-live-do-not-print-me";+ let payload = serde_json::json!([{+ "event_id": "e-1", "agent": "codex", "event": "session-start",+ "body": {"session_id": "s-1", "cwd": "/w"},+ sentinel: "leak",+ }]);+ let error = enqueue(&dir, &root, "unknown-field.json", payload).unwrap_err();+ let rendered = format!("{error:#}");+ assert!(+ !rendered.contains(sentinel),+ "the error echoed the input: {rendered}"+ );+ assert!(rendered.contains("schema error at line"), "{rendered}");+ assert_eq!(pending_count(&dir), 0);+}++// ------------------------------------------------------- persistence limits++#[test]+fn the_body_and_its_capture_protocol_block_reach_the_wire_untouched() {+ let root = fixture("verbatim-body");+ let server = stub(vec![Reply::Json(200, r#"{"accepted":1}"#.into())]);+ let dir = bind(&root, &server.url());+ let body = serde_json::json!({+ "session_id": "native-session-17",+ "cwd": "/work/app",+ "prompt": "Continue the parser fix.",+ "_ai_memory_capture": {"v": 1, "state": "metadata-only"},+ "tool_input": {"file_path": "/work/app/src/main.rs"},+ });+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([{+ "event_id": "run-17-prompt-4", "agent": "claude-code",+ "event": "user-prompt-submit", "body": body.clone(),+ }]),+ )+ .unwrap();+ flush(&dir);++ let sent = &server.bodies()[0][0];+ assert_eq!(sent["body"], body, "no local redaction, no dropped keys");+ let query = query_of(sent["url"].as_str().unwrap());+ assert_eq!(query["extension"], "example.runtime");+ assert_eq!(query["source_event"], "user-prompt-submit");+ assert_eq!(query["event"], "user-prompt-submit");+ assert_eq!(query["agent"], "claude-code");+ assert_eq!(query["workspace"], "team");+ assert_eq!(query["project"], "app");+ assert_eq!(query["ingest_key"].len(), 64);+ assert!(+ query["ingest_key"]+ .bytes()+ .all(|b| b.is_ascii_alphanumeric() || b == b'_' || b == b'-'),+ "the server only accepts its own key alphabet"+ );+}++#[test]+fn the_ingest_key_is_the_documented_tuple_and_ignores_payload() {+ let one = valid("e-1", "claude-code", "session-start", "s-1");+ let mut other_body = event("e-1", "claude-code", "session-start", "s-1");+ other_body["body"]["prompt"] = serde_json::Value::String("different".into());+ let input: InputEvent = serde_json::from_value(other_body).unwrap();+ let two = identity::validate(0, input, "example.runtime", "operator-a").unwrap();+ assert_eq!(+ one.ingest_key, two.ingest_key,+ "the key is identity, not content"+ );+ assert_ne!(one.body_sha256, two.body_sha256, "content is what differs");++ // A different producer namespace must not collide with the same event id.+ let input: InputEvent =+ serde_json::from_value(event("e-1", "claude-code", "session-start", "s-1")).unwrap();+ let elsewhere = identity::validate(0, input, "other.runtime", "operator-a").unwrap();+ assert_ne!(one.ingest_key, elsewhere.ingest_key);+}++#[test]+fn a_path_shaped_event_id_is_accepted_and_stays_idempotent() {+ // `event_id` only feeds the key hash; it is never a query parameter, so an+ // orchestrator that numbers events `run/123/event/2` must not be rejected.+ let root = fixture("path-event-id");+ let dir = bind(&root, "http://127.0.0.1:9/");+ let payload = serde_json::json!([{+ "event_id": "run/123/event/2", "agent": "claude-code",+ "event": "user-prompt-submit",+ "body": {"session_id": "native-17", "cwd": "/work/app"},+ }]);+ enqueue(&dir, &root, "a.json", payload.clone()).unwrap();+ assert_eq!(pending_count(&dir), 1);++ enqueue(&dir, &root, "b.json", payload).unwrap();+ assert_eq!(+ pending_count(&dir),+ 1,+ "the same path-shaped id must be recognized, not duplicated"+ );+}++#[test]+fn an_event_past_the_retry_window_is_retained_and_never_resent() {+ let root = fixture("expired");+ let server = stub(vec![Reply::Json(200, r#"{"accepted":1}"#.into())]);+ let dir = bind(&root, &server.url());+ let mut queue = Queue::open(&dir).unwrap();+ let old = valid("e-old", "claude-code", "session-start", "s-old");+ let fresh = valid("e-new", "codex", "session-start", "s-new");+ queue+ .enqueue(&[old.clone(), fresh], ai_memory_relay::now_ms())+ .unwrap();+ // Its first durable attempt was 31 days ago: past the server's key expiry.+ let long_ago = ai_memory_relay::now_ms() - 31 * 24 * 60 * 60 * 1000;+ queue+ .stamp_attempt(std::slice::from_ref(&old.ingest_key), long_ago)+ .unwrap();+ drop(queue);++ let report = flush(&dir);+ assert!(report.failure.is_none(), "{report:?}");+ let sessions: Vec<String> = server.bodies()[0]+ .as_array()+ .unwrap()+ .iter()+ .map(|item| item["body"]["session_id"].as_str().unwrap().to_string())+ .collect();+ assert_eq!(+ sessions,+ vec!["s-new".to_string()],+ "only the in-window session goes on the wire"+ );+ assert_eq!(+ pending_count(&dir),+ 1,+ "the expired event is kept, not dropped"+ );+ assert!(+ report.summary.iter().any(|line| line.contains("30-day")),+ "the operator has to be told: {report:?}"+ );+ let document: serde_json::Value =+ serde_json::from_str(&relay::status(&dir).unwrap().summary[0]).unwrap();+ assert_eq!(document["expired_items"], 1);+}++#[test]+fn a_full_queue_refuses_new_work_without_dropping_anything() {+ let root = fixture("queue-full");+ let dir = bind(&root, "http://127.0.0.1:9/");+ let mut queue = Queue::open(&dir).unwrap();+ // One 250 KiB body per event: 268 of them clear the 64 MiB ceiling.+ let filler = "x".repeat(250_000);+ let big = |id: &str, session: &str| -> ValidEvent {+ let input: InputEvent = serde_json::from_value(serde_json::json!({+ "event_id": id, "agent": "codex", "event": "post-tool-use",+ "body": {"session_id": session, "cwd": "/w", "blob": filler},+ }))+ .unwrap();+ identity::validate(0, input, "example.runtime", "operator-a").unwrap()+ };+ let first: Vec<ValidEvent> = (0..200)+ .map(|i| big(&format!("e-{i}"), &format!("s-{i}")))+ .collect();+ queue.enqueue(&first, ai_memory_relay::now_ms()).unwrap();++ let second: Vec<ValidEvent> = (200..300)+ .map(|i| big(&format!("e-{i}"), &format!("s-{i}")))+ .collect();+ let error = queue+ .enqueue(&second, ai_memory_relay::now_ms())+ .unwrap_err();+ assert!(error.to_string().contains("queue is full"), "{error:#}");+ drop(queue);+ assert_eq!(+ pending_count(&dir),+ 200,+ "the refused file is all-or-nothing and the queue is intact"+ );+}++#[test]+fn replay_protection_counts_pending_and_receipts_together() {+ let root = fixture("protection-cap");+ let dir = bind(&root, "http://127.0.0.1:9/");+ let mut queue = Queue::open(&dir).unwrap();+ let fresh = valid("e-1", "claude-code", "session-start", "s-1");+ queue+ .enqueue(std::slice::from_ref(&fresh), ai_memory_relay::now_ms())+ .unwrap();+ drop(queue);+ // Fill the receipt table to one slot below the cap in the fixture itself, so+ // the single pending item already consumes the last slot. Generated in SQL:+ // 200k deliveries over HTTP would prove the same thing far more slowly.+ {+ let connection = rusqlite::Connection::open(dir.join("relay.sqlite")).unwrap();+ connection+ .execute(+ "INSERT INTO receipt(ingest_key, body_sha256, first_attempt_ms, delivered_at_ms)+ WITH RECURSIVE n(i) AS (SELECT 1 UNION ALL SELECT i + 1 FROM n WHERE i < ?1)+ SELECT 'fill-' || i, 'fill', ?2, ?2 FROM n",+ rusqlite::params![+ ai_memory_relay::queue::MAX_RECEIPTS - 1,+ ai_memory_relay::now_ms()+ ],+ )+ .unwrap();+ }+ let mut queue = Queue::open(&dir).unwrap();++ let another = valid("e-2", "codex", "session-start", "s-2");+ let error = queue+ .enqueue(&[another], ai_memory_relay::now_ms())+ .unwrap_err();+ assert!(+ error.to_string().contains("replay protection is full"),+ "{error:#}"+ );+ // A duplicate must still be recognized while full: recognizing costs nothing.+ queue+ .enqueue(std::slice::from_ref(&fresh), ai_memory_relay::now_ms())+ .expect("an already-known id is recognized even at the cap");+}++// -------------------------------------------------------------- concurrency++#[test]+fn a_second_flush_is_refused_while_one_holds_the_lock() {+ let root = fixture("flush-lock");+ let dir = bind(&root, "http://127.0.0.1:9/");+ // Let the relay mint the lock file: created by hand it would inherit the+ // ambient umask, and the guard would (correctly) refuse a 0644 one.+ relay::flush(&dir, &FlushOptions::default()).expect("an empty queue flushes cleanly");+ let lock_path = dir.join("flush.lock");+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ assert_eq!(+ std::fs::metadata(&lock_path).unwrap().permissions().mode() & 0o777,+ 0o600+ );+ }+ let held = std::fs::OpenOptions::new()+ .write(true)+ .open(&lock_path)+ .unwrap();+ fs2::FileExt::try_lock_exclusive(&held).unwrap();++ let error = relay::flush(&dir, &FlushOptions::default()).unwrap_err();+ assert!(error.to_string().contains("another flush"), "{error:#}");+ fs2::FileExt::unlock(&held).unwrap();+ assert!(lock_path.exists(), "the lock file is never removed");+}++#[test]+fn two_writers_enqueue_into_one_queue_without_losing_either() {+ let root = fixture("two-writers");+ let dir = bind(&root, "http://127.0.0.1:9/");+ let files: Vec<PathBuf> = (0..2)+ .map(|writer| {+ let events: Vec<serde_json::Value> = (0..25)+ .map(|i| {+ event(+ &format!("w{writer}-e{i}"),+ "codex",+ "post-tool-use",+ &format!("w{writer}-s{i}"),+ )+ })+ .collect();+ write_events(+ &root,+ &format!("writer-{writer}.json"),+ serde_json::Value::Array(events),+ )+ })+ .collect();++ let handles: Vec<_> = files+ .into_iter()+ .map(|file| {+ let dir = dir.clone();+ thread::spawn(move || relay::enqueue(&dir, &file).map(|_| ()))+ })+ .collect();+ for handle in handles {+ handle+ .join()+ .unwrap()+ .expect("concurrent writers both land");+ }+ assert_eq!(pending_count(&dir), 50);+}++// ---------------------------------------------------------- filesystem guards++#[test]+fn the_queue_database_and_its_sidecars_are_owner_only() {+ let root = fixture("private-files");+ let dir = bind(&root, "http://127.0.0.1:9/");+ let mut queue = Queue::open(&dir).unwrap();+ queue+ .enqueue(+ &[valid("e-1", "codex", "session-start", "s-1")],+ ai_memory_relay::now_ms(),+ )+ .unwrap();++ // Checked while the connection is open, which is when -wal and -shm exist.+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ for name in ["relay.sqlite", "relay.sqlite-wal", "relay.sqlite-shm"] {+ let path = dir.join(name);+ assert!(path.exists(), "{name} should exist during a write");+ let mode = std::fs::metadata(&path).unwrap().permissions().mode();+ assert_eq!(+ mode & 0o777,+ 0o600,+ "{name} is mode {:o}; SQLite copies the database's mode onto its sidecars, \+ so the database must be created private, not chmod'ed afterwards",+ mode & 0o777+ );+ }+ }+ drop(queue);+}++#[test]+#[cfg(unix)]+fn a_symlinked_queue_directory_is_refused_without_following_it() {+ let root = fixture("symlink-dir");+ let real = root.join("real");+ std::fs::create_dir(&real).unwrap();+ let link = root.join("link");+ std::os::unix::fs::symlink(&real, &link).unwrap();++ let error = relay::status(&link).unwrap_err();+ assert!(error.to_string().contains("symlink"), "{error:#}");+ assert_eq!(+ std::fs::read_dir(&real).unwrap().count(),+ 0,+ "the target must be untouched"+ );+ assert!(std::fs::symlink_metadata(&link).unwrap().is_symlink());+}++#[test]+#[cfg(unix)]+fn a_group_readable_queue_directory_is_refused_and_not_repaired() {+ use std::os::unix::fs::PermissionsExt;+ let root = fixture("loose-dir");+ let dir = root.join("shared");+ std::fs::create_dir(&dir).unwrap();+ std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o755)).unwrap();++ let error = relay::status(&dir).unwrap_err();+ assert!(error.to_string().contains("owner-only"), "{error:#}");+ assert_eq!(+ std::fs::metadata(&dir).unwrap().permissions().mode() & 0o777,+ 0o755,+ "refusing must not silently chmod a directory the operator owns"+ );+}++#[test]+fn a_directory_holding_unrelated_files_is_refused() {+ let root = fixture("shared-dir");+ let dir = root.join("mixed");+ std::fs::create_dir(&dir).unwrap();+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700)).unwrap();+ }+ std::fs::write(dir.join("notes.txt"), b"someone else's file").unwrap();++ let error = relay::status(&dir).unwrap_err();+ assert!(error.to_string().contains("unrelated files"), "{error:#}");+ assert_eq!(+ std::fs::read(dir.join("notes.txt")).unwrap(),+ b"someone else's file",+ "the file must be untouched"+ );+}++#[test]+fn a_foreign_database_is_refused_byte_for_byte() {+ let root = fixture("foreign-db");+ let dir = root.join("queue");+ std::fs::create_dir(&dir).unwrap();+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700)).unwrap();+ }+ let db = dir.join("relay.sqlite");+ // Generic table names on purpose: `meta(key, value)` is exactly the shape a+ // name-based "interrupted init" guess would have adopted and overwritten.+ {+ let foreign = rusqlite::Connection::open(&db).unwrap();+ foreign+ .execute_batch(+ "CREATE TABLE meta(key TEXT PRIMARY KEY, value TEXT NOT NULL);+ INSERT INTO meta(key, value) VALUES('app', 'something-else');+ CREATE TABLE pending(id INTEGER PRIMARY KEY);",+ )+ .unwrap();+ }+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ std::fs::set_permissions(&db, std::fs::Permissions::from_mode(0o600)).unwrap();+ }+ let before = std::fs::read(&db).unwrap();++ let error = relay::status(&dir).unwrap_err();+ assert!(+ error.to_string().contains("not a usable relay queue"),+ "{error:#}"+ );+ assert_eq!(+ std::fs::read(&db).unwrap(),+ before,+ "a stranger's database must come back byte-identical"+ );+}++#[test]+fn an_empty_sqlite_file_is_treated_as_fresh() {+ // What a rolled-back initialization leaves behind: a valid SQLite file with+ // no user objects. Opening it must succeed, not refuse forever.+ let root = fixture("rolled-back-db");+ let dir = root.join("queue");+ std::fs::create_dir(&dir).unwrap();+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ std::fs::set_permissions(&dir, std::fs::Permissions::from_mode(0o700)).unwrap();+ }+ let db = dir.join("relay.sqlite");+ {+ // A real interrupted initialization: create the schema, then roll it+ // back the way a crash mid-transaction would.+ let mut aborted = rusqlite::Connection::open(&db).unwrap();+ let transaction = aborted.transaction().unwrap();+ transaction+ .execute_batch(+ "CREATE TABLE meta(key TEXT PRIMARY KEY, value TEXT NOT NULL);+ CREATE TABLE pending(seq INTEGER PRIMARY KEY);",+ )+ .unwrap();+ transaction.rollback().unwrap();+ let objects: i64 = aborted+ .query_row(+ "SELECT COUNT(*) FROM sqlite_master WHERE name NOT LIKE 'sqlite_%'",+ [],+ |r| r.get(0),+ )+ .unwrap();+ assert_eq!(objects, 0, "the rollback must leave no user objects");+ }+ #[cfg(unix)]+ {+ use std::os::unix::fs::PermissionsExt;+ std::fs::set_permissions(&db, std::fs::Permissions::from_mode(0o600)).unwrap();+ }++ relay::init(+ &dir,+ "http://127.0.0.1:9/",+ "example.runtime",+ "operator-a",+ "team",+ "app",+ )+ .expect("an object-free database is a fresh queue");+ assert_eq!(pending_count(&dir), 0);+}++// ------------------------------------------------------------------ privacy++#[test]+fn the_bearer_token_never_reaches_output_or_disk() {+ let root = fixture("token-privacy");+ let server = stub(vec![Reply::Json(200, r#"{"accepted":1}"#.into())]);+ let dir = bind(&root, &server.url());+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([event("e-1", "claude-code", "session-start", "s-1")]),+ )+ .unwrap();++ let token = "FAKEfake0123456789relaytoken";+ // Through the binary, so the assertion covers real stdout and stderr.+ let flushed = std::process::Command::new(env!("CARGO_BIN_EXE_ai-memory-relay"))+ .args(["flush", "--queue-dir"])+ .arg(&dir)+ .env_remove("AI_MEMORY_AUTH_TOKEN")+ .env("AI_MEMORY_AUTH_TOKEN", token)+ .output()+ .unwrap();+ let rendered = format!(+ "{}{}",+ String::from_utf8_lossy(&flushed.stdout),+ String::from_utf8_lossy(&flushed.stderr)+ );+ assert!(+ !rendered.contains(token),+ "the token reached output: {rendered}"+ );++ let status = std::process::Command::new(env!("CARGO_BIN_EXE_ai-memory-relay"))+ .args(["status", "--queue-dir"])+ .arg(&dir)+ .env_remove("AI_MEMORY_AUTH_TOKEN")+ .output()+ .unwrap();+ let rendered = String::from_utf8_lossy(&status.stdout).to_string();+ assert!(!rendered.contains(token));+ let document: serde_json::Value = serde_json::from_str(&rendered).unwrap();+ assert_eq!(document["pending_items"], 0, "the flush delivered it");++ // And the queue on disk must never have stored it.+ let stored = std::fs::read(dir.join("relay.sqlite")).unwrap();+ assert!(+ !String::from_utf8_lossy(&stored).contains(token),+ "the token was persisted"+ );+ // It did authenticate, though, and with exactly the value it was given.+ let authorization = server.heads()[0]+ .lines()+ .find(|line| line.to_ascii_lowercase().starts_with("authorization:"))+ .expect("the request should still carry a bearer header")+ .to_string();+ assert_eq!(+ authorization.split_once(':').unwrap().1.trim(),+ format!("Bearer {token}")+ );+}++#[test]+fn status_reports_counts_and_limits_without_payload() {+ let root = fixture("status-shape");+ let dir = bind(&root, "http://127.0.0.1:9/");+ let secret = "prompt-text-that-must-not-appear-anywhere";+ enqueue(+ &dir,+ &root,+ "in.json",+ serde_json::json!([{+ "event_id": "e-1", "agent": "codex", "event": "user-prompt-submit",+ "body": {"session_id": "s-1", "cwd": "/private/work", "prompt": secret},+ }]),+ )+ .unwrap();++ let rendered = relay::status(&dir).unwrap().summary[0].clone();+ assert!(!rendered.contains(secret), "status leaked a payload");+ assert!(!rendered.contains("/private/work"), "status leaked a cwd");+ let document: serde_json::Value = serde_json::from_str(&rendered).unwrap();+ assert_eq!(document["pending_items"], 1);+ assert_eq!(document["pending_sessions"], 1);+ assert_eq!(+ document["limits"]["receipts"],+ ai_memory_relay::queue::MAX_RECEIPTS+ );+ assert_eq!(+ document["retry_window_ms"],+ ai_memory_relay::identity::RETRY_WINDOW_MS+ );+}++#[test]+fn a_batch_stays_under_the_wire_budget_when_bodies_are_large() {+ let root = fixture("byte-budget");+ let server = stub(vec![Reply::AcceptAll, Reply::AcceptAll, Reply::AcceptAll]);+ let dir = bind(&root, &server.url());+ let mut queue = Queue::open(&dir).unwrap();+ let filler = "y".repeat(250_000);+ let events: Vec<ValidEvent> = (0..40)+ .map(|i| {+ let input: InputEvent = serde_json::from_value(serde_json::json!({+ "event_id": format!("e-{i}"), "agent": "codex", "event": "post-tool-use",+ "body": {"session_id": format!("s-{i}"), "cwd": "/w", "blob": filler},+ }))+ .unwrap();+ identity::validate(0, input, "example.runtime", "operator-a").unwrap()+ })+ .collect();+ queue.enqueue(&events, ai_memory_relay::now_ms()).unwrap();+ drop(queue);++ // 40 sessions, one head each: the item count would allow a single batch of+ // 40, but 10 MB of bodies must not go out as one request.+ flush(&dir);+ let sizes: Vec<usize> = server+ .bodies()+ .iter()+ .map(|batch| serde_json::to_vec(batch).unwrap().len())+ .collect();+ assert!(+ sizes.len() >= 2,+ "one batch would exceed the budget: {sizes:?}"+ );+ for size in &sizes {+ assert!(+ *size <= 8 * 1024 * 1024,+ "a batch of {size} bytes is over the 8 MiB budget the server's 10 MiB \+ body limit leaves room for"+ );+ }+}diff --git a/docs/companion-crates.md b/docs/companion-crates.mdindex ff798208..5e834cdd 100644--- a/docs/companion-crates.md+++ b/docs/companion-crates.md@@ -63,6 +63,23 @@ mutation broker. Browsers should talk to the companion; the companion should talto ai-memory with an operator token. That keeps CSRF, confirmation, audit, ratelimits, and UI-specific policy outside the core server.+## `ai-memory-relay`: external lifecycle delivery++[`ai-memory-relay`](../companions/ai-memory-relay) delivers events collected by+an external orchestrator through `/hook/batch`. Its own local queue records events+before sending and retains unacknowledged entries for a later flush. It does not+launch agents, claim handoffs, or open ai-memory's database or wiki.++The orchestrator still maps its events to the native harness payloads and sets+`AI_MEMORY_CAPTURE_OWNER` when launching that harness. The relay uses the native+session identity and derives retry keys from the producer's stable event IDs.+Only the first pending event for each session enters a batch; that session+advances after acknowledgement, even when other sessions are rate-limited.++The package has its own workspace, tests and CLI. Its README defines queue limits,+local data handling and recovery, with an executable test against the real+ai-memory server. Root workspace tests do not run the companion's unit tests.+## `ai-memory-importer`: migration and ingestion companionThis is the companion shape for PR #118. The first implemented companion livesdiff --git a/docs/external-lifecycle.md b/docs/external-lifecycle.mdindex 7734c248..b085d80b 100644--- a/docs/external-lifecycle.md+++ b/docs/external-lifecycle.md@@ -149,6 +149,9 @@ Use the tuple recipe when event IDs have narrower scope.saturation rather than opening an unbounded number of requests.Maintain a durable producer-side queue if offline/restart recovery matters.+The optional [lifecycle relay](../companions/ai-memory-relay) supplies one through+a separate CLI. It accepts events from the orchestrator and sends only the first+pending event of each session in a batch.Flush earlier events for a session before sending its terminal event. Serializedelivery within a session where order matters; different sessions can share theserver concurrently. Late observations and a later terminal event use existingdiff --git a/tests/e2e/external_relay_smoke.py b/tests/e2e/external_relay_smoke.pynew file mode 100755index 00000000..c06d71f5--- /dev/null+++ b/tests/e2e/external_relay_smoke.py@@ -0,0 +1,863 @@+#!/usr/bin/env python3+"""Deterministic end-to-end smoke test for the external lifecycle relay.++Run with:++ uv run --no-project python tests/e2e/external_relay_smoke.py \+ --ai-memory-bin /absolute/ai-memory \+ --relay-bin /absolute/ai-memory-relay++The test starts only isolated local processes and gives them a minimal,+synthetic environment. Every invocation preserves its temporary root, including+logs, queue files, payload fixtures, and a redacted diagnostic summary. Pass+``--artifacts-parent DIR`` to choose the parent directory. Exit status zero+means every assertion in the smoke test passed.+"""++from __future__ import annotations++import argparse+import concurrent.futures+import contextlib+import http.client+import http.server+import json+import os+import socket+import sqlite3+import subprocess+import tempfile+import threading+import time+import urllib.error+import urllib.request+import uuid+from pathlib import Path+from typing import Any, Iterable+++WORKSPACE = "external-relay-e2e"+PROJECT = "relay-smoke"+ACTOR = "relay-test-actor"+AGENT = "claude-code"+GOOD_TOKEN = "FAKEfake0123456789relaygood"+BAD_TOKEN = "FAKEfake0123456789relaywrong"+MARKER = "external_relay_deterministic_handoff_marker"+EVENTS = ("session-start", "user-prompt-submit", "session-end")+++class SmokeFailure(RuntimeError):+ """An assertion or subprocess failed."""+++class DropFirstResponseProxy:+ """Forward requests to the real server and drop responses until released."""++ def __init__(self, target_port: int, timeout_seconds: float) -> None:+ self.target_port = target_port+ self.timeout_seconds = timeout_seconds+ self.mode_lock = threading.Lock()+ self.drop_responses = True+ proxy = self++ class Handler(http.server.BaseHTTPRequestHandler):+ protocol_version = "HTTP/1.1"++ def do_POST(self) -> None: # noqa: N802 - BaseHTTPRequestHandler API+ length = int(self.headers.get("Content-Length", "0"))+ body = self.rfile.read(length)+ headers = {+ key: value+ for key, value in self.headers.items()+ if key.lower() not in {"host", "connection", "content-length"}+ }+ upstream = http.client.HTTPConnection(+ "127.0.0.1",+ proxy.target_port,+ timeout=proxy.timeout_seconds,+ )+ try:+ upstream.request("POST", self.path, body=body, headers=headers)+ response = upstream.getresponse()+ response_body = response.read()+ with proxy.mode_lock:+ drop = proxy.drop_responses+ if drop:+ self.connection.shutdown(socket.SHUT_RDWR)+ self.connection.close()+ return+ self.send_response(response.status)+ for key, value in response.getheaders():+ if key.lower() not in {+ "connection",+ "content-length",+ "transfer-encoding",+ }:+ self.send_header(key, value)+ self.send_header("Content-Length", str(len(response_body)))+ self.end_headers()+ self.wfile.write(response_body)+ finally:+ upstream.close()++ def log_message(self, _format: str, *_args: Any) -> None:+ return++ self.server = http.server.ThreadingHTTPServer(("127.0.0.1", 0), Handler)+ self.thread = threading.Thread(+ target=self.server.serve_forever,+ name="external-relay-drop-response-proxy",+ daemon=True,+ )+ self.thread.start()++ @property+ def url(self) -> str:+ return f"http://127.0.0.1:{self.server.server_port}"++ def stop(self) -> None:+ self.server.shutdown()+ self.server.server_close()+ self.thread.join(timeout=5)+ if self.thread.is_alive():+ raise SmokeFailure("fault proxy thread did not stop")++ def forward_responses(self) -> None:+ with self.mode_lock:+ self.drop_responses = False+++def parse_args() -> argparse.Namespace:+ parser = argparse.ArgumentParser(+ description=(+ "Run an isolated real-server E2E test for ai-memory-relay. All "+ "artifacts are retained; exit status 0 means every assertion passed."+ ),+ epilog=(+ "Example: uv run --no-project python tests/e2e/external_relay_smoke.py "+ "--ai-memory-bin /absolute/ai-memory "+ "--relay-bin /absolute/ai-memory-relay"+ ),+ )+ parser.add_argument(+ "--ai-memory-bin",+ required=True,+ type=Path,+ help="absolute path to the ai-memory executable",+ )+ parser.add_argument(+ "--relay-bin",+ required=True,+ type=Path,+ help="absolute path to the ai-memory-relay executable",+ )+ parser.add_argument(+ "--timeout-seconds",+ type=float,+ default=60.0,+ help="bounded timeout for readiness and each subprocess (default: 60)",+ )+ parser.add_argument(+ "--artifacts-parent",+ type=Path,+ help="existing directory under which the retained temp root is created",+ )+ args = parser.parse_args()+ if args.timeout_seconds < 1:+ parser.error("--timeout-seconds must be at least 1")+ for option in ("ai_memory_bin", "relay_bin"):+ value = getattr(args, option)+ if not value.is_absolute():+ parser.error(f"--{option.replace('_', '-')} must be an absolute path")+ if not value.is_file() or not os.access(value, os.X_OK):+ parser.error(f"--{option.replace('_', '-')} is not an executable file: {value}")+ if args.artifacts_parent is not None:+ args.artifacts_parent = args.artifacts_parent.resolve()+ if not args.artifacts_parent.is_dir():+ parser.error("--artifacts-parent must name an existing directory")+ return args+++def reserve_port() -> int:+ with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as listener:+ listener.bind(("127.0.0.1", 0))+ return int(listener.getsockname()[1])+++def write_json(path: Path, value: Any) -> None:+ path.write_text(json.dumps(value, indent=2, sort_keys=True) + "\n", encoding="utf-8")+++def parse_status(stdout: str, label: str) -> dict[str, int]:+ def unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:+ result: dict[str, Any] = {}+ for key, value in pairs:+ if key in result:+ raise SmokeFailure(f"{label} status JSON duplicated field {key}")+ result[key] = value+ return result++ try:+ parsed = json.loads(stdout, object_pairs_hook=unique_object)+ except json.JSONDecodeError as error:+ raise SmokeFailure(f"{label} did not emit one JSON object") from error+ if not isinstance(parsed, dict):+ raise SmokeFailure(f"{label} status JSON is not an object")+ pending_items = parsed.get("pending_items")+ receipts = parsed.get("receipts")+ if type(pending_items) is not int:+ raise SmokeFailure(f"{label} status JSON has no integer pending_items")+ if type(receipts) is not int:+ raise SmokeFailure(f"{label} status JSON has no integer receipts")+ return {"pending_items": pending_items, "receipts": receipts}+++class Harness:+ def __init__(self, args: argparse.Namespace) -> None:+ self.args = args+ parent = str(args.artifacts_parent) if args.artifacts_parent else None+ self.root = Path(tempfile.mkdtemp(prefix="ai-memory-external-relay-", dir=parent))+ self.home = self.root / "home"+ self.data = self.root / "data"+ self.project = self.root / "project"+ self.queues = self.root / "queues"+ self.payloads = self.root / "payloads"+ self.logs = self.root / "logs"+ self.tmp = self.root / "tmp"+ for directory in (+ self.home,+ self.data,+ self.project,+ self.queues,+ self.payloads,+ self.logs,+ self.tmp,+ ):+ directory.mkdir()+ (self.project / ".ai-memory.toml").write_text(+ f'workspace = "{WORKSPACE}"\nproject = "{PROJECT}"\n', encoding="utf-8"+ )+ self.empty_gitconfig = self.root / "empty-gitconfig"+ self.empty_gitconfig.write_text("", encoding="utf-8")+ self.port = reserve_port()+ self.base_url = f"http://127.0.0.1:{self.port}"+ self.server: subprocess.Popen[bytes] | None = None+ self.server_log_handle: Any = None+ self.proxies: list[DropFirstResponseProxy] = []+ self.command_index = 0+ self.command_lock = threading.Lock()+ self.checks: dict[str, Any] = {}++ def environment(self, token: str | None = GOOD_TOKEN) -> dict[str, str]:+ env = {+ "HOME": str(self.home),+ "USERPROFILE": str(self.home),+ "XDG_CONFIG_HOME": str(self.home / ".config"),+ "XDG_DATA_HOME": str(self.home / ".local" / "share"),+ "TMPDIR": str(self.tmp),+ "TEMP": str(self.tmp),+ "TMP": str(self.tmp),+ "PATH": os.defpath,+ "LANG": "C.UTF-8",+ "LC_ALL": "C.UTF-8",+ "GIT_CONFIG_NOSYSTEM": "1",+ "GIT_CONFIG_GLOBAL": str(self.empty_gitconfig),+ "GIT_CONFIG_SYSTEM": str(self.empty_gitconfig),+ "AI_MEMORY_HOME": str(self.home),+ "AI_MEMORY_DATA_DIR": str(self.data),+ "AI_MEMORY_EMBEDDING_PROVIDER": "none",+ "AI_MEMORY_BACKFILL_ON_START": "false",+ "AI_MEMORY_CONSOLIDATE_ON_SESSION_END": "false",+ "AI_MEMORY_AUTO_IMPROVE__SCHEDULER__ENABLED": "false",+ "RUST_LOG": "off",+ }+ if os.name == "nt":+ for key in ("SystemRoot", "WINDIR", "SystemDrive"):+ value = os.environ.get(key)+ if value:+ env[key] = value+ if token is not None:+ env["AI_MEMORY_AUTH_TOKEN"] = token+ return env++ def run(+ self,+ binary: Path,+ arguments: Iterable[str | Path],+ *,+ token: str | None = GOOD_TOKEN,+ input_text: str | None = None,+ expect: int | None = 0,+ label: str,+ ) -> subprocess.CompletedProcess[str]:+ command = [str(binary), *(str(arg) for arg in arguments)]+ started = time.monotonic()+ try:+ result = subprocess.run(+ command,+ cwd=self.project,+ env=self.environment(token),+ input=input_text,+ text=True,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ timeout=self.args.timeout_seconds,+ check=False,+ )+ except subprocess.TimeoutExpired as error:+ raise SmokeFailure(f"{label} exceeded {self.args.timeout_seconds:g}s") from error+ with self.command_lock:+ self.command_index += 1+ log_path = self.logs / f"command-{self.command_index:03d}.json"+ write_json(+ log_path,+ {+ "label": label,+ "argv": command,+ "duration_seconds": round(time.monotonic() - started, 3),+ "returncode": result.returncode,+ "stdout": result.stdout,+ "stderr": result.stderr,+ },+ )+ if expect is not None and result.returncode != expect:+ raise SmokeFailure(f"{label} exited {result.returncode}, expected {expect}")+ return result++ def relay(self, arguments: Iterable[str | Path], **kwargs: Any) -> subprocess.CompletedProcess[str]:+ return self.run(self.args.relay_bin, arguments, **kwargs)++ def queue_init(+ self, name: str, producer: str, server_url: str | None = None+ ) -> Path:+ queue = self.queues / name+ self.relay(+ [+ "init",+ "--queue-dir",+ queue,+ "--server-url",+ server_url or self.base_url,+ "--producer",+ producer,+ "--actor",+ ACTOR,+ "--workspace",+ WORKSPACE,+ "--project",+ PROJECT,+ ],+ label=f"init-{name}",+ )+ return queue++ def status(self, queue: Path, label: str) -> tuple[Any, int]:+ result = self.relay(["status", "--queue-dir", queue], label=label)+ parsed = parse_status(result.stdout, label)+ return parsed, parsed["pending_items"]++ def enqueue(self, queue: Path, payload_file: Path, label: str) -> None:+ self.relay(+ ["enqueue", "--queue-dir", queue, "--file", payload_file], label=label+ )++ def flush(+ self,+ queue: Path,+ label: str,+ token: str = GOOD_TOKEN,+ expect: int = 0,+ ) -> int:+ return self.relay(+ ["flush", "--queue-dir", queue],+ token=token,+ expect=expect,+ label=label,+ ).returncode++ def start_server(self) -> None:+ server_log = self.logs / "server.log"+ self.server_log_handle = server_log.open("xb")+ self.server = subprocess.Popen(+ [+ str(self.args.ai_memory_bin),+ "--data-dir",+ str(self.data),+ "serve",+ "--transport",+ "http",+ "--bind",+ f"127.0.0.1:{self.port}",+ "--workspace",+ WORKSPACE,+ "--project",+ PROJECT,+ "--no-watcher",+ ],+ cwd=self.project,+ env=self.environment(GOOD_TOKEN),+ stdin=subprocess.DEVNULL,+ stdout=self.server_log_handle,+ stderr=subprocess.STDOUT,+ )+ deadline = time.monotonic() + self.args.timeout_seconds+ while time.monotonic() < deadline:+ if self.server.poll() is not None:+ raise SmokeFailure(f"ai-memory server exited {self.server.returncode} before readiness")+ request = urllib.request.Request(+ f"{self.base_url}/mcp",+ headers={"Authorization": f"Bearer {GOOD_TOKEN}"},+ )+ try:+ with urllib.request.urlopen(request, timeout=0.5):+ return+ except urllib.error.HTTPError as error:+ if error.code in (400, 404, 405):+ return+ except (urllib.error.URLError, TimeoutError):+ pass+ time.sleep(0.05)+ raise SmokeFailure("ai-memory server readiness timeout")++ def stop_server(self) -> None:+ process = self.server+ if process is None:+ return+ self.server = None+ if process.poll() is None:+ process.terminate()+ try:+ process.wait(timeout=min(5.0, self.args.timeout_seconds))+ except subprocess.TimeoutExpired:+ process.kill()+ process.wait(timeout=min(5.0, self.args.timeout_seconds))+ if self.server_log_handle is not None:+ self.server_log_handle.close()+ self.server_log_handle = None++ def start_drop_response_proxy(self) -> DropFirstResponseProxy:+ proxy = DropFirstResponseProxy(self.port, self.args.timeout_seconds)+ self.proxies.append(proxy)+ return proxy++ def stop_proxies(self) -> None:+ while self.proxies:+ self.proxies.pop().stop()++ def db(self) -> sqlite3.Connection:+ path = self.data / "db" / "memory.sqlite"+ return sqlite3.connect(f"file:{path}?mode=ro", uri=True)++ def observation_count(self) -> int:+ with contextlib.closing(self.db()) as connection:+ return int(connection.execute("SELECT COUNT(*) FROM observations").fetchone()[0])++ def hook_spool_json_count(self) -> int:+ spool = self.data / "hook-spool"+ if not spool.is_dir():+ return 0+ return sum(1 for path in spool.rglob("*.json") if path.is_file())++ def observations(self, session_id: uuid.UUID) -> list[tuple[str, str | None, str | None, str]]:+ with contextlib.closing(self.db()) as connection:+ return list(+ connection.execute(+ "SELECT kind, extension, source_event, body FROM observations "+ "WHERE session_id = ? ORDER BY created_at, rowid",+ (session_id.bytes,),+ )+ )++ def handoff_state(self, from_session: uuid.UUID) -> str | None:+ with contextlib.closing(self.db()) as connection:+ row = connection.execute(+ "SELECT state FROM handoffs WHERE from_session_id = ? ORDER BY created_at DESC LIMIT 1",+ (from_session.bytes,),+ ).fetchone()+ return None if row is None else str(row[0])++ def native_hook(self, event: str, session_id: uuid.UUID) -> subprocess.CompletedProcess[str]:+ payload = json.dumps(+ {+ "session_id": str(session_id),+ "cwd": str(self.project),+ "prompt": "native duplicate must remain uncaptured",+ }+ )+ env = self.environment(GOOD_TOKEN)+ env["AI_MEMORY_CAPTURE_OWNER"] = "external-relay-e2e"+ command = [+ str(self.args.ai_memory_bin),+ "--data-dir",+ str(self.data),+ "hook",+ "--event",+ event,+ "--agent",+ AGENT,+ "--server-url",+ self.base_url,+ "--auth-token",+ GOOD_TOKEN,+ ]+ try:+ result = subprocess.run(+ command,+ cwd=self.project,+ env=env,+ input=payload,+ text=True,+ stdout=subprocess.PIPE,+ stderr=subprocess.PIPE,+ timeout=self.args.timeout_seconds,+ check=False,+ )+ except subprocess.TimeoutExpired as error:+ raise SmokeFailure(f"native-{event} exceeded timeout") from error+ self.command_index += 1+ write_json(+ self.logs / f"command-{self.command_index:03d}.json",+ {+ "label": f"native-{event}",+ "argv": [arg if arg != GOOD_TOKEN else "<redacted>" for arg in command],+ "returncode": result.returncode,+ "stdout": result.stdout,+ "stderr": result.stderr,+ },+ )+ if result.returncode != 0:+ raise SmokeFailure(f"native-{event} exited {result.returncode}")+ return result+++def lifecycle(session_id: uuid.UUID, prefix: str, prompt: str = MARKER) -> list[dict[str, Any]]:+ return [+ {+ "event_id": f"{prefix}-start",+ "agent": AGENT,+ "event": "session-start",+ "body": {"session_id": str(session_id), "cwd": "", "source": prefix},+ },+ {+ "event_id": f"{prefix}-prompt",+ "agent": AGENT,+ "event": "user-prompt-submit",+ "body": {"session_id": str(session_id), "cwd": "", "prompt": prompt},+ },+ {+ "event_id": f"{prefix}-end",+ "agent": AGENT,+ "event": "session-end",+ "body": {"session_id": str(session_id), "cwd": "", "reason": "completed"},+ },+ ]+++def materialize(harness: Harness, name: str, events: list[dict[str, Any]]) -> Path:+ copied = json.loads(json.dumps(events))+ for item in copied:+ item["body"]["cwd"] = str(harness.project)+ path = harness.payloads / f"{name}.json"+ write_json(path, copied)+ return path+++def require(condition: bool, message: str) -> None:+ if not condition:+ raise SmokeFailure(message)+++def run_smoke(harness: Harness) -> None:+ main_session = uuid.uuid4()+ main_queue = harness.queue_init("offline-main", "producer-a")+ initial_status, initial_pending = harness.status(main_queue, "status-initial")+ require(initial_pending == 0, f"new queue has {initial_pending} pending events")++ canonical_file = materialize(+ harness, "canonical-offline", lifecycle(main_session, "canonical")+ )+ harness.enqueue(main_queue, canonical_file, "enqueue-offline")+ _, offline_pending = harness.status(main_queue, "status-offline-enqueued")+ require(offline_pending == 3, f"offline enqueue retained {offline_pending}, expected 3")++ harness.start_server()+ harness.flush(main_queue, "flush-after-server-start")+ _, flushed_pending = harness.status(main_queue, "status-after-flush")+ require(flushed_pending == 0, f"successful flush left {flushed_pending} pending")+ main_rows = harness.observations(main_session)+ require([row[0] for row in main_rows] == ["session-start", "user-prompt", "session-end"], "canonical lifecycle order differs")+ require(all(row[1] == "producer-a" for row in main_rows), "canonical producer extension differs")+ require([row[2] for row in main_rows] == list(EVENTS), "canonical source events differ")++ before_native = harness.observation_count()+ spool_before_native = harness.hook_spool_json_count()+ receiver = uuid.uuid4()+ native_start = harness.native_hook("session-start", receiver)+ require(MARKER in native_start.stdout, "capture-owner SessionStart did not receive handoff")+ harness.native_hook("user-prompt-submit", receiver)+ harness.native_hook("session-end", receiver)+ after_native = harness.observation_count()+ spool_after_native = harness.hook_spool_json_count()+ require(after_native == before_native, "capture-owner native hooks created observations")+ require(+ spool_after_native == spool_before_native,+ "capture-owner native hooks created spool JSON files",+ )+ require(harness.handoff_state(main_session) == "accepted", "capture-owner hook did not preserve and accept the external handoff")++ harness.enqueue(main_queue, canonical_file, "enqueue-identical-replay")+ harness.flush(main_queue, "flush-identical-replay")+ require(len(harness.observations(main_session)) == 3, "identical replay duplicated observations")++ collision_before = harness.observation_count()+ collision_queue = harness.queue_init(+ "collision-foreign-agent", "producer-collision"+ )+ collision_status_before, _ = harness.status(+ collision_queue, "status-before-collision"+ )+ collision_receipts_before = collision_status_before["receipts"]+ collision_file = materialize(+ harness,+ "session-collision",+ [+ {+ "event_id": "wrong-agent-collision",+ "agent": "codex",+ "event": "user-prompt-submit",+ "body": {+ "session_id": str(main_session),+ "cwd": "",+ "prompt": "valid wrong-agent event expected to be acknowledged and dropped",+ },+ }+ ],+ )+ harness.enqueue(collision_queue, collision_file, "enqueue-session-collision")+ harness.flush(collision_queue, "flush-session-collision")+ collision_status_after, collision_pending = harness.status(+ collision_queue, "status-after-collision"+ )+ collision_receipts_after = collision_status_after["receipts"]+ require(collision_pending == 0, "acknowledged SessionCollision remained pending")+ require(+ collision_receipts_after == collision_receipts_before + 1,+ "SessionCollision acknowledgement did not create one relay receipt",+ )+ collision_stored_delta = harness.observation_count() - collision_before+ require(collision_stored_delta == 0, "SessionCollision created a stored observation")++ same_body = "identical body with distinct external identities"+ producer_a_session = uuid.uuid4()+ producer_a_file = materialize(+ harness,+ "distinct-producer-a",+ [+ {+ "event_id": "shared-event-id",+ "agent": AGENT,+ "event": "user-prompt-submit",+ "body": {"session_id": str(producer_a_session), "cwd": "", "prompt": same_body},+ },+ {+ "event_id": "different-event-id",+ "agent": AGENT,+ "event": "user-prompt-submit",+ "body": {"session_id": str(producer_a_session), "cwd": "", "prompt": same_body},+ },+ ],+ )+ harness.enqueue(main_queue, producer_a_file, "enqueue-distinct-event-ids")+ harness.flush(main_queue, "flush-distinct-event-ids")+ producer_a_rows = harness.observations(producer_a_session)+ require(len(producer_a_rows) == 2, "distinct event IDs collapsed")++ producer_b_queue = harness.queue_init("producer-b", "producer-b")+ producer_b_file = materialize(+ harness,+ "distinct-producer-b",+ [+ {+ "event_id": "shared-event-id",+ "agent": AGENT,+ "event": "user-prompt-submit",+ "body": {"session_id": str(producer_a_session), "cwd": "", "prompt": same_body},+ }+ ],+ )+ harness.enqueue(producer_b_queue, producer_b_file, "enqueue-distinct-producer")+ harness.flush(producer_b_queue, "flush-distinct-producer")+ combined_producer_rows = harness.observations(producer_a_session)+ require(len(combined_producer_rows) == 3, "distinct producer collapsed")+ require(+ sum(row[1] == "producer-a" for row in combined_producer_rows) == 2+ and sum(row[1] == "producer-b" for row in combined_producer_rows) == 1,+ "producer namespaces were not preserved",+ )++ proxy = harness.start_drop_response_proxy()+ lost_response_session = uuid.uuid4()+ lost_response_queue = harness.queue_init(+ "lost-response", "producer-loss", server_url=proxy.url+ )+ lost_response_file = materialize(+ harness,+ "lost-response",+ [+ {+ "event_id": "accepted-before-response-loss",+ "agent": AGENT,+ "event": "user-prompt-submit",+ "body": {+ "session_id": str(lost_response_session),+ "cwd": "",+ "prompt": "response loss idempotency marker",+ },+ }+ ],+ )+ harness.enqueue(lost_response_queue, lost_response_file, "enqueue-lost-response")+ lost_response_exit = harness.flush(+ lost_response_queue, "flush-lost-response", expect=2+ )+ _, lost_response_pending = harness.status(+ lost_response_queue, "status-lost-response"+ )+ require(lost_response_pending == 1, "response loss did not retain the queue item")+ require(+ len(harness.observations(lost_response_session)) == 1,+ "real server did not accept exactly one observation before response loss",+ )+ proxy.forward_responses()+ harness.flush(lost_response_queue, "flush-lost-response-retry")+ _, lost_response_retry_pending = harness.status(+ lost_response_queue, "status-lost-response-retry"+ )+ require(lost_response_retry_pending == 0, "lost-response retry remained pending")+ require(+ len(harness.observations(lost_response_session)) == 1,+ "lost-response retry duplicated the real-server observation",+ )++ concurrent_sessions: list[tuple[uuid.UUID, Path]] = []+ for index in range(15):+ session_id = uuid.uuid4()+ queue = harness.queue_init(f"concurrent-{index:02d}", f"parallel-{index % 3}")+ payload = materialize(+ harness,+ f"concurrent-{index:02d}",+ lifecycle(session_id, f"parallel-{index:02d}", prompt=f"parallel marker {index}"),+ )+ harness.enqueue(queue, payload, f"enqueue-concurrent-{index:02d}")+ concurrent_sessions.append((session_id, queue))+ with concurrent.futures.ThreadPoolExecutor(max_workers=15) as executor:+ futures = [+ executor.submit(harness.flush, queue, f"flush-concurrent-{index:02d}")+ for index, (_, queue) in enumerate(concurrent_sessions)+ ]+ for future in futures:+ future.result(timeout=harness.args.timeout_seconds + 5)+ for session_id, queue in concurrent_sessions:+ rows = harness.observations(session_id)+ require([row[0] for row in rows] == ["session-start", "user-prompt", "session-end"], f"concurrent session {session_id} lifecycle order differs")+ _, pending = harness.status(queue, f"status-concurrent-{session_id.hex[:8]}")+ require(pending == 0, f"concurrent queue {session_id} retained {pending}")++ auth_session = uuid.uuid4()+ auth_queue = harness.queue_init("auth-retry", "producer-auth")+ auth_file = materialize(+ harness,+ "auth-retry",+ [+ {+ "event_id": "auth-event",+ "agent": AGENT,+ "event": "user-prompt-submit",+ "body": {"session_id": str(auth_session), "cwd": "", "prompt": "auth retry marker"},+ }+ ],+ )+ harness.enqueue(auth_queue, auth_file, "enqueue-auth-retry")+ bad_code = harness.flush(+ auth_queue, "flush-auth-rejected", token=BAD_TOKEN, expect=2+ )+ _, rejected_pending = harness.status(auth_queue, "status-auth-rejected")+ require(rejected_pending == 1, f"auth rejection retained {rejected_pending}, expected 1")+ require(len(harness.observations(auth_session)) == 0, "unauthorized flush wrote an observation")+ harness.flush(auth_queue, "flush-auth-retry-correct")+ _, retry_pending = harness.status(auth_queue, "status-auth-retry-correct")+ require(retry_pending == 0, f"authorized retry left {retry_pending} pending")+ require(len(harness.observations(auth_session)) == 1, "authorized retry lost or duplicated event")++ final_count = harness.observation_count()+ expected_count = 3 + 2 + 1 + 1 + (15 * 3) + 1+ require(final_count == expected_count, f"final observation count {final_count}, expected {expected_count}")+ harness.checks = {+ "initial_queue_status": initial_status,+ "initial_pending": initial_pending,+ "offline_pending": offline_pending,+ "offline_restart_flush": "passed",+ "canonical_lifecycle": "passed",+ "capture_owner_zero_new_observations": after_native - before_native,+ "capture_owner_new_spool_json": spool_after_native - spool_before_native,+ "handoff_state": harness.handoff_state(main_session),+ "identical_replay_count": len(harness.observations(main_session)),+ "session_collision": {+ "relay_acknowledged": collision_pending == 0,+ "receipt_delta": collision_receipts_after - collision_receipts_before,+ "stored_observation_delta": collision_stored_delta,+ },+ "distinct_event_id_count": len(producer_a_rows),+ "distinct_producer_count": sum(+ row[1] == "producer-b" for row in combined_producer_rows+ ),+ "lost_response": {+ "first_exit": lost_response_exit,+ "pending_after_loss": lost_response_pending,+ "pending_after_retry": lost_response_retry_pending,+ "stored_observations": len(+ harness.observations(lost_response_session)+ ),+ },+ "concurrent_sessions": len(concurrent_sessions),+ "concurrent_observations": sum(+ len(harness.observations(sid)) for sid, _ in concurrent_sessions+ ),+ "auth_rejected_exit": bad_code,+ "auth_rejected_pending": rejected_pending,+ "auth_retry_pending": retry_pending,+ "final_observations": final_count,+ "expected_observations": expected_count,+ }+++def main() -> int:+ args = parse_args()+ harness = Harness(args)+ passed = False+ error_message: str | None = None+ try:+ run_smoke(harness)+ passed = True+ return 0+ except Exception as error: # diagnostics must survive every assertion failure+ error_message = f"{type(error).__name__}: {error}"+ return 1+ finally:+ try:+ harness.stop_proxies()+ finally:+ harness.stop_server()+ summary = {+ "status": "passed" if passed else "failed",+ "artifacts": str(harness.root),+ "checks": harness.checks,+ }+ if error_message is not None:+ summary["error"] = error_message+ write_json(harness.root / "summary.json", summary)+ print(json.dumps(summary, sort_keys=True))+++if __name__ == "__main__":+ raise SystemExit(main())