@explyt/ai-agent 0.5.1 → 0.6.0-dogfood.2

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 (71) hide show
  1. package/README.md +3 -3
  2. package/THIRD-PARTY-NOTICES.md +24 -21
  3. package/agent-docs/agents.md +33 -6
  4. package/agent-docs/ci.md +3 -2
  5. package/agent-docs/mcp.md +164 -9
  6. package/agent-docs/plugins.md +66 -0
  7. package/agent-docs/rules.md +11 -14
  8. package/agent-docs/settings.md +148 -18
  9. package/agent-docs/skills.md +63 -10
  10. package/agent-docs/web-search.md +68 -2
  11. package/dist/cli/account.js +1 -0
  12. package/dist/cli/atomic-write.js +18 -0
  13. package/dist/cli/brand-profile.js +10 -6
  14. package/dist/cli/engine.js +36 -12
  15. package/dist/cli/enterprise-login.js +1 -0
  16. package/dist/cli/index.js +53 -4
  17. package/dist/cli/install-lock.js +2 -4
  18. package/dist/cli/install-process.js +2 -2
  19. package/dist/cli/plugin.js +1 -0
  20. package/dist/cli/settings-lock.js +1 -1
  21. package/dist/cli/update-seen.js +1 -1
  22. package/dist/cli/update.js +1 -1
  23. package/dist/cli/user-extensions-contract.js +5 -0
  24. package/dist/cli/user-extensions.js +1 -1
  25. package/dist/extensions/ask-user-question.js +1 -1
  26. package/dist/extensions/bash.js +1 -1
  27. package/dist/extensions/custom-provider.js +1 -1
  28. package/dist/extensions/explyt-account.js +1 -1
  29. package/dist/extensions/hello.js +1 -1
  30. package/dist/extensions/identity.js +1 -1
  31. package/dist/extensions/login-menu.js +1 -1
  32. package/dist/extensions/mcp.js +1 -1
  33. package/dist/extensions/messaging.js +1 -0
  34. package/dist/extensions/misc-hacks.js +1 -1
  35. package/dist/extensions/notify.js +1 -1
  36. package/dist/extensions/plugins.js +1 -0
  37. package/dist/extensions/policy.js +1 -1
  38. package/dist/extensions/rules.js +1 -1
  39. package/dist/extensions/session-title.js +1 -1
  40. package/dist/extensions/skills.js +1 -1
  41. package/dist/extensions/subagents.js +2 -2
  42. package/dist/extensions/telegram.js +1 -1
  43. package/dist/extensions/telemetry.js +1 -1
  44. package/dist/extensions/todo.js +1 -1
  45. package/dist/extensions/tool-rows.js +1 -1
  46. package/dist/extensions/tui.js +1 -1
  47. package/dist/extensions/update-notice.js +1 -1
  48. package/dist/extensions/user-extensions.js +1 -1
  49. package/dist/extensions/web-access.js +1 -1
  50. package/dist/extensions/write.js +1 -1
  51. package/dist/install/installer.js +14 -13
  52. package/dist/mcp-adapter.js +179 -216
  53. package/dist/rpiv-ask-user-question/chunk-AS7SJKG3.js +1 -1
  54. package/dist/rpiv-ask-user-question/{chunk-V6PM4YRC.js → chunk-IRYKQOMH.js} +11 -7
  55. package/dist/rpiv-ask-user-question/{chunk-CDNB7COL.js → chunk-TDITPATL.js} +357 -189
  56. package/dist/rpiv-ask-user-question/{chunk-NXE76BE4.js → chunk-YWUYYQVK.js} +7 -4
  57. package/dist/rpiv-ask-user-question/index.js +419 -90
  58. package/dist/rpiv-todo/{chunk-RYUIY66D.js → chunk-4NSYSZHX.js} +2 -2
  59. package/dist/rpiv-todo/{chunk-7UKL4B2W.js → chunk-7MIN5RH6.js} +2 -2
  60. package/dist/rpiv-todo/{chunk-V6PM4YRC.js → chunk-IRYKQOMH.js} +11 -7
  61. package/dist/rpiv-todo/index.js +34 -12
  62. package/dist/vendor/acorn.js +49 -19
  63. package/dist/vendor/model-probe/src/index.js +41 -2
  64. package/dist/vendor/pi-coding-agent.js +3 -6
  65. package/dist/vendor/pi-mcp-adapter-types.js +8 -1
  66. package/dist/vendor/pi-tui.js +346 -40
  67. package/dist/vendor/pi-web-access.js +1569 -768
  68. package/dist/vendor/smol-toml.js +1199 -0
  69. package/dist/vendor/zod.js +51 -2
  70. package/package.json +38 -82
  71. package/reserved-names.json +4 -1
package/README.md CHANGED
@@ -17,8 +17,8 @@ explyt update # install the newer latest, then restart open sessi
17
17
  For a one-off pinned run:
18
18
 
19
19
  ```bash
20
- npx -y "@explyt/ai-agent@0.5.1" # start the terminal UI
21
- npx -y "@explyt/ai-agent@0.5.1" login # store a provider credential, once
20
+ npx -y "@explyt/ai-agent@0.6.0" # start the terminal UI
21
+ npx -y "@explyt/ai-agent@0.6.0" login # store a provider credential, once
22
22
  ```
23
23
 
24
24
  The agent runs with exactly the extensions this build ships with and ignores any
@@ -28,4 +28,4 @@ you get.
28
28
  IDE (ACP) integration is not part of this package: it is provided by the Explyt
29
29
  managed backend, which the Neo plugin downloads and manages.
30
30
 
31
- Run `npx -y @explyt/ai-agent@0.5.1 --help` for the available options.
31
+ Run `npx -y @explyt/ai-agent@0.6.0 --help` for the available options.
@@ -114,7 +114,7 @@ License or other written license agreements with the Company.
114
114
  re-exports the engine's own bundled entry point by name; it contains no engine code.
115
115
  - The formerly bundled `pi-subagents` package was removed by spec 008; references to it in
116
116
  older release history are historical and do not describe the current artifact.
117
- - Seven units of `@earendil-works/pi-coding-agent` 1.1.0 are **copied** (from the TypeScript in
117
+ - Seven units of `@earendil-works/pi-coding-agent` 1.4.0 are **copied** (from the TypeScript in
118
118
  the shipped sourcemaps' `sourcesContent`) into `extensions/bash/engine/` under spec 006
119
119
  (RQ-37) — `killProcessTree` into `packages/shared/src/process/`, where spec 008's children
120
120
  share it; the whitespace-normalized originals sit next to each copy as `*.upstream.txt`, and every
@@ -150,14 +150,14 @@ License or other written license agreements with the Company.
150
150
 
151
151
  ### 5. model-probe, @opencode-ai/models, yaml, acorn, minimatch, semver, typebox and yauzl
152
152
 
153
- - `model-probe` 0.6.0, MIT, https://www.npmjs.com/package/model-probe
153
+ - `model-probe` 0.7.0, MIT, https://www.npmjs.com/package/model-probe
154
154
  - Copyright (c) 2025 ratatulieoi
155
155
  - Copyright (c) 2026 real-wudaoshi
156
156
  - `@opencode-ai/models` 0.0.53, MIT, https://www.npmjs.com/package/@opencode-ai/models
157
157
  - Copyright (c) 2025 models.dev
158
158
  - `yaml` 2.9.0, ISC, https://www.npmjs.com/package/yaml
159
159
  - Copyright Eemeli Aro <eemeli@gmail.com>
160
- - `acorn` 8.18.0, MIT, https://www.npmjs.com/package/acorn
160
+ - `acorn` 8.19.0, MIT, https://www.npmjs.com/package/acorn
161
161
  - Copyright (C) 2012-2022 by various contributors (see AUTHORS)
162
162
  - `minimatch` 10.2.6, Blue Oak Model License 1.0.0, https://www.npmjs.com/package/minimatch
163
163
  - Copyright Isaac Z. Schlueter <i@izs.me> and minimatch contributors
@@ -205,7 +205,7 @@ THIS SOFTWARE.
205
205
  ### 6. rpiv-ask-user-question
206
206
 
207
207
  **Original Work:**
208
- - Name: `@juicesharp/rpiv-ask-user-question` (version 2.11.0)
208
+ - Name: `@juicesharp/rpiv-ask-user-question` (version 2.13.10)
209
209
  - Available at: https://www.npmjs.com/package/@juicesharp/rpiv-ask-user-question
210
210
  (source: https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-ask-user-question)
211
211
  - Licensed under the MIT License
@@ -258,7 +258,7 @@ the Apache License 2.0 text applies to the Codex logic with the NOTICE above; th
258
258
  ### 8. rpiv-todo
259
259
 
260
260
  **Original Work:**
261
- - Name: `@juicesharp/rpiv-todo` (version 2.11.0)
261
+ - Name: `@juicesharp/rpiv-todo` (version 2.13.9)
262
262
  - Available at: https://www.npmjs.com/package/@juicesharp/rpiv-todo
263
263
  (source: https://github.com/juicesharp/rpiv-mono/tree/main/packages/rpiv-todo)
264
264
  - Licensed under the MIT License
@@ -651,29 +651,30 @@ Consult each package for its complete license text.
651
651
  - @modelcontextprotocol/sdk@1.32.1: license metadata = MIT (installed by npm beside this package)
652
652
  - @mozilla/readability@0.6.0: license metadata = Apache-2.0 (installed by npm beside this package)
653
653
  - @napi-rs/keyring@2.1.0: license metadata = MIT (installed by npm beside this package)
654
- - acorn@8.18.0: license metadata = MIT (installed by npm beside this package)
654
+ - acorn@8.19.0: license metadata = MIT (installed by npm beside this package)
655
655
  - defuddle@0.19.3: license metadata = MIT (installed by npm beside this package)
656
656
  - linkedom@0.16.11: license metadata = ISC (installed by npm beside this package)
657
657
  - marked@18.0.11: license metadata = MIT (installed by npm beside this package)
658
658
  - minimatch@10.2.6: license metadata = BlueOak-1.0.0 (installed by npm beside this package)
659
- - model-probe@0.6.0: license metadata = MIT (installed by npm beside this package)
659
+ - model-probe@0.7.0: license metadata = MIT (installed by npm beside this package)
660
660
  - open@10.2.0: license metadata = MIT (installed by npm beside this package)
661
661
  - p-limit@6.2.0: license metadata = MIT (installed by npm beside this package)
662
- - pi-mcp-adapter@5.2.0: license metadata = MIT (installed by npm beside this package)
663
- - pi-web-access@0.39.0: license metadata = MIT (installed by npm beside this package)
662
+ - pi-mcp-adapter@5.4.0: license metadata = MIT (installed by npm beside this package)
663
+ - pi-web-access@0.44.0: license metadata = MIT (installed by npm beside this package)
664
664
  - promise.try@2.0.2: license metadata = MIT (installed by npm beside this package)
665
665
  - quickjs-wasi@3.6.2: license metadata = MIT (installed by npm beside this package)
666
666
  - recheck@4.6.0-beta.3: license metadata = MIT (installed by npm beside this package)
667
667
  - semver@7.8.5: license metadata = ISC (installed by npm beside this package)
668
+ - smol-toml@1.9.1: license metadata = BSD-3-Clause (installed by npm beside this package)
668
669
  - turndown@7.2.4: license metadata = MIT (installed by npm beside this package)
669
- - unbash@5.0.0: license metadata = ISC (installed by npm beside this package)
670
- - undici@8.11.2: license metadata = MIT (installed by npm beside this package)
670
+ - unbash@6.0.1: license metadata = ISC (installed by npm beside this package)
671
+ - undici@8.12.3: license metadata = MIT (installed by npm beside this package)
671
672
  - unpdf@1.8.1: license metadata = MIT (installed by npm beside this package)
672
673
  - yaml@2.9.0: license metadata = ISC (installed by npm beside this package)
673
674
  - yauzl@3.4.0: license metadata = MIT (installed by npm beside this package)
674
675
  - typebox@1.3.27: license metadata = MIT (compiled into dist/vendor/typebox)
675
- - model-probe@0.6.0: license metadata = MIT (compiled into dist/vendor/model-probe)
676
- - pi-web-access@0.39.0: license metadata = MIT (compiled into dist/vendor/pi-web-access.js)
676
+ - model-probe@0.7.0: license metadata = MIT (compiled into dist/vendor/model-probe)
677
+ - pi-web-access@0.44.0: license metadata = MIT (compiled into dist/vendor/pi-web-access.js)
677
678
 
678
679
  ## Packages compiled into this package's own files
679
680
 
@@ -681,9 +682,9 @@ Generated at build time from the packages each compiled, unobfuscated file inlin
681
682
  directories do not ship, so their copyright notices are reproduced here; the full text of
682
683
  each licence named is under "Full License Texts" above.
683
684
 
684
- - @earendil-works/pi-tui@1.1.0, MIT, compiled into dist/vendor/pi-tui.js
685
+ - @earendil-works/pi-tui@1.4.0, MIT, compiled into dist/vendor/pi-tui.js
685
686
  - Copyright (c) 2025 Mario Zechner
686
- - notice recorded from https://github.com/earendil-works/pi/blob/v1.1.0/LICENSE (the package ships none)
687
+ - notice recorded from https://github.com/earendil-works/pi/blob/v1.4.0/LICENSE (the package ships none)
687
688
  - @modelcontextprotocol/client@2.3.1, Apache-2.0, compiled into dist/mcp-adapter.js
688
689
  - Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
689
690
  - @modelcontextprotocol/core@2.3.1, Apache-2.0, compiled into dist/mcp-adapter.js
@@ -692,7 +693,7 @@ each licence named is under "Full License Texts" above.
692
693
  - Copyright 2025 The Model Context Protocol Authors
693
694
  - @typesafe-ai/sdk@0.6.0, MIT, compiled into dist/mcp-adapter.js
694
695
  - Copyright (c) 2026 TypeSafe
695
- - acorn@8.18.0, MIT, compiled into dist/vendor/acorn.js
696
+ - acorn@8.19.0, MIT, compiled into dist/vendor/acorn.js
696
697
  - Copyright (C) 2012-2022 by various contributors (see AUTHORS)
697
698
  - ajv-formats@3.0.1, MIT, compiled into dist/mcp-adapter.js
698
699
  - Copyright (c) 2020 Evgeny Poberezkin
@@ -712,7 +713,7 @@ each licence named is under "Full License Texts" above.
712
713
  - Copyright (c) EventSource GitHub organisation
713
714
  - fast-deep-equal@3.1.3, MIT, compiled into dist/mcp-adapter.js
714
715
  - Copyright (c) 2017 Evgeny Poberezkin
715
- - fast-uri@3.1.7, BSD-3-Clause, compiled into dist/mcp-adapter.js
716
+ - fast-uri@3.1.9, BSD-3-Clause, compiled into dist/mcp-adapter.js
716
717
  - Copyright (c) 2011-2021, Gary Court until https://github.com/garycourt/uri-js/commit/a1acf730b4bba3f1097c9f52e7d9d3aba8cdcaae
717
718
  - Copyright (c) 2021-present The Fastify team <https://github.com/fastify/fastify#team>
718
719
  - get-east-asian-width@1.6.0, MIT, compiled into dist/vendor/pi-tui.js
@@ -723,6 +724,8 @@ each licence named is under "Full License Texts" above.
723
724
  - Copyright (c) 2018 Filip Skokan
724
725
  - json-schema-traverse@1.0.0, MIT, compiled into dist/mcp-adapter.js
725
726
  - Copyright (c) 2017 Evgeny Poberezkin
727
+ - marked-cjk-friendly@0.1.2, MIT, compiled into dist/vendor/pi-tui.js
728
+ - Copyright (c) 2024 Tatsunori Uchino, and authors and contributors of original packages
726
729
  - marked@18.0.11, MIT, compiled into dist/vendor/pi-tui.js
727
730
  - Copyright (c) 2018+, MarkedJS (https://github.com/markedjs/)
728
731
  - Copyright (c) 2011-2018, Christopher Jeffrey (https://github.com/chjj/)
@@ -734,7 +737,7 @@ each licence named is under "Full License Texts" above.
734
737
  - Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
735
738
  - pend@1.2.0, MIT, compiled into dist/vendor/yauzl.js
736
739
  - Copyright (c) 2014 Andrew Kelley
737
- - pi-mcp-adapter@5.2.0, MIT, compiled into dist/mcp-adapter.js, dist/vendor/pi-mcp-adapter-types.js
740
+ - pi-mcp-adapter@5.4.0, MIT, compiled into dist/mcp-adapter.js, dist/vendor/pi-mcp-adapter-types.js
738
741
  - Copyright (c) 2026 Nico Bailon
739
742
  - pkce-challenge@5.0.1, MIT, compiled into dist/mcp-adapter.js
740
743
  - Copyright (c) 2019
@@ -744,11 +747,11 @@ each licence named is under "Full License Texts" above.
744
747
  - Copyright (c) Kevin Mårtensson <kevinmartensson@gmail.com> (github.com/kevva)
745
748
  - shebang-regex@3.0.0, MIT, compiled into dist/mcp-adapter.js
746
749
  - Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (sindresorhus.com)
747
- - smol-toml@1.9.1, BSD-3-Clause, compiled into dist/mcp-adapter.js
750
+ - smol-toml@1.9.1, BSD-3-Clause, compiled into dist/vendor/smol-toml.js
748
751
  - Copyright (c) Squirrel Chat et al., All rights reserved.
749
752
  - strip-json-comments@5.0.3, MIT, compiled into dist/mcp-adapter.js
750
753
  - Copyright (c) Sindre Sorhus <sindresorhus@gmail.com> (https://sindresorhus.com)
751
- - undici@6.29.0, MIT, compiled into dist/mcp-adapter.js
754
+ - undici@6.29.1, MIT, compiled into dist/mcp-adapter.js
752
755
  - Copyright (c) Matteo Collina and Undici contributors
753
756
  - which@2.0.2, ISC, compiled into dist/mcp-adapter.js
754
757
  - Copyright (c) Isaac Z. Schlueter and Contributors
@@ -756,5 +759,5 @@ each licence named is under "Full License Texts" above.
756
759
  - Copyright Eemeli Aro <eemeli@gmail.com>
757
760
  - yauzl@3.4.0, MIT, compiled into dist/vendor/yauzl.js
758
761
  - Copyright (c) 2014 Josh Wolfe
759
- - zod@4.6.5, MIT, compiled into dist/vendor/zod.js
762
+ - zod@4.6.7, MIT, compiled into dist/vendor/zod.js
760
763
  - Copyright (c) 2025 Colin McDonnell
@@ -21,14 +21,38 @@ strong profile for a large one. `fork` never takes an agent or a profile.
21
21
  Only `*.md` files directly inside a root are read; subdirectories are not searched. The project
22
22
  root is the session's working directory, with no search up the directory tree. Agent files of
23
23
  other tools, such as `.claude/agents/`, are **not** read: their tool names would not work here.
24
- A root that is a symbolic link, or is reached through a linked directory, is ignored, and so is a
25
- linked file inside a root: point a root at real files only.
24
+ A root that is a symbolic link or Windows junction, or is reached through one, is read as its
25
+ target, and so is a linked `*.md` file inside a root. With `skills.followSymlinks: false` in either
26
+ settings layer (`settings.md`), each of them is ignored instead.
26
27
 
27
28
  A launch reads the files again, so a file written earlier in the same answer can be launched at
28
29
  once. The list of agents and profiles the model sees in its system prompt is rebuilt on the next
29
30
  user message that starts a new answer; a message sent while the model is still answering keeps the
30
31
  list that answer started with.
31
32
 
33
+ ## Plugin agents
34
+
35
+ The Marketplace plugins the project enables add their own agents: each `*.md` file directly inside
36
+ `agents/` of the enabled plugin version (see `plugins.md`); files in subdirectories are not read. A
37
+ plugin agent is part of the plugin — do not edit or copy it. It follows the agent file format below,
38
+ with these differences:
39
+
40
+ - **A plugin agent never replaces another agent.** A `name` it shares with any other agent — a user
41
+ agent, a built-in or an agent of another plugin — makes **every** claimant unavailable, the
42
+ built-in included, and the clash is reported with every claiming path. Rename your own file, or
43
+ disable the plugin, to resolve it.
44
+ - `profile` and `emoji` have no effect: a plugin agent runs on the call's `model_profile`, or else
45
+ on the parent's model, and shows no icon.
46
+ - A plugin agent whose `tools` use another product's tool names fails at the launch.
47
+ - The body is used exactly as written: `${PLUGIN_ROOT}`, `${PLUGIN_DATA}` and `{{var:<id>}}` are
48
+ not substituted and reach the helper as plain text.
49
+ - `subagents.disabledAgents` never disables a plugin agent: an entry naming it is kept and ignored.
50
+ Disabling the plugin removes all of its agents. In `/agents` its row has the source `plugin` and
51
+ cannot be switched.
52
+
53
+ Plugin agents change only when a session starts (or after `/reload` in the terminal UI), unlike
54
+ your own agent files, which a launch reads again.
55
+
32
56
  ## Built-in agents
33
57
 
34
58
  Three agents ship with the product:
@@ -45,7 +69,7 @@ everywhere, even when that file is invalid but its frontmatter `name` can be rea
45
69
  override makes the name unavailable instead of falling back to the built-in. A file whose
46
70
  frontmatter cannot be read at all (or that is over 64 KB) claims no name, so the built-in keeps
47
71
  running beside its invalid row — fix the frontmatter. Two user files with that name make the name
48
- unavailable, built-in included. No
72
+ unavailable, built-in included; so does a plugin agent with that name (see "Plugin agents"). No
49
73
  built-in model profile exists: write one for each model you want to offer.
50
74
 
51
75
  ## Agent file
@@ -69,7 +93,7 @@ You review the change against the task. Report defects with file and line. Do no
69
93
  | `description` | yes | non-blank string of at most 1024 characters; what the parent reads to choose the agent |
70
94
  | `profile` | no | a **profile name**; the agent always runs on that profile |
71
95
  | `emoji` | no | exactly one emoji, shown on the helper's panel row and history header — before the profile's emoji when both are set; anything else is ignored with a warning |
72
- | `tools` | no | array of tool names; the helper gets exactly these, plus its two report tools, plus `use_skill` when `skills` is set |
96
+ | `tools` | no | array of tool names; the helper gets exactly these, plus its two report tools, plus `use_skill` when `skills` is set; `list_agents` and `send_message` count as listed tools, so a helper without them in `tools` cannot message its parent or siblings |
73
97
  | `skills` | no | array of Skill names; the helper sees and can apply only these |
74
98
 
75
99
  The `name` in the frontmatter is the identity; the file name may differ.
@@ -80,7 +104,8 @@ The `name` in the frontmatter is the identity; the file name may differ.
80
104
  helper cannot start helpers. Tools a helper never has are refused too: `list_models`, `todo`
81
105
  (a helper reports progress with `report_progress` instead), and `ask_user_question` when the
82
106
  session does not offer it to helpers. Without `tools`, the helper
83
- gets the default helper tools.
107
+ gets the default helper tools, which include `list_agents` and `send_message`: a helper can
108
+ message its parent and its sibling helpers, never another session.
84
109
  - **`tools` and Skills.** With `tools` and `skills`, the helper also gets `use_skill`, so it can
85
110
  apply the listed Skills. With `tools` but no `skills`, the helper sees no Skills at all unless
86
111
  `tools` names `use_skill` — the built-ins `hawkeye` and `retriever` work this way.
@@ -198,7 +223,7 @@ Disabling never edits an agent or profile file.
198
223
  ## The `/agents` screen
199
224
 
200
225
  In the terminal UI, `/agents` lists every agent with its state, source (`builtin`, `global`,
201
- `project`), the model a launch without `model_profile` would run on (`parent` for the parent's
226
+ `project`, `plugin`), the model a launch without `model_profile` would run on (`parent` for the parent's
202
227
  model) and its description:
203
228
 
204
229
  - `on` — available and launchable.
@@ -207,6 +232,8 @@ model) and its description:
207
232
  reads `duplicate name` and lists every claiming path on its own line below the row.
208
233
  - `not supported` — enabled, but a launch would fail; the row names the failing field.
209
234
 
235
+ A `plugin` row cannot be switched: disable the plugin instead.
236
+
210
237
  A disabled built-in stays a row, so it can be switched back on; the screen shows its empty state,
211
238
  naming the two agent roots, only when there is no row at all.
212
239
 
package/agent-docs/ci.md CHANGED
@@ -55,7 +55,7 @@ environment variable (`"$NAME"` is read from the environment):
55
55
  {
56
56
  "providers": {
57
57
  "ci-account": {
58
- "baseUrl": "https://plugin.explyt.ai/openai/api/v1",
58
+ "baseUrl": "https://plugin.staging.explyt.ai/openai/api/v1",
59
59
  "api": "openai-completions",
60
60
  "apiKey": "$CI_ACCOUNT_KEY",
61
61
  "models": [{ "id": "<model id from your account>" }]
@@ -64,7 +64,7 @@ environment variable (`"$NAME"` is read from the environment):
64
64
  }
65
65
  ```
66
66
 
67
- `https://plugin.explyt.ai/openai/api/v1` is the model address of the account this build logs in to. Then run with
67
+ `https://plugin.staging.explyt.ai/openai/api/v1` is the model address of the account this build logs in to. Then run with
68
68
  `--model ci-account/<model id>` and set `CI_ACCOUNT_KEY` from a secret.
69
69
 
70
70
  **Your own provider.** Any server that speaks an API the agent supports (a company proxy, vLLM, LM
@@ -200,6 +200,7 @@ and stops on its own.
200
200
  |---|---|
201
201
  | print mode, the answer succeeds | 0 |
202
202
  | print mode, the answer ends with an error or an abort | 1 |
203
+ | print mode, the answer is cut off at the model's output token limit | 1; the partial answer is on stdout and a warning on stderr |
203
204
  | JSON mode, any model outcome | 0, the outcome is in the events |
204
205
  | no prompt | 1 |
205
206
  | no key found, or the engine cannot start | non-zero |
package/agent-docs/mcp.md CHANGED
@@ -11,8 +11,28 @@ An MCP server gives the agent extra tools, resources and prompts. Servers are de
11
11
  | session | the `mcpServers` field of the IDE's session request | the IDE |
12
12
  | plugin | the Marketplace plugins `<project>/.explyt/plugins.json` enables (dogfood builds only) | the plugin author |
13
13
 
14
- These four logical sources and nothing else. Other tools' MCP files are **not** read — not
15
- `~/.config/mcp/mcp.json`, `~/.agents/mcp.json` or `<project>/.mcp.json`.
14
+ Other agents' MCP files are read only when that agent is enabled for the corresponding home or
15
+ project location through `otherAgents.*` (`settings.md`). They are translated in place and never
16
+ written by this product. Ambient `~/.config/mcp/mcp.json` and `~/.agents/mcp.json` are not read.
17
+
18
+ | Agent | Home (global) | Project |
19
+ |---|---|---|
20
+ | Claude Code | `~/.claude.json`: top-level `mcpServers`, then this project's `projects[path].mcpServers` | `<project>/.mcp.json` |
21
+ | Cursor | `~/.cursor/mcp.json` | `<project>/.cursor/mcp.json` |
22
+ | Codex | `$CODEX_HOME/config.toml`, or `~/.codex/config.toml` when `CODEX_HOME` is unset, empty or relative | `<project>/.codex/config.toml` |
23
+ | OpenCode | `~/.config/opencode/opencode.json` and `opencode.jsonc` | `<project>/opencode.json` and `opencode.jsonc` |
24
+
25
+ Claude's home file entries remain global even when defined inside `projects[path]`; overrides of
26
+ those project-bound definitions always use the project path. Claude off lists, and Codex/OpenCode
27
+ `enabled: false`, keep a server off unless our global overrides explicitly enable it. Codex
28
+ `disabled_tools` becomes the initial excluded-tool list. Cursor's internal database switches are
29
+ not read.
30
+
31
+ Foreign definitions use their agent's variable syntax, not ours. Explicit environment references
32
+ may use any variable name, including provider tokens; values come from the process environment,
33
+ not saved login credentials. Unsupported definitions do not
34
+ start; `/mcp` shows the reason. An unreadable or invalid file does not block other sources.
35
+ At each OpenCode location, JSONC overrides JSON: objects merge recursively and arrays are replaced.
16
36
 
17
37
  ### Legacy plugin compatibility
18
38
 
@@ -63,6 +83,8 @@ HTTP server uses `url` with optional `headers`.
63
83
  | `headers` | object of strings | headers sent with each request |
64
84
  | `disabled` | boolean | `true` keeps the definition but does not start the server |
65
85
  | `excludeTools` | array of strings | tools of this server the model must not see |
86
+ | `roots` | boolean | `false` stops sending this server the project folder as its root (see below); default on |
87
+ | `appendStructuredContent` | boolean | `false` stops adding a tool's `structuredContent` after a result that already has text content |
66
88
  | `auth` | `{ "provider": "<id>" }` | send the credential stored with `/login` for that model provider as a Bearer token; **not in a project file** |
67
89
 
68
90
  `auth` with a `provider` is honoured in `~/.explyt/mcp.json` and in the IDE's own session
@@ -79,6 +101,24 @@ An entry whose field has the wrong type is skipped with a warning, and the rest
79
101
  loads. A file that is not valid JSON, or whose top level is not an object, contributes no servers
80
102
  and is reported.
81
103
 
104
+ ## The project folder is sent to every server
105
+
106
+ Every server is told the project folder as its MCP root, as Claude Code and opencode do. A server
107
+ that must keep its own folders needs `"roots": false`. The official filesystem server is the
108
+ common case: it replaces the folders in its `args` with the roots it receives.
109
+
110
+ ```json
111
+ { "mcpServers": { "notes": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/home/me/notes"], "roots": false } } }
112
+ ```
113
+
114
+ ## Server log
115
+
116
+ What a server sends as a log message is appended to `mcp.log` in the agent directory
117
+ (`$XDG_DATA_HOME/explyt-ai-agent/agent/mcp.log`, default `~/.local/share/explyt-ai-agent/agent/mcp.log`),
118
+ one line per message with the time and the server name. Past 5 MB the file moves to `mcp.log.1` and
119
+ a new one starts. The text is whatever the server chose to log, so it may hold data the server
120
+ handles; look there when a server does not start or misbehaves, and treat the file as private.
121
+
82
122
  ## Environment variables
83
123
 
84
124
  A string anywhere in an entry may reference a variable in three spellings: `${NAME}`, `$env:NAME`
@@ -90,12 +130,19 @@ and the literal text is passed through unchanged.
90
130
 
91
131
  ## The same name in two files
92
132
 
93
- A project entry **replaces** the global entry of the same name, as a whole. It does not inherit
94
- single fields from it: to change one field for one project, repeat the whole entry.
133
+ A project entry precedes the global entry of the same name, as a whole. It does not inherit
134
+ single fields from it: to change one field for one project, repeat the whole entry. An off project
135
+ server is passed over, so the global server can take its place. Within one scope, native still
136
+ replaces the legacy representation, even when disabled.
95
137
 
96
- A name that collides between the merged files and the servers the IDE supplied is a different
97
- matter — that makes the configuration invalid, and it is reported rather than resolved by
98
- preferring a source or renaming a server. Rename one of them.
138
+ Same-name servers are tried in this order: IDE, our project/global files, Claude Code, Cursor,
139
+ Codex, OpenCode, then plugins. Disabled or unsupported candidates are skipped; the first usable
140
+ candidate wins. Definitions are not merged across sources; later candidates show as `shadowed`.
141
+ Within another agent, project precedes home, except Claude: home `projects[path]`, project
142
+ `.mcp.json`, then home top-level entries.
143
+
144
+ An IDE server wins over project and foreign sources. A collision with an effective own global
145
+ server refuses the session; an active own project definition of that name shadows the global one.
99
146
 
100
147
  A plugin server never replaces another server. When its name is already taken by a global,
101
148
  project or session server, or by a server of another enabled plugin, it is left out of the session
@@ -124,6 +171,111 @@ An entry matches the bare tool name (`delete_page`) or its prefixed form (`docs_
124
171
  `*` and `?` are glob wildcards. By default a server's tools reach the model prefixed with the server
125
172
  name, which is why both spellings match.
126
173
 
174
+ ## Overriding another agent's switches
175
+
176
+ Edit `otherAgents.mcpOverrides` in our `settings.json`, not the other agent's files.
177
+ Keys are `<agent>:<server>`; values accept only `disabled` (boolean) and `excludeTools` (array of
178
+ strings). Commands, URLs, environment and headers cannot be changed here.
179
+
180
+ A global override can enable or disable a server and replace its excluded-tool list.
181
+ A project override can only disable a server or add exclusions. An unpathed global override
182
+ cannot lift a project server's own restrictions.
183
+
184
+ To enable a server or tool for one project, use a global key
185
+ `<agent>:<server>@<absolute project path>`. It replaces the **whole** unpathed global override in
186
+ that project, so repeat any exclusions to retain. Paths match through symlinks and filesystem
187
+ case aliases. If a matching path key already exists, edit it rather than the plain key.
188
+
189
+ Claude home `projects[path]` definitions remain global but are project-bound: use a global path
190
+ key for their overrides. Claude's project-specific off lists also require a global path key
191
+ to lift their restriction.
192
+
193
+ For example, in the global `settings.json`:
194
+
195
+ ```json
196
+ {
197
+ "otherAgents": {
198
+ "mcpOverrides": {
199
+ "codex:docs": { "disabled": true },
200
+ "codex:docs@/work/app": { "disabled": false, "excludeTools": ["delete_page"] }
201
+ }
202
+ }
203
+ }
204
+ ```
205
+
206
+ Here `docs` is off by default and enabled only in `/work/app`, where `delete_page` stays excluded.
207
+ A project-layer `disabled: true` can still turn it off there.
208
+
209
+ `/mcp` stores foreign-server switches in these overrides, leaving source files unchanged.
210
+ Missing-server overrides are ignored and kept. An override cannot enable reading a source:
211
+ first enable that agent for the required location in `otherAgents.*`.
212
+
213
+ ## Approving project servers
214
+
215
+ A project server is one defined in `<project>/.explyt/mcp.json`, `<project>/.explyt/mcp_servers.json`
216
+ or another agent's project file (the "Project" column above). Global files, Claude's `~/.claude.json`
217
+ (also its `projects[path]` entries), plugin servers and IDE servers are not project servers and are
218
+ never asked about. When the project is the home directory, no server is a project server.
219
+
220
+ ### The policy: `mcp.projectServers`
221
+
222
+ The global setting decides what happens to a project server **without an answer**:
223
+
224
+ ```json
225
+ { "mcp": { "projectServers": "ask" } }
226
+ ```
227
+
228
+ | Value | Without an answer |
229
+ |---|---|
230
+ | `ask` (default) | the person is asked; the server does not start until it is approved |
231
+ | `allow` | the server starts without a question |
232
+ | `deny` | the server does not start and nobody is asked; `/mcp` shows it `not allowed` |
233
+
234
+ It is read from the global `settings.json` only; in a project `settings.json` it is ignored with a
235
+ warning, and an unaccepted value counts as `ask`. The policy covers every project; an answer covers
236
+ one server in one project. A recorded answer wins under every policy. A change of the policy
237
+ applies at the next session start or `/reload`.
238
+
239
+ Under `ask`, a terminal window or IDE form follows the import question (`settings.md`). It asks
240
+ about project servers that would otherwise run, only the first unanswered candidate of each name.
241
+ Saving allows checked servers and denies unchecked ones for this project; dismissal records nothing.
242
+
243
+ No question is shown in `bypassPermissions`, `afk`, print/JSON runs, child sessions, or IDE clients
244
+ without form support. Unanswered project servers stay off. Denied, dismissed or unreachable
245
+ candidates permit the next eligible same-name server to run; another unanswered project candidate
246
+ waits for a later check point.
247
+
248
+ ### Where answers are stored
249
+
250
+ Answers live outside every project, in `mcp/project-server-approvals.json` under the product data
251
+ directory (`$XDG_DATA_HOME/explyt-ai-agent`, default `~/.local/share/explyt-ai-agent`), readable by its owner
252
+ only:
253
+
254
+ ```json
255
+ { "/home/me/work/app": { "own:fs": "deny", "claude:github": "allow" } }
256
+ ```
257
+
258
+ The outer key is the project's canonical path (real path, `/` separators, lower case on a
259
+ case-insensitive file system), so each Git worktree is a separate project. The inner key is
260
+ `<source>:<server name>`, where the source is `own` for our own files or the agent id. A value is
261
+ `allow` or `deny`.
262
+
263
+ An unreadable or malformed store keeps all project servers off, even under policy `allow`, and
264
+ blocks approval questions and writes; other servers still work. Correct it only on the user's
265
+ request, preserving unrelated entries. Do not delete or replace a damaged document to hide the
266
+ error. Apply the repair in a new session or `/reload`.
267
+
268
+ ### Changing an answer
269
+
270
+ - In the terminal, `/mcp` stages allow (`a`) or deny (`d`) for project servers and saves on close.
271
+ - On the user's request, edit the store: set `allow`/`deny`, or delete the server's entry to ask
272
+ again under `ask`. Preserve other servers and projects. Hand edits apply in a new session or
273
+ `/reload`.
274
+
275
+ An approval saved through the question or `/mcp` starts the server immediately only if its name
276
+ is not already running. Answers never stop or replace a running server: denial or a newly approved
277
+ higher-priority definition takes effect in a new session or `/reload`.
278
+
127
279
  ## When a change takes effect
128
280
 
129
281
  The configuration is resolved once, before the session's MCP runtime starts. Editing a file does
@@ -137,8 +289,11 @@ which is not an error.
137
289
  ## The `/mcp` screen
138
290
 
139
291
  In the terminal UI, `/mcp` lists the servers, their status and their tools, and can toggle a server
140
- or an individual tool — writing the same `disabled` and `excludeTools` fields described above. That
141
- command does not exist in an IDE session; there, edit the files.
292
+ or an individual tool — writing the same `disabled` and `excludeTools` fields described above, or,
293
+ for another agent's server, `otherAgents.mcpOverrides`. Its `a` and `d` keys change approvals
294
+ ("Approving project servers" above). A project server waiting for an answer is listed
295
+ `awaiting approval`, a denied one `not allowed`. That command does not exist in an IDE session;
296
+ there, edit the files and the approval store.
142
297
 
143
298
  A plugin server is listed with the source `plugin` and cannot be toggled there: it is switched by
144
299
  enabling or disabling its plugin. A plugin server that could not be resolved is not listed at all;
@@ -0,0 +1,66 @@
1
+ # Marketplace plugins
2
+
3
+ ## Project activation
4
+
5
+ Plugins are enabled per project in `.explyt/plugins.json`. Commit the exact plugin version and each MCP server's zero-based `runModes` index; do not put credentials or filesystem paths in this file. An entry without a `version` is reported and ignored, and `enable`, `disable` and `config set-run-mode` drop it when they rewrite the file.
6
+
7
+ Example:
8
+
9
+ ```json
10
+ {
11
+ "schemaVersion": 1,
12
+ "plugins": {
13
+ "security-pack": {
14
+ "version": "1.3.1",
15
+ "runModes": { "Github MCP": 1 }
16
+ }
17
+ }
18
+ }
19
+ ```
20
+
21
+ An enabled plugin version adds its rules, its Skills (`skills.md`), its agents (`agents.md`, section
22
+ "Plugin agents") and its MCP servers to the project's sessions. A plugin's components are switched
23
+ off only by disabling the plugin.
24
+
25
+ ## Plugin commands
26
+
27
+ Plugins are managed from a shell in the project directory with `explyt plugin <operation>`. Without a global install, run `npx -y @explyt/ai-agent@<version> plugin <operation>` with the same version as the running agent (`explyt --version`, or the version it was started with). The current directory is the project. The command prints results on stdout and errors on stderr, and exits `0` on success, `1` when an operation fails, and `2` on an argument or usage error: an unknown operation or flag, a missing or extra argument, or an invalid plugin ID, version or run-mode index. Each error names its typed kind, such as `PluginVersionNotInstalled`.
28
+
29
+ The operations are `install`, `uninstall`, `update`, `enable`, `disable`, `list`, `details`, `verify`, `config set`, and `config set-run-mode`; `explyt plugin help` lists their arguments, shows both values-file shapes and an `enable` example. Plugin activation requires an installed exact version. When enabling a plugin is not a no-op, provide an explicit run-mode choice for every declared MCP server, one `--run-mode <server-name> <index>` each, for example `explyt plugin enable security-pack@1.3.1 --run-mode "Github MCP" 1 --run-mode Local 0`; an existing selection for the same exact version in the current project may be reused. `verify` takes no argument and reports every issue of the plugins the current project enables: a missing or damaged version, an incompatible `minPluginVersion`, and a required value that is not set. The issues are its result: it prints them on stdout and exits `0`, and fails only when the project manifest cannot be read or is invalid.
30
+
31
+ Before writing a values file or choosing run modes, run `explyt plugin details <plugin-id>@<version> --project` for the installed version. It lists each declared variable with its type, whether it is required, its default and choices, and whether a global or project value is stored (never the value itself), and each MCP server with its run-mode variants by index and the index this project selects. Without a version, or for a version that is not installed, `details` lists no declarations.
32
+
33
+ No command changes a running session. Changes take effect in a new session, or in a running terminal session after `/reload`. A command run through a tool cannot reload the session it was run from.
34
+
35
+ ## Values and credentials
36
+
37
+ Credentials and other plugin values stay in the local plugin store, not in the project manifest. Values are first supplied at install time with a JSON object mapping each declared variable ID to a string; a required value that is neither supplied, already stored, nor defaulted fails the install:
38
+
39
+ ```text
40
+ explyt plugin install <plugin-id>[@<version>] --values-file <values-file>
41
+ ```
42
+
43
+ ```json
44
+ { "github_pat": "ghp_...", "mode": "http" }
45
+ ```
46
+
47
+ Later changes go through `config set`:
48
+
49
+ ```text
50
+ explyt plugin config set <plugin-id>@<version> <values-file>
51
+ explyt plugin config set <plugin-id>@<version> --project <values-file>
52
+ ```
53
+
54
+ The first command patches global values; the second patches values for the current project. A project value overrides the global value for that project. The values file for `config set` contains a `values` object and may contain an `unset` array; omitted keys are preserved, and an ID may not be in both:
55
+
56
+ ```json
57
+ { "values": { "mode": "mcp" }, "unset": ["api_key"] }
58
+ ```
59
+
60
+ A `secret`, `path` or free-form `string` value may be an `${env:NAME}` or `${env:NAME:-fallback}` reference instead of the value itself, which keeps a secret out of the store; it is read from the agent's environment when a session starts.
61
+
62
+ To remove an installed version, use `explyt plugin uninstall <plugin-id>[@<version>]`. Removing the last installed version also removes that plugin's stored values and per-version `${PLUGIN_DATA}` directories. To change one MCP server's selection for an enabled version, use:
63
+
64
+ ```text
65
+ explyt plugin config set-run-mode <plugin-id>@<version> <server-name> <index>
66
+ ```
@@ -9,34 +9,31 @@ does not repeat them in every conversation.
9
9
  |---|---|---|
10
10
  | `~/.explyt/rules/**/*.md` | `global:.explyt/rules/team.md` | frontmatter + Markdown |
11
11
  | `<project>/.explyt/rules/**/*.md` | `project:.explyt/rules/team.md` | frontmatter + Markdown |
12
- | `~/.claude/CLAUDE.md` | `user:.claude/CLAUDE.md` | plain Markdown |
13
12
  | `<project>/AGENTS.md` | `project:AGENTS.md` | plain Markdown |
14
- | `<project>/CLAUDE.md` | `project:CLAUDE.md` | plain Markdown |
15
- | `<project>/.claude/CLAUDE.md` | `project:.claude/CLAUDE.md` | plain Markdown |
16
- | `<project>/CLAUDE.local.md` | `project:CLAUDE.local.md` | plain Markdown |
17
13
 
18
- These seven are always read.
14
+ These three are always read.
19
15
 
20
16
  ### Rules of other agents
21
17
 
22
- These are read only when the user has enabled that agent in the global `otherAgents` settings
23
- (`settings.md`): a home location when the agent is in `otherAgents.enabled`, a project location
24
- when `otherAgents.projects` (for this project) or `otherAgents.projectDefault` says `allow` for it.
25
- The files are read in place and never written.
18
+ These require the user's opt-in for the agent and location (home or project); see `otherAgents`
19
+ in `settings.md`. Read the files in place; do not edit them to configure this product.
26
20
 
27
21
  | Agent | Path | Rule ID | Format |
28
22
  |---|---|---|---|
23
+ | `claude` | `~/.claude/CLAUDE.md` | `user:.claude/CLAUDE.md` | plain Markdown |
29
24
  | `claude` | `~/.claude/rules/**/*.md` | `user:.claude/rules/style.md` | Claude rule |
30
25
  | `codex` | `$CODEX_HOME/AGENTS.override.md`, else `$CODEX_HOME/AGENTS.md` (`$CODEX_HOME` when it is an absolute path, else `~/.codex`; a relative value is not used) | `user:CODEX_HOME/AGENTS.md` | plain Markdown |
31
26
  | `opencode` | `~/.config/opencode/AGENTS.md` | `user:.config/opencode/AGENTS.md` | plain Markdown |
27
+ | `claude` | `<project>/CLAUDE.md` | `project:CLAUDE.md` | plain Markdown |
28
+ | `claude` | `<project>/.claude/CLAUDE.md` | `project:.claude/CLAUDE.md` | plain Markdown |
29
+ | `claude` | `<project>/CLAUDE.local.md` | `project:CLAUDE.local.md` | plain Markdown |
32
30
  | `claude` | `<project>/.claude/rules/**/*.md` | `project:.claude/rules/api.md` | Claude rule |
33
31
  | `cursor` | `<project>/.cursorrules` | `project:.cursorrules` | plain Markdown |
34
32
  | `cursor` | `<project>/.cursor/rules/**/*.mdc` | `project:.cursor/rules/ts.mdc` | Cursor rule |
35
33
  | `codex` | `<project>/AGENTS.override.md` | `project:AGENTS.override.md` | plain Markdown |
36
34
 
37
- The Claude `CLAUDE.md` files in the first table stay read whatever these settings hold; an answer
38
- only adds the files of this table. When the project is the home directory, the project rows are
39
- not read.
35
+ Without an answer none of these files is read. When the project is the home directory, the
36
+ project rows are not read, and `~/.claude/CLAUDE.md` is read once, as a home file.
40
37
 
41
38
  - **Claude rule** — optional frontmatter of which only `paths` counts: a YAML list whose every
42
39
  element is one glob, or one string of globs separated by commas (`src/*.{ts,tsx}, test/**` is
@@ -54,8 +51,8 @@ not read.
54
51
  apply. A file whose frontmatter
55
52
  block is not closed is a broken rule: it does not apply and is reported.
56
53
 
57
- The order is: `~/.claude/CLAUDE.md`, then the home rows above, then `<project>/AGENTS.md` and the
58
- project `CLAUDE.md` files, then the project rows above, then the Explyt rules and plugin rules.
54
+ The order is: the home rows above, then `<project>/AGENTS.md`, then the project rows above, then
55
+ the Explyt rules and plugin rules.
59
56
 
60
57
  Besides these, only the rules of the Marketplace plugins the project enables (dogfood builds
61
58
  only). A `CLAUDE.md`