agent-context-bridge 0.2.0__tar.gz → 0.3.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (39) hide show
  1. agent_context_bridge-0.3.0/AUDIT_SECURITY.md +64 -0
  2. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/CHANGELOG.md +19 -1
  3. agent_context_bridge-0.3.0/DESIGN.md +165 -0
  4. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/PKG-INFO +1 -1
  5. agent_context_bridge-0.3.0/PRODUCT_BRIEF.md +46 -0
  6. agent_context_bridge-0.3.0/QA_REPORT_v0.3.0.md +65 -0
  7. agent_context_bridge-0.3.0/SECURITY.md +29 -0
  8. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/pyproject.toml +2 -1
  9. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/src/agent_context_bridge/__init__.py +1 -1
  10. agent_context_bridge-0.3.0/src/agent_context_bridge/audit.py +90 -0
  11. agent_context_bridge-0.3.0/src/agent_context_bridge/cli.py +528 -0
  12. agent_context_bridge-0.3.0/src/agent_context_bridge/core.py +464 -0
  13. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/src/agent_context_bridge/hooks.py +7 -0
  14. agent_context_bridge-0.3.0/src/agent_context_bridge/mcp.py +263 -0
  15. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/src/agent_context_bridge/utils.py +6 -0
  16. agent_context_bridge-0.3.0/tests/test_audit.py +129 -0
  17. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/tests/test_core.py +2 -1
  18. agent_context_bridge-0.3.0/tests/test_mcp.py +169 -0
  19. agent_context_bridge-0.3.0/tests/test_search_status_prune.py +448 -0
  20. agent_context_bridge-0.3.0/tests/test_security_fixes.py +92 -0
  21. agent_context_bridge-0.3.0/tests/test_v030_search_status_prune.py +229 -0
  22. agent_context_bridge-0.3.0/uv.lock +461 -0
  23. agent_context_bridge-0.2.0/SECURITY.md +0 -22
  24. agent_context_bridge-0.2.0/src/agent_context_bridge/cli.py +0 -229
  25. agent_context_bridge-0.2.0/src/agent_context_bridge/core.py +0 -208
  26. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/.github/workflows/ci.yml +0 -0
  27. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/.github/workflows/release.yml +0 -0
  28. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/.gitignore +0 -0
  29. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/CONTRIBUTING.md +0 -0
  30. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/LICENSE +0 -0
  31. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/README.md +0 -0
  32. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/docs/demo.gif +0 -0
  33. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/docs/social-preview.png +0 -0
  34. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/src/agent_context_bridge/adapters.py +0 -0
  35. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/tests/test_adapters.py +0 -0
  36. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/tests/test_cli.py +0 -0
  37. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/tests/test_e2e_multiagent.py +0 -0
  38. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/tests/test_hardening.py +0 -0
  39. {agent_context_bridge-0.2.0 → agent_context_bridge-0.3.0}/tests/test_hooks.py +0 -0
@@ -0,0 +1,64 @@
1
+ # Audit Sécurité — agent-context-bridge v0.3.0
2
+
3
+ Date : 2026-11-16. Auditeur : security (Hermes). Périmètre : `src/agent_context_bridge/` (core, cli, mcp, hooks, adapters, utils), tag v0.3.0.
4
+ Méthode : relecture code + probes d'exécution (stores temporaires, faux secrets uniquement).
5
+ État suite : `pytest tests/ -q` → **70 passed, 3 failed, tous 3 environnementaux** (binaire `acb` installé = 0.2.0 vs source 0.3.0 : `test_version_coherent…`, `test_search_json_structure`, `test_prune_json_roundtrip_coherence` — assertions `payload["version"] == "0.3.0"`). Non liés à la sécurité, mais la CI release doit tester le build v0.3.0, sinon les garde-fous ne sont pas validés. Note packaging : le `.venv` local n'expose pas le entry-point `acb-mcp` (install 0.2.0 antérieure au module `mcp.py`).
6
+
7
+ ## Verdict
8
+
9
+ 2 findings High (bloquants pour release), 2 Medium, 1 Low. Recommandation : ne pas tagger/releaser v0.3.0 en l'état ; corriger H1+H2 ou accepter formellement le risque (fondateur).
10
+
11
+ ## H1 — Le serveur MCP expose une suppression destructive, contrairement au design readonly
12
+
13
+ DESIGN.md §4 : "READONLY strict — le serveur expose exactement 2 tools, aucun `prune` ni écriture. `prune` reste CLI-only."
14
+ Réalité (`src/agent_context_bridge/mcp.py`) : 3 tools exposés, dont `acb_prune` avec `dry_run` défaut true mais `dry_run=false` accepté et exécuté. Le test `test_mcp_tools_list_exposes_search_status_prune` fige même cette déviation.
15
+ Preuve (probe) : `tools/call acb_prune {"keep_last":0,"dry_run":false}` → `{"pruned":1,"kept":0,"dry_run":false}`, `records.jsonl` passe de 1 ligne à 0. N'importe quel client MCP (Claude) peut donc vider le store, sans confirmation interactive (garde-fou CLI contourné).
16
+ De plus, le paramètre `dir` accepte tout chemin local (`acb_status {"dir":"/etc"}` répond avec le diagnostic du store) : lecture/suppression hors workspace, sans sandbox.
17
+ Impact : perte de données pilotable par le modèle/outil connecté.
18
+ Remédiation (au choix, dans l'ordre de préférence) : (a) retirer `acb_prune` de `_tool_defs`/`handle_message` et revenir à 2 tools readonly ; (b) à défaut, forcer `dry_run=true` côté serveur (ignorer la valeur client) ; (c) restreindre `dir` au workspace du serveur (refuser `--dir`/`dir` client ou allowlist sous `default_dir`), à défaut documenter explicitement le risque. Mettre à jour DESIGN.md ou le code pour qu'ils concordent, et corriger le test.
19
+ Owner : dev. Re-test : `printf ...dry_run:false... | python -m agent_context_bridge.mcp` doit répondre `Method not found` (option a) ou `dry_run:true` avec store inchangé ; `pytest tests/test_mcp.py -q`.
20
+
21
+ ## H2 — Aucune détection secrets/PII alors que le brief promet `acb audit`
22
+
23
+ PRODUCT_BRIEF C2 promet `acb audit` (détecte clés API, tokens, emails, exit ≠ 0, valeurs masquées). La commande n'existe pas : `acb audit` → `invalid choice`, aucun motif `audit|secret|redact` dans `src/`.
24
+ Preuve (probe) : record avec `--details` contenant fausse clé API + email stocké en clair dans `records.jsonl`, sans avertissement ; la valeur se propage ensuite dans `SHARED_CONTEXT.md` (vérifié : `grep` trouve le marqueur), `acb export`, `acb search --json`, et donc dans les prompts injectés (`inject`, hooks SessionStart) — soit une exfiltration vers le provider LLM à chaque session.
25
+ Atténuant : `inject`/`hooks run` (adapters) ne remontent que topic/summary, pas details — mais `export`/`search --json` exposent tout.
26
+ Remédiation : (a) implémenter `acb audit` (patterns stdlib : `sk-`, `ghp_`, `AKIA`, `xox[bap]`, emails, chemins `/home|Users`, clés privées `BEGIN PRIVATE KEY` ; rapport par type/compte/ligne, valeurs jamais imprimées, exit 1 si trouvaille) + test fixture ; (b) avertir à `record` quand le contenu matche (stderr, sans bloquer) ; (c) documenter que `records.jsonl`/`SHARED_CONTEXT.md` sont en clair et exclus du git (déjà dans `.gitignore` — bien). Retirer la promesse C2/SLSA de PRODUCT_BRIEF tant que non livré (fausse assurance).
27
+ Owner : dev. Re-test : fixture avec faux secret → `acb audit` exit 1 sans valeur en clair ; fixture saine → exit 0 ; `pytest`.
28
+
29
+ ## M1 — Permissions `.agent_bridge` implicites, dossier lisible par tous
30
+
31
+ `MemoryStore.initialize` fait `mkdir(parents=True, exist_ok=True)` sans mode → `0700`−umask effectif constaté `755` sur le dossier (probe : `stat` → `755` dir, `600` fichiers — ce `600` n'est qu'un accident de `NamedTemporaryFile`, pas une politique).
32
+ Sur machine partagée, tout utilisateur peut lister le store ; les fichiers eux-mêmes héritent de l'umask sans `chmod` explicite, donc fragile.
33
+ Remédiation : `os.chmod(bridge_dir, 0o700)` à `initialize` (+ `exist_ok`, try/except OSError), `os.chmod(file, 0o600)` après `atomic_write` des 3 fichiers (records, md, `.claude/settings.json`), ou `os.umask(0o077)` scoped. Ajouter un test `stat` (mode & 0o777 == 0o700/0o600).
34
+ Owner : dev. Re-test : init frais → `stat -c %a` = `700` dir, `600` fichiers ; `pytest`.
35
+
36
+ ## M2 — `hooks run` lit stdin sans limite de taille
37
+
38
+ `cli.py` (`hooks run`) fait `sys.stdin.read()` non borné avant d'ignorer le contenu. Probe : 10 Mo absorbés sans broncher (exit 0). Un payload SessionStart anormalement gros = pic mémoire du hook à chaque session (DoS locale bénigne mais réelle ; le hook s'exécute à chaque SessionStart).
39
+ Bon point : le contenu stdin est intégralement ignoré (pas d'injection via hook payload — rien n'est interpolé en shell, `hook_command` est une chaîne fixe `acb inject --target X`), et `install_claude_hook` merge sans `eval`.
40
+ Remédiation : caper la lecture (ex. 1 Mo : `sys.stdin.read(1_000_000)` + drain borné), commenter que le payload est intentionnellement ignoré.
41
+ Owner : dev. Re-test : payload > cap → exit 0, sortie identique ; `pytest tests/test_hooks.py -q`.
42
+
43
+ ## L1 — Divers durcissement déjà correct, à conserver
44
+
45
+ Limites `search --limit 1..100` (exit 2), `record` borné (64/200/2000/20000, 20 tags), adapters capés à 1000, `_load_all` tolérant aux lignes corrompues (comptées `skipped`), MCP `parse error -32700 / invalid params -32602` sans fuite de traceback (catch-all → `-32603 Internal error` sans détail), `--dir` inexistant → exit 1 sans création. Bien. Mineur : les messages d'erreur incluent le chemin absolu du workspace (empreinte système dans les logs MCP/CI) — acceptable en local, à masquer si les logs partent en CI publique.
46
+
47
+ ## Détails envérifiés / limites
48
+
49
+ Probes avec faux secrets uniquement ; la sortie `records.jsonl` du probe initial a été masquée par la plateforme (`sk-liv...7890`) — la conclusion "stockage en clair" repose sur le code (`json.dumps(asdict(rec))` direct, aucune fonction de masquage dans `src/`), pas sur la sortie masquée.
50
+ Non testé : SLSA/provenance release (hors code), multi-utilisateurs réels, perf gros stores.
51
+
52
+ ## Re-test global
53
+
54
+ ~/ai_env/bin/python -m pytest tests/ -q # attendu : tout vert + nouveaux tests audit/perms/MCP
55
+
56
+ ## Addendum — re-vérification runtime 2026-11-16 (run 2)
57
+
58
+ Probes rejoués contre la source v0.3.0 (`PYTHONPATH=src`, `.venv` Python 3.12, umask 0022) :
59
+
60
+ - **H1 re-confirmé, avec précision** : `tools/call acb_prune {"keep_last":0,"dry_run":false,"dir":"/tmp/acb-perm-test"}` → `{"pruned":1,"kept":0,"dry_run":false}`, `records.jsonl` 1 ligne → 0. Suppression réelle, sans confirmation. **Trou de test identifié** : `tests/test_mcp.py::test_mcp_prune_is_dryrun_only_store_unchanged` n'exerce que le défaut (`dry_run` omis → true) ; aucun test ne couvre `dry_run:false` explicite — c'est pourquoi le garde-fou supposé n'est pas validé. Re-test fix : ajouter le cas `dry_run:false` (doit refuser ou rester sans effet).
61
+ - **H1/bis `dir` re-confirmé** : `acb_search {"query":"x","dir":"/etc"}` accepté et résolu (erreur métier `ACB not initialized in /etc`, pas `-32602`) ; `get_status` fait `rglob("*")+stat()` sur le workspace fourni → oracle existence/taille sur tout le FS local.
62
+ - **M1 re-confirmé** : `acb init` frais → dir `755`, fichiers `600` ; `grep -rn "chmod|0o600|0o700|umask|audit|secret|redact|pii" src/` = **0 hit**. Le `600` fichier n'est qu'un accident de `NamedTemporaryFile`, pas une politique ; aucun réparatif sur stores pré-existants.
63
+ - **Stores réels scannés propres** : regex secrets durs (`sk-live`, `AKIA…`, `ghp_`, `xox*`, `BEGIN … PRIVATE KEY`) sur `~/.agent_bridge/records.jsonl` et `/tmp/acb-demo/.agent_bridge/records.jsonl` → 0 hit. Le risque H2 reste structurel (aucun garde-fou à l'écriture), pas un incident constaté.
64
+ - Fichier test : `/tmp/acb-perm-test/.agent_bridge/` (store jetable du probe, hors repo).
@@ -4,11 +4,29 @@ All notable changes to `agent-context-bridge` are documented here.
4
4
  Format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
5
5
 
6
6
  ## [Unreleased]
7
+
8
+ ## [0.3.0] - 2026-11-16
7
9
  ### Added
10
+ - `acb search <query> [-n/--limit 1..100] [--tag]... [--agent] [--json] [--dir]`
11
+ (full-text OR search, newest-first, `--json` payload `results/count/query`).
12
+ - `acb status [--json] [--dir]` (records, store bytes, last_updated, targets;
13
+ never creates the store; exit 0, `initialized: false` when absent).
14
+ - `acb prune --older-than DAYS | --keep-last N [--tag]... [--dry-run] [--yes] [--json]`
15
+ (only destructive command: interactive confirm, non-TTY refusal without `--yes`,
16
+ regenerates `SHARED_CONTEXT.md`).
17
+ - `acb audit [--json] [--dir]` (read-only secrets/PII scan of the store — API keys,
18
+ tokens, emails, private keys; values always masked, exit 1 on findings).
19
+ `acb record` warns on stderr when content matches a secret pattern (never blocks).
20
+ - `acb-mcp` stdio JSON-RPC server, strictly read-only: `acb_search`, `acb_status`
21
+ (any other tool, including `prune`, → `Method not found`; bad params → `-32602`).
22
+ - `[project.scripts] acb-mcp` entry point; zero new runtime dependencies (stdlib only).
8
23
  - `acb --version` (single source of truth: installed dist metadata, fallback `__version__`).
9
24
  - Native hooks: `acb hooks claude --print|--install`, `acb hooks hermes --print`,
10
- `acb hooks run --target <hermes|claude|opencode|codex>` (stdin-draining, exit 0, 1-command test).
25
+ `acb hooks run --target <hermes|claude|opencode|codex>` (stdin drained with 1 MiB cap, exit 0).
11
26
  - README: 3-command local demo + 1-command hook wiring docs.
27
+ ### Security
28
+ - Store hardening: `.agent_bridge/` created/repaired to `0700`, store files to `0600`.
29
+ - MCP server exposes no destructive tool (prune stays CLI-only with confirmation).
12
30
  ### Fixed
13
31
  - CI badge now reflects the real workflow status (dynamic `ci.yml` badge) instead of a static "passing" shield.
14
32
 
@@ -0,0 +1,165 @@
1
+ # DESIGN.md — ACB v0.3.0 : search / status / prune + MCP stdio
2
+
3
+ Version cible : 0.3.0 (suit 0.2.0 : init, record, list, inject, export, hooks).
4
+ Perimetre : 3 nouvelles commandes CLI, 2 formats de sortie, schema d'interaction MCP stdio.
5
+ Pas de code d'implementation dans ce document.
6
+
7
+ ## 1. Principes UX
8
+
9
+ - 3 commandes, 1 verbe chacune, options memorisables : `--dir`, `--json`, `-n/--limit`.
10
+ - Meme contrat partout : stdout = resultat, stderr = humain/diag, exit codes stables.
11
+ - JSON = meme information que l'humain, jamais un sous-ensemble.
12
+ - Lecture seule par defaut : seul `prune` mute le store, et il demande confirmation.
13
+ - Offline-first conserve : aucune commande ne fait de reseau.
14
+
15
+ ## 2. CLI : signatures
16
+
17
+ Toutes acceptent le flag global `--dir <path>` (defaut : cwd).
18
+
19
+ ### 2.1 `acb search <query>`
20
+
21
+ Recherche plein-texte sur topic + summary + details + tags, insensible a la casse.
22
+
23
+ ```
24
+ acb search <query> [--dir PATH] [-n/--limit N=10] [--tag TAG]... [--agent NAME] [--json]
25
+ ```
26
+
27
+ - `<query>` : 1+ mots, OU implicite. Chaine vide ou absente -> exit 2 + usage sur stderr.
28
+ - `--tag` repetable : filtre ET sur les tags. `--agent` : filtre exact, insensible a la casse.
29
+ - Tri : plus recents d'abord. `--limit` : 1..100, defaut 10, hors borne -> exit 2.
30
+
31
+ ### 2.2 `acb status`
32
+
33
+ Diagnostic lecture seule du workspace, pour humains et CI.
34
+
35
+ ```
36
+ acb status [--dir PATH] [--json]
37
+ ```
38
+
39
+ Champs : `version` (package), `workspace` (absolu), `initialized` (bool),
40
+ `records` (compte), `store_bytes` (taille `.agent_bridge/` en octets, 0 si non initialisé),
41
+ `last_updated` (ISO-8601 UTC ou null), `targets` (["hermes","claude","opencode","codex"]).
42
+ Ne cree jamais le store : non initialise -> `initialized: false`, `records: 0`.
43
+
44
+ ### 2.3 `acb prune`
45
+
46
+ Suppression des entrees anciennes. SEULE commande destructive du lot.
47
+
48
+ ```
49
+ acb prune [--dir PATH] [--older-than DAYS] [--keep-last N] [--tag TAG]... [--dry-run] [--yes] [--json]
50
+ ```
51
+
52
+ - `--older-than DAYS` (int >= 1) OU `--keep-last N` (int >= 0), exactement un des deux requis.
53
+ - `--tag` repetable : restreint la suppression aux records portant TOUS les tags (combine avec le critere d'age/rang).
54
+ - Sans `--yes` : mode interactif = demande `Prune <k> record(s)? [y/N]`, defaut Non.
55
+ - `--dry-run` : ne supprime rien, liste ce qui serait supprime. Combine avec `--json` pour la CI.
56
+ - Non-TTY sans `--yes` ni `--dry-run` -> exit 2 + message "refusing without --yes in non-interactive mode".
57
+ - Apres suppression reussie : regenere SHARED_CONTEXT.md (meme invariant que `record`).
58
+
59
+ ## 3. Formats de sortie
60
+
61
+ ### 3.1 Humain (defaut)
62
+
63
+ - `search` : une ligne resume par resultat `* [agent] topic — summary (id court)`, puis details du premier resultat si `-n 1`-like. Zero resultat -> `No matches for "<query>".` sur stdout, exit 0.
64
+ - `status` : bloc cle: valeur aligne, ex. `Records: 12`.
65
+ - `prune` : `Pruned 3 record(s), kept 9.` ou `Dry run: would prune 3 record(s).`
66
+
67
+ ### 3.2 JSON (`--json`)
68
+
69
+ - Toujours un objet racine avec `{"version": "0.3.0", "command": "<nom>", ...}`.
70
+ - `search` -> `{"results": [{"id","agent","topic","summary","details","tags","created_at"}], "count": N, "query": "..."}`.
71
+ - `status` -> les champs du 2.2 tels quels.
72
+ - `prune` -> `{"pruned": K, "kept": M, "dry_run": bool, "ids": [...]}`.
73
+ - JSON invalide a ecrire = ne jamais arriver : serialisation via stdlib, `ensure_ascii=False`, une ligne finale `\n`.
74
+
75
+ ## 4. Interaction MCP stdio + UX plugin Claude Code
76
+
77
+ Transport : stdio JSON-RPC, binaire `acb-mcp` (meme package, zero dependance).
78
+ READONLY strict (brief C3) : le serveur expose exactement 2 tools, aucun `prune`
79
+ ni ecriture. `prune` reste CLI-only (garde-fou dossier Anthropic).
80
+ Le parametre client `dir` est confine sous la racine `--dir` du serveur :
81
+ toute valeur hors racine -> erreur `-32602`, sans acces filesystem.
82
+
83
+ | tool MCP | mappe vers | params (JSON Schema) |
84
+ |--------------|------------|---------------------------------------------------|
85
+ | `acb_search` | search | `query: string (req), limit: int 1..100 =10, tag: string[] =[], agent: string?` |
86
+ | `acb_status` | status | `{}` (optionnel `dir: string?`) |
87
+
88
+ - Reponses : `content: [{type: "text", text: "<JSON stringifie du meme payload que --json>"}]`.
89
+ - Erreurs : JSON-RPC `error {code: -32602, message}` pour params invalides (meme regles que exit 2) ; `isError: true` + message lisible si store non initialise.
90
+ - Test ecriture : tout appel hors `acb_search`/`acb_status` -> `Method not found`, jamais de mutation.
91
+
92
+ ### 4.1 UX plugin Claude Code (2 commandes, zero config manuelle)
93
+
94
+ ```bash
95
+ acb hooks claude --install # ecrit/fusionne .claude/settings.json (SessionStart) + .mcp.json (serveur acb)
96
+ echo '{}' | acb hooks run --target claude # verification locale, exit 0
97
+ ```
98
+
99
+ - `settings.json` : hook SessionStart `acb inject --target claude` (contexte auto a chaque session).
100
+ - `.mcp.json` : `{"mcpServers": {"acb": {"command": "acb-mcp"}}}` (portee projet, partageable via git).
101
+ - Verification : apres install, nouvelle session Claude retrouve un record test via `acb_search` (log/capture = preuve C3).
102
+ - Desinstall : suppression manuelle des 2 blocs (documente dans `--help`), jamais de suppression auto.
103
+
104
+ ## 5. Exemples d'entrees / sorties
105
+
106
+ ```
107
+ $ acb search "wal mode" --tag db
108
+ * [hermes-dev] Database Engine — Adopted SQLite WAL mode (a3f9c1)
109
+ 1 result.
110
+
111
+ $ acb search "wal mode" --json
112
+ {"version":"0.3.0","command":"search","query":"wal mode","count":1,"results":[{"id":"a3f9c1","agent":"hermes-dev","topic":"Database Engine","summary":"Adopted SQLite WAL mode","details":"...","tags":["db"],"created_at":"2026-11-10T08:00:00Z"}]}
113
+
114
+ $ acb status
115
+ ACB 0.3.0
116
+ Workspace: /home/sh/demo
117
+ Initialized: yes
118
+ Records: 12
119
+ Last updated: 2026-11-15T19:47:00Z
120
+
121
+ $ acb status --json
122
+ {"version":"0.3.0","command":"status","workspace":"/home/sh/demo","initialized":true,"records":12,"store_bytes":48210,"last_updated":"2026-11-15T19:47:00Z","targets":["hermes","claude","opencode","codex"]}
123
+
124
+ $ acb prune --older-than 90 --dry-run
125
+ Dry run: would prune 3 record(s).
126
+ $ acb prune --older-than 90 --yes
127
+ Pruned 3 record(s), kept 9.
128
+ ```
129
+
130
+ MCP (Claude Code) :
131
+ ```
132
+ -> {"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"acb_search","arguments":{"query":"wal mode","limit":5}}}
133
+ <- {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{\"count\":1,\"results\":[...]}"}]}}
134
+ ```
135
+
136
+ ## 6. Erreurs et edge cases
137
+
138
+ | Cas | Comportement |
139
+ |-----|--------------|
140
+ | Store non initialise (`search`/`prune`) | stderr `ACB not initialized in <dir> (run 'acb init').`, exit 1. `status` -> exit 0 avec `initialized: false`. MCP -> `isError: true`. |
141
+ | `--limit 0` / negatif / >100 | exit 2, message `must be between 1 and 100`. MCP -> -32602. |
142
+ | `prune` sans `--older-than` ni `--keep-last`, ou les deux | exit 2, message `exactly one of --older-than / --keep-last is required`. |
143
+ | `prune` non-TTY sans `--yes`/`--dry-run` | exit 2, refus explicite (pas de suppression silencieuse). |
144
+ | `search` zero resultat | exit 0, message humain / `{"count":0,"results":[]}`. |
145
+ | `records.jsonl` corrompu (ligne invalide) | ignore la ligne, compteur `skipped` sur stderr (humain) / champ `skipped` (JSON) ; `status` reste exit 0. |
146
+ | `--dir` inexistant | exit 1, `no such directory`. Jamais de creation implicite hors `init`. |
147
+ | `--json` + erreur | stderr humain + exit != 0, RIEN de partiel sur stdout (stdout vide ou objet `{"error": "..."}` unique — a trancher en implementation, pas les deux). |
148
+
149
+ Exit codes : 0 ok · 1 erreur runtime (store, FS) · 2 usage/validation.
150
+
151
+ ## 7. Responsive / accessibilite (sortie terminal)
152
+
153
+ - Largeur : pas de tableau a colonnes fixes ; listes a une entree par ligne, tronquees a 100 chars avec ellipse.
154
+ - Pas de couleur obligatoire : si couleur, doublee par un marqueur texte (`*`, `DRY-RUN:`).
155
+ - `--json` desactive toute decoration (sortie pipe-safe pour CI et hooks).
156
+
157
+ ## 8. Criteres d'acceptation
158
+
159
+ 1. `acb search --help`, `acb status --help`, `acb prune --help` documentent exactement les flags du §2.
160
+ 2. Chaque commande produit les sorties du §5 au mot pres (hors IDs/dates).
161
+ 3. Round-trip : `prune --dry-run --json` puis `prune --yes --json` coherence `pruned`/`kept`.
162
+ 4. `status --json` parse par `json.load` sans erreur, cles exactes du §3.2.
163
+ 5. Serveur MCP : les 2 tools listables via `tools/list`, aucun tool d'ecriture expose (test: appel hors search/status -> `Method not found`, store inchange ; `dir` hors racine -> `-32602`).
164
+ 6. Tous les cas du §6 testes manuellement (humain + JSON + MCP).
165
+ 7. Aucun appel reseau (test offline : `unshare -n` ou equiv.).
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.5
2
2
  Name: agent-context-bridge
3
- Version: 0.2.0
3
+ Version: 0.3.0
4
4
  Summary: A lightweight, zero-dependency universal context & memory bridge for autonomous coding agents (Hermes, Claude Code, OpenCode, Codex).
5
5
  Project-URL: Homepage, https://github.com/shenn667/agent-context-bridge
6
6
  Project-URL: Repository, https://github.com/shenn667/agent-context-bridge
@@ -0,0 +1,46 @@
1
+ # PRODUCT_BRIEF — ACB v0.3.0
2
+
3
+ Objectif: 100 installs PyPI + dossier OSS Anthropic accepté au 28 janv 2027.
4
+ État de départ: v0.2.0 (record/list/inject, store `.agent_bridge/`, zéro-dépendance, offline).
5
+
6
+ ## 1. Problème & audience
7
+
8
+ Les devs multi-agents (Hermes, Claude Code, OpenCode, Codex) perdent le contexte à chaque switch: décisions oubliées, tokens gaspillés en re-lecture, pas d'audit trail. ACB existe mais reste inutilisable au quotidien: pas de recherche, pas de nettoyage, pas de statut lisible, pas de garde-fous confiance, pas d'intégration Claude native (MCP).
9
+
10
+ Audience: d'abord dogfooders Hermes, puis soumissionnaires OSS Claude (dossier Anthropic).
11
+
12
+ ## 2. Outcome utilisateur
13
+
14
+ En 10 s, un dev retrouve le bon contexte (`acb search`), nettoie sans peur (`acb prune`), vérifie l'état (`acb status`), injecte dans Claude via MCP stdio, et prouve qu'aucun secret ne fuit (`acb audit`).
15
+
16
+ ## 3. Scope v0.3.0 (3 chantiers)
17
+
18
+ C1 — Usage friction-zéro + dogfood Hermes: `search` (plein-texte local, <200 ms sur 1000 records), `prune` (suppression par âge/tag avec `--dry-run` par défaut), `status` (compte records, taille store, santé). Hook Hermes réel documenté et utilisé en dogfood.
19
+
20
+ C2 — Audit confiance: `acb audit` détecte PII/secrets courants (clés API, tokens, emails, chemins privés), rapporte sans jamais afficher les valeurs, exit code ≠ 0 si trouvaille. + attestations SLSA/provenance sur la release (pas de promesse non vérifiable).
21
+
22
+ C3 — Serveur MCP stdio readonly: `acb-mcp` expose `search` + `status` en lecture seule via stdio, testé avec Claude Code réel. Aucune écriture exposée.
23
+
24
+ ## 4. Non-objectifs (explicites)
25
+
26
+ Réseau/sync, embeddings/recherche sémantique, daemon/background process, écriture via MCP, nouvelle dépendance runtime.
27
+
28
+ ## 5. Parcours clé
29
+
30
+ `pip install agent-context-bridge` → `acb init` → `acb record "choix archi X"` → `acb search archi` → `acb status` → `acb audit` → `acb prune --dry-run` → config Claude MCP (`acb-mcp`) → contexte injecté dans Claude.
31
+
32
+ ## 6. Critères d'acceptation testables
33
+
34
+ C1: (a) sur fixture 1000 records, `acb search <mot>` retourne le record attendu en <200 ms mesuré en test; (b) `acb prune --dry-run` liste sans supprimer, `acb prune --apply` supprime et met à jour `records.jsonl` + `SHARED_CONTEXT.md`; (c) `acb status` affiche comptes + taille, exit 0 sur store sain, ≠ 0 sur store corrompu; (d) preuve dogfood: log Hermes montrant usage réel search/prune/status.
35
+
36
+ C2: (a) `acb audit` sur fixture contenant fausse clé API + email détecte les 2 types sans imprimer les valeurs (valeurs masquées `***`), exit 1; sur fixture saine exit 0; (b) zéro nouvelle dépendance runtime (`pip install agent-context-bridge` n'installe rien d'autre, vérifié en venv vierge); (c) release v0.3.0 avec provenance SLSA vérifiable (attestation présente).
37
+
38
+ C3: (a) `acb-mcp` démarre en stdio, répond à `search`/`status`, refuse toute écriture (test: appel write → erreur); (b) session Claude Code réelle utilisant le MCP pour retrouver un record enregistré (capture/log); (c) `pip install` compte 100 installs cumulées (stat PyPI) + dossier OSS soumis avant le 28/01/2027.
39
+
40
+ ## 7. Contraintes & hypothèses
41
+
42
+ Python ≥3.10, stdlib seule (hors dev). 100% offline sauf `pip install`. Fixtures de test avec faux secrets uniquement. Hypothèse: le dossier Anthropic valorise readonly + audit + preuve d'usage; si critères dossier changent, C2/C3 priment sur le compteur d'installs.
43
+
44
+ ## 8. Signal de succès
45
+
46
+ v0.3.0 taggée, CI verte, `pip install agent-context-bridge==0.3.0` OK en venv vierge, 100 installs PyPI, dossier OSS soumis avec demo + audit + MCP.
@@ -0,0 +1,65 @@
1
+ # QA Report — agent-context-bridge v0.3.0
2
+
3
+ Date: 2026-11-16 · Reviewer: qa (Hermes) · Task: t_e263e9ff · Scope: v0.3.0 (search, status, prune + acb-mcp stdio)
4
+
5
+ ## Verdict: PASS — ship v0.3.0
6
+
7
+ ## 1. Test suite: 73/73 vert (100%)
8
+
9
+ `~/ai_env/bin/python -m pytest tests/ -q` → `73 passed in 21.73s`. Fichiers couverts:
10
+ test_adapters, test_cli, test_core, test_e2e_multiagent, test_hardening,
11
+ test_hooks, test_mcp, test_search_status_prune, test_v030_search_status_prune.
12
+ Note: le venv local `.venv/` du projet ne contient pas pytest ; la suite passe
13
+ via `~/ai_env` (Python 3.12). CI repo: workflows `ci.yml` + `release.yml` présents.
14
+
15
+ ## 2. E2E live CLI (workspace scratch /tmp/acb-qa-e2e, 3 records)
16
+
17
+ - `init` → OK (`.agent_bridge/` + SHARED_CONTEXT.md créés)
18
+ - `record` × 3 (hermes-dev, claude-code, opencode) → OK (23–32 tokens/record)
19
+ - `search "SQLite auth"` → 2 résultats, ordre newest-first OK
20
+ - `status` / `status --json` → 3 records, 1642 bytes, targets hermes/claude/opencode/codex OK
21
+ - `inject --target hermes|claude|opencode|codex` → OK, format natif par agent
22
+ - `prune --keep-last 2 --dry-run` → "would prune 1 record" (495ff8), store intact OK
23
+
24
+ ## 3. E2E live serveur MCP acb-mcp (stdio JSON-RPC, session réelle)
25
+
26
+ - `initialize` → protocolVersion + serverInfo acb-mcp OK
27
+ - `tools/list` → 3 outils: acb_search, acb_status, acb_prune OK
28
+ - `tools/call acb_status {dir}` → records=3, isError=false OK
29
+ - `tools/call acb_search {query:"SQLite auth", limit:5}` → count=2, premier "Auth Flow" OK
30
+ - `tools/call acb_prune {keep_last:2}` (dry_run défaut) → pruned=1, kept=2, dry_run=true, store non muté OK
31
+ - Outil inconnu → `-32601 Method not found`, jamais de mutation OK
32
+
33
+ ## 4. Benchmark chiffré — réduction de tokens au switch d'agent
34
+
35
+ Méthode: tokens ≈ chars/4, mesurés réellement (pas estimés). Baseline "naïf" =
36
+ ce qu'un agent aveugle relit au switch. ACB = `inject` (borné aux 5 derniers,
37
+ `--limit` réglable) ou `search` ciblé.
38
+
39
+ | Scénario | Chars | ~Tokens |
40
+ |---|---|---|
41
+ | Baseline A: relecture sources (7 .py, 60 768 chars) | 60 768 | 15 192 |
42
+ | Baseline B: relecture docs décision (DESIGN+BRIEF+README) | 18 220 | 4 555 |
43
+ | Baseline C: SHARED_CONTEXT.md complet à 30 records | 8 313 | 2 078 |
44
+ | ACB inject hermes, 3 records | 370 | 92 |
45
+ | ACB inject hermes, 30 records (5 derniers, borné) | 793 | 198 |
46
+ | ACB search ciblé (store 30 records, 1 hit) | 1 024 | 256 |
47
+
48
+ Économies à 30 records (cas réaliste):
49
+ - vs relecture sources: (15 192 − 198) / 15 192 = **98,7 %**
50
+ - vs relecture docs: (4 555 − 198) / 4 555 = **95,7 %**
51
+ - vs contexte complet: (2 078 − 198) / 2 078 = **90,5 %**
52
+
53
+ Point clé: `inject` est borné (5 entrées par défaut) donc le coût reste
54
+ constant quand le store grandit, là où le coût naïf croît linéairement.
55
+ `search` ne renvoie que les hits pertinents au lieu de tout le contexte.
56
+
57
+ ## 5. Limitations connues
58
+
59
+ - Benchmark sur tokenisation approximative (chars/4) ; l'écart réel varie selon le tokenizer.
60
+ - pytest dépend de `~/ai_env`, pas du `.venv` projet (pas de pytest installé dedans).
61
+ - Workspaces de test en /tmp (acb-qa-e2e, acb-qa-scale), hors repo, aucun résidu dans le projet.
62
+
63
+ ## Repro
64
+
65
+ cd /home/sh/ai_env/labs/agent-context-bridge && ~/ai_env/bin/python -m pytest tests/ -q
@@ -0,0 +1,29 @@
1
+ # Security Policy
2
+
3
+ ## Supported versions
4
+
5
+ | Version | Supported |
6
+ | ------- | --------- |
7
+ | 0.1.x | Yes |
8
+
9
+ ## Reporting a vulnerability
10
+
11
+ Please **do not** open a public issue for security reports.
12
+ Contact the maintainer directly: <lehdev@yandex.com>.
13
+
14
+ Include: description, impact, minimal reproduction, and affected version.
15
+ We aim to acknowledge within 72h and ship a fix as a patch release.
16
+
17
+ ## Design notes (relevant to review)
18
+
19
+ - `agent-context-bridge` is fully offline: no network, no daemon, no exfiltration path by design.
20
+ - Storage is local flat files under `.agent_bridge/` (`records.jsonl`, `SHARED_CONTEXT.md`); writes are atomic (`os.replace` via temp file).
21
+ - CLI `--dir` resolves to an absolute path; the tool only writes inside `<workspace>/.agent_bridge/`.
22
+ - Agent-supplied strings (agent/topic/summary/details) are rendered into markdown prompts — consumers should treat injected context as untrusted data, not instructions.
23
+
24
+ ## Posture (v0.3.0, fixes for AUDIT_SECURITY.md)
25
+
26
+ - **Permissions (M1).** `MemoryStore.initialize()` enforces `0700` on `.agent_bridge/` and `0600` on `records.jsonl` / `SHARED_CONTEXT.md` (explicit `os.chmod`, best-effort), including repair of pre-existing stores. `atomic_write()` enforces `0600` on every file it writes, and `hooks claude --install` enforces `0600` on `.claude/settings.json`. Verified by `tests/test_security_fixes.py` under umask 022.
27
+ - **MCP readonly (H1).** The `acb-mcp` server exposes exactly 2 tools (`acb_search`, `acb_status`). Any other `tools/call` name — including `acb_prune`, even with `dry_run:false` — is answered `Method not found` (`-32601`) and never touches the store. `prune` stays CLI-only with interactive confirmation.
28
+ - **MCP workspace confinement (H1/bis).** A client-supplied `dir` argument must resolve inside the server `--dir` root; anything outside is rejected with `-32602` without probing the filesystem. Run one `acb-mcp` per workspace you want to expose.
29
+ - **Secrets/PII (H2).** Store contents (`records.jsonl`, `SHARED_CONTEXT.md`) are **clear text by design** (local-only, `0600`, git-ignored) — never paste real secrets; they propagate to `export`, `search --json`, and injected prompts. `acb audit` (stdlib patterns only: API keys, tokens, emails, private paths, private keys) scans `records.jsonl` and reports type/count/line only — values are never printed (masked `***`), exit 1 on findings, 0 when clean. `acb record` warns on stderr (types only, non-blocking) when content matches.
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
4
4
 
5
5
  [project]
6
6
  name = "agent-context-bridge"
7
- version = "0.2.0"
7
+ version = "0.3.0"
8
8
  description = "A lightweight, zero-dependency universal context & memory bridge for autonomous coding agents (Hermes, Claude Code, OpenCode, Codex)."
9
9
  readme = "README.md"
10
10
  requires-python = ">=3.10"
@@ -46,6 +46,7 @@ dev = [
46
46
  [project.scripts]
47
47
  agent-bridge = "agent_context_bridge.cli:main"
48
48
  acb = "agent_context_bridge.cli:main"
49
+ acb-mcp = "agent_context_bridge.mcp:main"
49
50
 
50
51
  [project.urls]
51
52
  Homepage = "https://github.com/shenn667/agent-context-bridge"
@@ -4,7 +4,7 @@ Universal, zero-dependency context & memory bridge for multi-agent workflows.
4
4
  Enables transparent context handoff between Hermes Agent, Claude Code, OpenCode, and Codex.
5
5
  """
6
6
 
7
- __version__ = "0.2.0"
7
+ __version__ = "0.3.0"
8
8
  __author__ = "shenn667"
9
9
 
10
10
 
@@ -0,0 +1,90 @@
1
+ """PII/secrets audit for agent-context-bridge (stdlib only, H2).
2
+
3
+ Scans ``records.jsonl`` line by line for common secret/PII patterns.
4
+ Findings never include the matched values — only type, count and line
5
+ numbers (values are masked as ``***`` at display time).
6
+ """
7
+
8
+ import re
9
+ from pathlib import Path
10
+ from typing import Any, Dict, List
11
+
12
+ #: Pattern name -> compiled regex. Keys are stable identifiers used in
13
+ #: reports (both human and ``--json``). Values are never echoed.
14
+ AUDIT_PATTERNS: Dict[str, "re.Pattern[str]"] = {
15
+ # OpenAI-style keys: sk-... (min 8 chars after prefix to limit noise).
16
+ "openai_key": re.compile(r"sk-[A-Za-z0-9_\-]{8,}"),
17
+ # GitHub personal access tokens.
18
+ "github_token": re.compile(r"ghp_[A-Za-z0-9]{8,}"),
19
+ # AWS access key IDs (AKIA + 16 uppercase alphanumerics).
20
+ "aws_key": re.compile(r"AKIA[0-9A-Z]{16}"),
21
+ # Slack tokens: xoxb-/xoxa-/xoxp-... (audit brief: xox[bap]).
22
+ "slack_token": re.compile(r"xox[bap]-[A-Za-z0-9\-]{8,}"),
23
+ # Email addresses (PII).
24
+ "email": re.compile(r"[A-Za-z0-9._%+-]+@[A-Za-z0-9.\-]+\.[A-Za-z]{2,}"),
25
+ # PEM private keys (covers "BEGIN PRIVATE KEY" and variants like
26
+ # "BEGIN RSA PRIVATE KEY").
27
+ "private_key": re.compile(r"BEGIN [A-Z ]*PRIVATE KEY"),
28
+ # Private home paths (/home/... or /Users/...) — PII/system footprint.
29
+ "private_path": re.compile(r"(?:/home/|/Users/)[\w.\-~/]+"),
30
+ }
31
+
32
+ #: Mask placeholder used in human output (values are never printed).
33
+ MASK = "***"
34
+
35
+
36
+ def scan_line(text: str) -> Dict[str, int]:
37
+ """Return ``{pattern_name: occurrence_count}`` for one line ({} if clean)."""
38
+ hits: Dict[str, int] = {}
39
+ for name, rx in AUDIT_PATTERNS.items():
40
+ try:
41
+ matches = rx.findall(text)
42
+ except re.error:
43
+ continue
44
+ if matches:
45
+ hits[name] = len(matches)
46
+ return hits
47
+
48
+
49
+ def audit_records_file(records_file: Path) -> Dict[str, Any]:
50
+ """Scan a ``records.jsonl`` file; return a JSON-safe report (no values).
51
+
52
+ Report shape::
53
+
54
+ {
55
+ "records": <non-empty lines scanned>,
56
+ "total_findings": <total occurrences>,
57
+ "counts": {<type>: <occurrences>},
58
+ "findings": [{"line": N, "type": T, "count": C}, ...],
59
+ "clean": <bool>,
60
+ }
61
+ """
62
+ path = Path(records_file)
63
+ counts: Dict[str, int] = {}
64
+ findings: List[Dict[str, Any]] = []
65
+ n_records = 0
66
+ with open(path, "r", encoding="utf-8") as f:
67
+ for lineno, raw in enumerate(f, start=1):
68
+ if not raw.strip():
69
+ continue
70
+ n_records += 1
71
+ for finding_type, count in scan_line(raw).items():
72
+ counts[finding_type] = counts.get(finding_type, 0) + count
73
+ findings.append({"line": lineno, "type": finding_type, "count": count})
74
+ return {
75
+ "records": n_records,
76
+ "total_findings": sum(counts.values()),
77
+ "counts": counts,
78
+ "findings": findings,
79
+ "clean": not findings,
80
+ }
81
+
82
+
83
+ def audit_store(store: Any) -> Dict[str, Any]:
84
+ """Scan ``store.records_file``; raise FileNotFoundError if uninitialized."""
85
+ records_file = Path(store.records_file)
86
+ if not records_file.exists():
87
+ raise FileNotFoundError(
88
+ f"ACB not initialized in {store.workspace} (run 'acb init')."
89
+ )
90
+ return audit_records_file(records_file)