agentsmesh 0.39.0 → 0.41.0

package/CHANGELOG.md

@@ -1,5 +1,98 @@
 # Changelog
 
+## 0.41.0
+
+### Minor Changes
+
+- 3bbf68b: Lessons are harder to lose and easier to use correctly, after a full manual QA pass.
+
+  Team merges: if git could not start the lessons merge driver, it kept only your side of `lessons.json` with no conflict markers, and every check still passed. Now `lessons validate`, `check` and `generate --check` fail while the file is missing the other branch's lessons, and tell you to run `agentsmesh lessons resolve` before `git add`. The driver is also only saved when git can start it later (npx caches and package-script bin folders on PATH no longer count, and the npx form needs agentsmesh at the repository root or installed globally). `lessons resolve` now works again after you fix a broken side by hand in the file.
+
+  The recall hook never breaks your tool: a log file it cannot write, or a bad line in a log, no longer makes it fail or lose a lesson for the session. A failed read (for example reading a file that does not exist yet) is no longer counted against a later write. A multi-file patch shows each warned rule once and stays under the size cap. Invisible and look-alike characters can no longer fake the end of the recalled-lessons block. An unreadable graph is now also reported when a session starts with no prompt. The hook does nothing in a folder with no lessons project, such as your home folder.
+
+  The `lessons` CLI works from any subfolder of a project, like git. It refuses an unquoted multi-word rule (instead of saving only its first word) and a single-value flag given twice. Re-adding a lesson says what changed. A regex the linear engine cannot run is dropped with a `DEAD_COMMAND_PATTERN` warning when the lesson has another trigger, or refused as `UNRECALLABLE_LESSON` (exit 2) when it is the only one. Every lessons command, and every MCP lessons tool, now explains an unreadable graph (merge conflict, bad JSON, `SCHEMA_INVALID`, newer version) instead of printing parser output. A negated glob (`!path`) is flagged as broad. A lessons write that lost its lock (the process was paused past the 60 s stale window) refuses to save instead of erasing a later write, and a lock dated in the future no longer blocks writers.
+
+  MCP lessons tools never create a lessons graph in your home folder or outside a project: they use the nearest lessons folder, then `agentsmesh.yaml`, then the git repository root, and otherwise refuse writes with `NO_PROJECT`. `lessons_show` accepts a lesson id, `lessons_query` with `always` honors `session` and `no_dedup`, and refused writes return `VALIDATION_FAILED` with the finding codes.
+
+  Installed pack hooks are no longer lost: two packs on the same event are combined, a pack adds to an extend's hooks for that event, and a local `hooks.yaml` event keeps the pack's hooks after its own. Before, `agentsmesh init --lessons` (which adds the recall hook locally) silently removed installed pack hooks for the same event. Extends layers still override per event, as documented. To drop a pack hook, uninstall the pack or leave `hooks` out of its features.
+
+- 2cb8b48: The MCP server now tells every client about lessons when it connects, and says something true in both states.
+
+  Where a project has lessons, the server hands over the same recall and capture contract that `init --lessons` writes into your instruction file. That matters for a plugin: a plugin can ship skills and servers but never your instruction file, so a plugin-only install previously had no standing instruction at all and recall depended on the agent opening the skill first. The obligations are phrased in tool names rather than shell commands, since a client reaching the server this way may have no shell.
+
+  Where a project has no lessons, the server says so plainly and explains how to start one. It does not name a graph file you do not have, does not point at a skill you never installed, and mandates nothing. This matters because the server also carries the configuration tools and is documented on its own: most people who wire it up never opted into lessons, and they should not be told to query a memory that cannot answer.
+
+- cea0c7e: Lessons now hold up for teams, for more tools, and against a graph you did not write yourself.
+
+  Teams: two branches that both capture lessons now merge cleanly. The git merge driver merges each lesson field by field, and every clone gets the driver the next time it runs `agentsmesh generate` (or `init --lessons`), so it no longer depends on one person's setup. If a merge still leaves conflict markers, the new `agentsmesh lessons resolve` combines both sides. `agentsmesh check` and `generate --check` now fail when `lessons.json` cannot be read (a merge conflict, a corrupt file, a newer schema), instead of passing while recall is silently off. The lessons lock no longer loses a lesson when many agents write at once. A fresh clone no longer prunes lessons whose files are merely not created yet: a glob counts as dead only when git history shows its file was deleted or renamed. Generated recall hooks run `npx --no --offline agentsmesh` when the project depends on agentsmesh, so teammates without a global install still get recall.
+
+  More tools: the recall hook now answers Gemini CLI's `BeforeAgent`, Cursor's `sessionStart` and `postToolUseFailure`, and GitHub Copilot's `sessionStart` and `postToolUseFailure`. Codex `apply_patch` edits get recall for the files they touch, subagents get their own session dedup, and the hook and MCP server find the lessons project from a subdirectory. Target descriptors (including plugins) can declare `hookContextEvents` so recall is only wired to events whose output reaches the model.
+
+  Capture and effectiveness: failures are read from the field Claude Code actually sends, keyed on the command that really ran, and user interrupts are no longer counted. A `--trigger-file` path outside the project is rejected instead of being stored where it could never fire. The outcome log is on by default (turn it off with `"outcomeLog": false` in `.agentsmesh/lessons/config.json` or `AGENTSMESH_LESSONS_OUTCOME_LOG=0`), and a lesson counts as missed only when the same action fails again in the same session within 30 minutes, so `validate` and `stats` stop flagging lessons that work.
+
+  Safety: recalled rules are delivered one per line inside a `<recalled-lessons>` block, with ids, and every CLI and MCP answer is size-capped, so a hostile rule cannot pose as a system message or flood the context. `file_glob` triggers use a linear-time matcher over a safe glob subset; other glob syntax is rejected with `UNSAFE_GLOB_PATTERN` and never matches, so a crafted glob can no longer stall recall. `recallLimit` and `recallMaxTokens` in config.json are capped at 50 and 8000, `lessons query --always` has the same budget as the hook, and legacy migration refuses index paths outside `.agentsmesh/lessons/`.
+
+- 98cb625: **Upgrade notes.** Most projects need to do nothing, but check these after you upgrade:
+  - Run `agentsmesh generate` once. Hooks for Gemini CLI, GitHub Copilot, Cursor and Windsurf, lessons recall hooks, and hooks from installed packs can be generated differently now, so `agentsmesh generate --check` reports drift until you regenerate.
+  - Run `agentsmesh lessons validate`. Some lesson file triggers no longer match anything, and `lessons validate` and `agentsmesh lint` now report them as `UNSAFE_GLOB_PATTERN` errors: `**` inside a name (`src/**.ts`, write `src/**/*.ts`), extglobs (`+(a|b)`, write `{a,b}`) and ranges (`{1..3}`, write `{1,2,3}`).
+  - Gemini CLI hooks match exact tool names now. `Bash`, `Edit`, `Write` and `Read` reach Gemini's own tools (before, they matched nothing there), but a partial Gemini name such as `shell` no longer matches: use the full name (`run_shell_command`) or the Claude Code name (`Bash`). A `UserPromptSubmit` hook now also runs on Gemini, as `BeforeAgent`.
+  - `SessionStart` and `PostToolUseFailure` hooks now also reach GitHub Copilot, and `PostToolUseFailure` hooks reach Cursor.
+  - The lessons outcome log (`.agentsmesh/lessons/outcome-log.jsonl`, local and gitignored) is on by default, and turning telemetry off no longer stops it. Turn it off with `"outcomeLog": false` in `.agentsmesh/lessons/config.json` or `AGENTSMESH_LESSONS_OUTCOME_LOG=0`.
+  - `agentsmesh lessons` exits 2 for a flag with an empty value, so a script that runs `--cmd "$CMD"` fails when `CMD` is empty.
+  - Installing the same whole source again rebuilds its pack, so files you added by hand inside `.agentsmesh/packs/<name>/` are removed, as `refresh` already did. Keep your own changes in `.agentsmesh/`, outside `packs/`.
+
+### Patch Changes
+
+- 579a6c5: `agentsmesh check` now gives the fix that matches the drift it found, instead of always saying "Run 'agentsmesh merge' to resolve, or 'agentsmesh generate --force' to accept current state." For canonical or generated-output drift (including the stale hashes a `merge` can leave) it points to plain `agentsmesh generate`; only changed locked features (`collaboration.strategy: lock`) get the `generate --force` advice. A `.agentsmesh/.lock` with git conflict markers is now reported as a lock conflict with the `agentsmesh merge` fix (and `lockConflict: true` in `--json`, in the MCP `check` tool result, and in the `LockSyncReport` returned by the programmatic `check()`), instead of "Not initialized for collaboration".
+- 499f7c7: The `agentsmesh lessons` commands handle bad input clearly instead of quietly doing the wrong thing.
+
+  A flag that needs a value but gets none now fails with exit 2 and "--flag needs a value". Before, it was ignored: `deprecate X --superseded-by` deprecated without the supersede link, and `query --session` skipped dedup. A value that starts with `--` can be passed as `--flag=value` (for example `--rule="--no-verify is forbidden"`), and the error for an unknown "flag" that is really text says so. `prune --cap abc` no longer falls back to the default cap. `lessons help [subcommand]` works.
+
+  `lessons add` uses exit 2 for every input error, with messages that name the flag: `--scope` other than `always`, a topic id that is not kebab-case (it suggests one), `--new-topic` without a non-blank `--topic-summary`, and an unsafe `--trigger-file` glob, which is now refused before any trigger id is made. A change the graph validator refuses also exits 2, and the message is plain: `Refused to save the lessons graph: … Nothing was written.` Internal names such as `mutateLessonsGraph:` no longer show in messages. Repeated `--evidence` refs are stored once. The 2000-character rule limit counts characters, so an emoji counts once.
+
+  `--trigger-file` is stored in one form: surrounding spaces and a leading `./` are dropped, so `./src/a.ts` reuses the `src/a.ts` trigger. A relative path that climbs out of the project (`../x.ts`), the project root, or an existing folder is rejected with a clear reason; for a folder it suggests `folder/**`. The same applies to the MCP `lessons_add` tool. A `--trigger-cmd` with a `\u{…}` escape is rejected, as the docs said.
+
+  `query` says when a legacy `index.yaml` store could not be migrated, instead of printing only "(no matches)". `import-md --migrated-at` must be a real date. `AGENTSMESH_LESSONS_TELEMETRY` and `AGENTSMESH_LESSONS_OUTCOME_LOG` also accept `true`/`false`, `yes`/`no` and `on`/`off`. `lessons query` warns when `config.json` has a switch that is not `true`/`false` (such as `"outcomeLog": "no"`) or is not a JSON object.
+
+  Smaller fixes: `show <lesson>` includes the rationale, `journal` marks deprecated and superseded lessons, `validate --json` names the error codes, messages end with a period, the `--ids` help text says what it does, and the docs keyword example uses one `--trigger-kw` per keyword.
+
+- b2bfc56: The lessons recall hook, the lessons.json merge driver and the lessons logs handle more edge cases correctly.
+
+  Recall hook: it reads a payload over 1 MB to the end before ignoring it, so the host no longer gets a broken pipe, and it reads JSON that starts with a UTF-8 BOM. An event name it does not know (such as Gemini's `BeforeTool`) now does nothing instead of answering as `PostToolUse`; a payload with no event name is still a tool call. Copilot's VS Code compatible `SessionStart` (with `initial_prompt`) gets task recall. The project now comes from the touched file first, so in a monorepo a package's own lessons apply to its files, and a `cwd` outside the project no longer hides it. A decomposed (NFD) path matches its glob. On a prompt, the note about hidden matches is back: at most 5 keyword rules are shown, the always-on lessons keep their own budget, and the hook says what either cap left out. The recurrence warning counts only failures from the last 24 hours (it used to count every failure ever, "failed 833×"). A Cursor `permission_denied` is not recorded as a failure, a failed command's nudge no longer suggests a file glob, and recalls running at the same time no longer lose each other's session dedup entries.
+
+  Logs and files: an append after a line cut off mid-write starts a new line instead of gluing two records, the logs are capped by size (a single huge line is dropped) and readers read only the newest part, a read-only `lessons.json` is not written over and a save keeps its file mode, a `.lessons.lock` that is a file gets a clear message instead of `ENOTDIR`, a UTF-8 BOM in `lessons.json` or `config.json` is ignored, a writer waiting on a busy lock says once who holds it, and old temp files and stale lock folders are cleaned up.
+
+  Merge: a trigger or topic deleted on one branch stays deleted when the other branch did not change it and no lesson uses it. `lessons resolve` refuses to save a result with errors when it had to rebuild the sides from conflict markers (and keeps the markers), warns when the markers have no merge base, counts lessons after same-id renames, and names the right next step for a merge, rebase, cherry-pick or revert (none outside git). The merge driver falls back to the bare command when npx is missing but agentsmesh is on PATH. `init` and `generate` ask you to re-run `init --lessons` when the recall hook command in hooks.yaml no longer matches the project's agentsmesh dependency, and `generate` no longer repeats "Kept your own lessons.json merge driver" on every run.
+
+- e2f4219: Installing a changed pack again now updates it in place. Before, if the source dropped a folder (say `commands/`), running `agentsmesh install` again with the same `--name` failed with "Auto-generated pack name … collides", and without `--name` it added a second pack from the same source that kept the removed files. Now the install finds the pack from the same source, `--target` and `--as` (by `--name`, by feature set, or the one pack that covers the whole source). When both cover the whole source, it replaces the pack's contents like `refresh`, so files removed at the source go away. A picked subset still merges, and packs split by `--path`, `--as` or pick stay separate. A re-install without `--name` also keeps the pack's name (it used to rename a local pack to an auto-generated name), and `--dry-run` shows the pack it would update. A `--name` that belongs to a pack from another source now fails with a clear message that names the pack.
+
+  Skill folders are no longer dropped because of their name. A source with `rules/` next to `skills/my_skill/` or `skills/S1/` used to look like a lone rules folder, so its skills, README and LICENSE were skipped without a word. Any skill folder name now counts, except names that start with `.` or `_`.
+
+  `mcp.json`, `hooks.yaml`, `permissions.yaml` and `ignore` at the root of a source without `.agentsmesh/` are still not installed (settings install only from a source's `.agentsmesh/` folder), but install now prints one warning that names each skipped file.
+
+- 7857ff1: The MCP `check` and `generate` tools now tell the same story as the CLI. `check` runs the same check as `agentsmesh check`, so an unreadable `.agentsmesh/lessons/lessons.json` (a merge conflict, bad JSON, a schema error or a newer version) is now reported in a new `lessonsGraphError` field, with the same text as the CLI JSON `error`, instead of looking like a clean result. `generate` sets `lockfileUpdated` only when the run really rewrote `.agentsmesh/.lock`; a run that changes nothing leaves the lock alone and now says `false`.
+- b7ab200: Internal-only: removed dead code and collapsed duplicated generators. Two exported helpers had no caller outside their own tests since the commit that introduced them, and one install helper was fully superseded by a more general sibling. Fifteen targets each carried the same four-line ignore generator differing only in a path constant, and the pack writer and merger each repeated the same copy-into-subdirectory loop three times; both now call one shared helper. No behaviour changes: every generated artifact is byte-identical.
+- ab63a79: `agentsmesh generate` no longer rewrites `.agentsmesh/.lock` when nothing changed. Before, a run that printed "Nothing changed" still wrote a new `generated_at`, so the git tree was dirty after every `generate` and each teammate's run showed a lock diff. Now the lock is rewritten only when its `checksums`, `extends`, `packs` or `outputs` change; otherwise the file stays byte-for-byte the same. `generated_at`, `generated_by` and `lib_version` now describe the last run that changed the lock. `check`, `generate --check` and `watch` work as before.
+- cab70b6: On Windows, agentsmesh now copes when another process is removing or reading the same lock folder or file at that moment. A command waiting for a busy lock (for example `generate`, `install` or a lessons write) no longer crashes with `EPERM`, and lessons recalls running at the same time no longer lose a session dedup entry. Short `EPERM`, `EACCES` and `EBUSY` errors are retried for a moment, as renames already were; an error that does not clear still stops the command.
+
+## 0.40.0
+
+### Minor Changes
+
+- 4fbf6a6: **Fixed — lessons over MCP no longer require an initialized project.** `lessons_query` and the other lessons tools rejected every call in a directory without `agentsmesh.yaml` with `NO_PROJECT`, while the CLI did the opposite: `agentsmesh lessons query` printed a setup hint and exited 0, and `lessons add` created the graph. Since MCP is the documented path for an agent with no shell — and the only path a Claude Code plugin has — the feature was unreachable for exactly the callers it was meant to serve. All five lessons tools now fall back to the working directory. Config tools such as `generate` still require a project and still report `NO_PROJECT`.
+
+### Patch Changes
+
+- 5989d1f: **Fixed — a slash command in prose is no longer rewritten as a path.** `/plugin`, `/config`, `/memory` and friends are indistinguishable from a one-segment root-absolute path, and reference resolution is existence-gated, so the corruption appeared only once a repository grew a directory of that name: a repo with `plugin/` saw every `/plugin` in its skills and rules silently rewritten to `plugin` on the next `generate`. Directory names like `config`, `docs`, `test` and `build` make this likely in an ordinary project, and agent-facing documentation is full of slash commands.
+
+  A root-absolute token now has to look like a path to be treated as one — a further segment, a file extension, or a trailing slash. `/docs/x.md`, `/AGENTS.md` and `/docs/` still rewrite; `/docs` is left alone. Write `/docs/` or `docs/` when you mean the directory.
+
+- 5e8ef3b: **Added — the recall log records which action it was for.** `lessons stats` reports a held-rate and correctly calls it a weak upper bound, because a delivery with no recorded repeat is not proof of prevention. The missing piece was exposure: the log proved a recall happened but not for which action, so occurrences per action could not be counted and no before/after rate was computable.
+
+  Each recall record now carries the normalized `contextKey` the outcome log already stores (`file:src/x.ts`, `cmd:git commit`, or `none` for a keyword-only query), so this adds no content the logs did not already hold and never records a raw command. Telemetry remains opt-in and off by default. Records written before this change have no key and are reported as such rather than silently skewing an average.
+
+- ead5625: AgentsMesh can now be listed in the official MCP registry. The published package declares `mcpName`, the field the registry reads to confirm that the npm package and the registry entry share an owner — without it a submission is rejected outright. The registry manifest `server.json` also stops pinning an npm version, so it can no longer advertise a release that has been superseded, and its remaining version field is written by `changeset version` instead of by hand.
+
 ## 0.39.0
 
 ### Minor Changes

package/README.md

@@ -113,7 +113,7 @@ agentsmesh lessons query --file src/cli/output.ts --session auto
 # -> "Normalize CLI display paths to forward slashes"
 ```
 
-`agentsmesh init --lessons` wires the loop once: an always-on rule in `_root.md`, a `lessons` skill where supported, recall and capture hooks on hook-capable tools, and matching MCP tools (`lessons_query`, `lessons_add`) for agents without shell access. Rules can be scoped by file, command, or keyword, or always-on with `--scope always`.
+`agentsmesh init --lessons` wires the loop once: an always-on rule in `_root.md`, a `lessons` skill where supported, recall and capture hooks on hook-capable tools, and matching MCP tools (`lessons_query`, `lessons_add`) for agents without shell access. Rules can be scoped by file, command, or keyword, or always-on with `--scope always`. A git merge driver, set up by `init --lessons` and then by `generate` in every clone, combines lessons captured on two branches; `agentsmesh lessons resolve` repairs a conflict that slips through.
 
 Full walkthrough: [Teach your AI agents with lessons](https://samplexbro.github.io/agentsmesh/guides/lessons/) · [`agentsmesh lessons` reference](https://samplexbro.github.io/agentsmesh/cli/lessons/)