@explyt/ai-agent 0.5.0 → 0.5.1-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 (58) hide show
  1. package/README.md +3 -3
  2. package/THIRD-PARTY-NOTICES.md +10 -5
  3. package/agent-docs/README.md +4 -0
  4. package/agent-docs/ci.md +237 -0
  5. package/agent-docs/plugins.md +62 -0
  6. package/agent-docs/rules.md +43 -1
  7. package/agent-docs/settings.md +57 -11
  8. package/agent-docs/skills.md +6 -2
  9. package/agent-docs/telegram.md +7 -3
  10. package/agent-docs/updates.md +3 -1
  11. package/agent-docs/workflows.md +421 -0
  12. package/dist/cli/brand-profile.js +6 -6
  13. package/dist/cli/engine-signals.js +77 -0
  14. package/dist/cli/engine.js +416 -11
  15. package/dist/cli/index.js +185 -21
  16. package/dist/cli/install-net.js +147 -0
  17. package/dist/cli/install-node.js +10 -6
  18. package/dist/cli/install-npm.js +9 -1
  19. package/dist/cli/install-run.js +9 -4
  20. package/dist/cli/launch.js +4 -1
  21. package/dist/cli/plugin.js +1 -0
  22. package/dist/extensions/ask-user-question.js +1 -1
  23. package/dist/extensions/bash.js +1 -1
  24. package/dist/extensions/custom-provider.js +1 -1
  25. package/dist/extensions/explyt-account.js +1 -1
  26. package/dist/extensions/hello.js +1 -1
  27. package/dist/extensions/identity.js +1 -1
  28. package/dist/extensions/login-menu.js +1 -1
  29. package/dist/extensions/mcp.js +1 -1
  30. package/dist/extensions/misc-hacks.js +1 -1
  31. package/dist/extensions/notify.js +1 -1
  32. package/dist/extensions/plugins.js +1 -0
  33. package/dist/extensions/policy.js +1 -1
  34. package/dist/extensions/rules.js +1 -1
  35. package/dist/extensions/session-title.js +1 -1
  36. package/dist/extensions/skills.js +1 -1
  37. package/dist/extensions/subagents.js +55 -1
  38. package/dist/extensions/telegram.js +1 -1
  39. package/dist/extensions/telemetry.js +1 -1
  40. package/dist/extensions/todo.js +1 -1
  41. package/dist/extensions/tool-rows.js +1 -1
  42. package/dist/extensions/tui.js +1 -1
  43. package/dist/extensions/update-notice.js +1 -1
  44. package/dist/extensions/web-access.js +1 -1
  45. package/dist/extensions/write.js +1 -1
  46. package/dist/install/installer.js +126 -16
  47. package/dist/rpiv-ask-user-question/{chunk-NXE76BE4.js → chunk-27VC5VIA.js} +1 -1
  48. package/dist/rpiv-ask-user-question/{chunk-V6PM4YRC.js → chunk-3E6FYMMK.js} +6 -6
  49. package/dist/rpiv-ask-user-question/{chunk-CDNB7COL.js → chunk-R5GW6VHB.js} +1 -1
  50. package/dist/rpiv-ask-user-question/index.js +3 -3
  51. package/dist/rpiv-todo/{chunk-V6PM4YRC.js → chunk-3E6FYMMK.js} +6 -6
  52. package/dist/rpiv-todo/{chunk-7UKL4B2W.js → chunk-MENO7HZY.js} +1 -1
  53. package/dist/rpiv-todo/{chunk-RYUIY66D.js → chunk-V3SMMTR6.js} +1 -1
  54. package/dist/rpiv-todo/index.js +4 -4
  55. package/dist/skills/builtin/code-review-orchestrated/SKILL.md +3 -3
  56. package/dist/skills/builtin/debug-root-cause/SKILL.md +75 -0
  57. package/dist/vendor/acorn.js +5732 -0
  58. package/package.json +3 -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.0" # start the terminal UI
21
- npx -y "@explyt/ai-agent@0.5.0" login # store a provider credential, once
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
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.0 --help` for the available options.
31
+ Run `npx -y @explyt/ai-agent@0.5.1 --help` for the available options.
@@ -148,7 +148,7 @@ License or other written license agreements with the Company.
148
148
  - local Explyt extension with current `@earendil-works` imports
149
149
  - shell API-key execution removed; credential files use locked atomic writes and private permissions
150
150
 
151
- ### 5. model-probe, @opencode-ai/models, yaml, minimatch, semver, typebox and yauzl
151
+ ### 5. model-probe, @opencode-ai/models, yaml, acorn, minimatch, semver, typebox and yauzl
152
152
 
153
153
  - `model-probe` 0.6.0, MIT, https://www.npmjs.com/package/model-probe
154
154
  - Copyright (c) 2025 ratatulieoi
@@ -157,6 +157,8 @@ License or other written license agreements with the Company.
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
161
+ - Copyright (C) 2012-2022 by various contributors (see AUTHORS)
160
162
  - `minimatch` 10.2.6, Blue Oak Model License 1.0.0, https://www.npmjs.com/package/minimatch
161
163
  - Copyright Isaac Z. Schlueter <i@izs.me> and minimatch contributors
162
164
  - `semver` 7.8.5, ISC, https://www.npmjs.com/package/semver
@@ -169,16 +171,16 @@ License or other written license agreements with the Company.
169
171
  - `pend` 1.2.0 (dependency of `yauzl`), MIT, https://www.npmjs.com/package/pend
170
172
  - Copyright (c) 2014 Andrew Kelley
171
173
 
172
- `model-probe`, `typebox`, `yaml`, `minimatch`, `semver` and `yauzl` are also redistributed
174
+ `model-probe`, `typebox`, `yaml`, `acorn`, `minimatch`, `semver` and `yauzl` are also redistributed
173
175
  compiled, unobfuscated and unmodified: the public npm package contains `dist/vendor/model-probe/`
174
176
  (the installed `model-probe` compiled from its TypeScript, with its `rules.json`),
175
177
  `dist/vendor/typebox/` (the pinned `typebox` in one ESM build) and `dist/vendor/yaml.js`,
176
- `minimatch.js`, `semver.js` and `yauzl.js` (each installed package with its own dependencies in
177
- one file), each file carrying the package's name, version and licence in a banner that names
178
+ `acorn.js`, `minimatch.js`, `semver.js` and `yauzl.js` (each installed package with its own
179
+ dependencies in one file), each file carrying the package's name, version and licence in a banner that names
178
180
  the exact version compiled. `zod` is compiled the same way into `dist/vendor/zod.js`. The
179
181
  packages inlined with them are listed in the generated section at the end of this file.
180
182
 
181
- The MIT text below applies to the derivative, `model-probe`, `@opencode-ai/models`, `yauzl`, `pend`, and
183
+ The MIT text below applies to the derivative, `model-probe`, `@opencode-ai/models`, `acorn`, `yauzl`, `pend`, and
182
184
  `typebox` with the copyright notices above. The ISC text immediately below applies to `yaml` and
183
185
  `semver`, each with its own copyright holder listed above (the ISC terms are identical);
184
186
  `minimatch` is covered by the separate Blue Oak Model License text further down, and its
@@ -649,6 +651,7 @@ Consult each package for its complete license text.
649
651
  - @modelcontextprotocol/sdk@1.32.1: license metadata = MIT (installed by npm beside this package)
650
652
  - @mozilla/readability@0.6.0: license metadata = Apache-2.0 (installed by npm beside this package)
651
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)
652
655
  - defuddle@0.19.3: license metadata = MIT (installed by npm beside this package)
653
656
  - linkedom@0.16.11: license metadata = ISC (installed by npm beside this package)
654
657
  - marked@18.0.11: license metadata = MIT (installed by npm beside this package)
@@ -689,6 +692,8 @@ each licence named is under "Full License Texts" above.
689
692
  - Copyright 2025 The Model Context Protocol Authors
690
693
  - @typesafe-ai/sdk@0.6.0, MIT, compiled into dist/mcp-adapter.js
691
694
  - Copyright (c) 2026 TypeSafe
695
+ - acorn@8.18.0, MIT, compiled into dist/vendor/acorn.js
696
+ - Copyright (C) 2012-2022 by various contributors (see AUTHORS)
692
697
  - ajv-formats@3.0.1, MIT, compiled into dist/mcp-adapter.js
693
698
  - Copyright (c) 2020 Evgeny Poberezkin
694
699
  - ajv@8.20.0, MIT, compiled into dist/mcp-adapter.js
@@ -13,11 +13,13 @@ it. Read the whole file before editing anything it describes.
13
13
  | `rules.md` | persistent instructions: where rule files live, their frontmatter, how to disable one |
14
14
  | `skills.md` | Skills: where they are found, the built-in ones, the `SKILL.md` frontmatter, how to disable one |
15
15
  | `agents.md` | helper agents and model profiles: where the files live, every field, which model a helper runs on, disabling one |
16
+ | `workflows.md` | workflows: scripted runs of helper agents — the folder layout, `meta`, stage files, `returns`, launching, resume, disabling one |
16
17
  | `mcp.md` | MCP servers: the two `mcp.json` files, the entry shape, disabling a server or a tool |
17
18
  | `web-search.md` | web search and page fetch: `web-search.json`, where requests go, keys, switching search off, failures |
18
19
  | `local-models.md` | models on the user's own machine: the llama.cpp router and `/llama`, other OpenAI-compatible servers |
19
20
  | `cache-warming.md` | prompt cache warming: what it costs and saves, which models it works with, `cacheWarming` and how to turn it on |
20
21
  | `plugins.md` | Marketplace plugins (dogfood builds only; a stable build has neither this file nor `explyt plugin`): the project manifest, the `explyt plugin` command, plugin values |
22
+ | `ci.md` | running without a terminal (CI, cron, scripts): `explyt -p` and `--mode json`, keys and `models.json`, permissions, installing and pinning a version, cancelling, exit codes, a GitHub Actions workflow |
21
23
  | `telegram.md` | the Telegram remote for terminal sessions (the terminal only; an IDE session has neither this file nor `/telegram`): setup and pairing, the `/telegram` menu, notifications, a message during a run, the bot's language, its files, what leaves the machine |
22
24
 
23
25
  ## User configuration lives under `.explyt/`
@@ -32,6 +34,7 @@ all projects, and in the project directory for one project:
32
34
  ~/.explyt/mcp.json MCP servers for every project
33
35
  ~/.explyt/agents/*.md helper agents for every project
34
36
  ~/.explyt/models/*.md model profiles for every project
37
+ ~/.explyt/workflows/<folder>/WORKFLOW.ts workflows for every project
35
38
 
36
39
  <project>/.explyt/settings.json settings for this project
37
40
  <project>/.explyt/rules/**/*.md rules for this project
@@ -39,6 +42,7 @@ all projects, and in the project directory for one project:
39
42
  <project>/.explyt/mcp.json MCP servers for this project
40
43
  <project>/.explyt/agents/*.md helper agents for this project
41
44
  <project>/.explyt/models/*.md model profiles for this project
45
+ <project>/.explyt/workflows/<folder>/WORKFLOW.ts
42
46
  <project>/.explyt/plugins.json Marketplace plugins enabled for this project (dogfood builds only)
43
47
  ```
44
48
 
@@ -0,0 +1,237 @@
1
+ # Running without a terminal: CI, cron and scripts
2
+
3
+ `explyt` runs one prompt and exits when it is asked for print or JSON output. It needs no
4
+ terminal then, so it works in GitHub Actions, GitLab CI, cron jobs and shell scripts.
5
+
6
+ Supported platforms: **Linux and macOS**. On Windows a run starts, but it is neither supported nor
7
+ tested.
8
+
9
+ ## The invocation
10
+
11
+ ```bash
12
+ explyt -p "review the diff" # print mode: the final answer on stdout
13
+ explyt --mode json -p "list the files" # JSON mode: JSONL events on stdout
14
+ git diff | explyt -p "review this" # piped text joins the prompt
15
+ ```
16
+
17
+ - Quote the prompt and put `--` before a prompt held in a variable: `-p -- "$PROMPT"`. Every
18
+ unquoted word becomes a prompt of its own, and each one is a separate request; only the answer to
19
+ the last one is printed. Without `--` a prompt that starts with `-` is read as an option:
20
+ `--permission-mode=bypassPermissions` in `$PROMPT` would let every call run. After `--` a word
21
+ that starts with `@` is still a file to attach, so text you do not control goes on stdin, not on
22
+ the command line ("Untrusted content").
23
+ - Write every JSON run as `--mode json -p "<prompt>"`. A prompt before the flags needs `-p`:
24
+ `explyt "review" -p` works, `explyt "review" --mode json` is refused as an unknown command.
25
+ - A literal prompt that starts with `-` goes after `--` too: `explyt -p -- "-x is wrong"`.
26
+ - In a run with `-p`, a subcommand (`update`, `login`, `plugin`, `tui`, …) works only as the first
27
+ argument. Anywhere else it reaches the model as a prompt: `explyt -p update` asks the model
28
+ about "update".
29
+ - Stdout carries only the answer (print mode) or the events (JSON mode). Every message of the agent
30
+ itself goes to stderr.
31
+ - A bare `explyt` without a terminal still refuses: it is the terminal UI.
32
+ - A run without a prompt (an empty `-p`, an empty pipe, an unset `$PROMPT`) refuses with exit 1
33
+ before any model request.
34
+ - When nothing is piped in and the job's stdin may stay open, add `< /dev/null`: the agent reads a
35
+ piped stdin to its end before it starts. A GitHub Actions step closes it by itself.
36
+ - Send command output through a pipe or a file, not through `@<(git diff)`: the engine skips a file
37
+ of size 0, and a process substitution reports size 0. In a CI step, where the agent should be
38
+ started with `exec` ("Cancelling and time limits"), write the output to a file and redirect it:
39
+ `git diff > "$RUNNER_TEMP/diff.txt"; exec explyt -p "review" < "$RUNNER_TEMP/diff.txt"`.
40
+
41
+ ## Model and credentials
42
+
43
+ Pass a model explicitly with `--model <provider>/<model>`. Without it the agent picks a model by
44
+ itself, usually the provider's most capable and most expensive one. The model list is
45
+ `explyt --list-models` (without `-p`, so the list goes to stdout).
46
+
47
+ **A provider key from the environment.** A provider the agent knows (Anthropic, OpenAI, Google,
48
+ OpenRouter, Mistral, …) needs no file: set its own variable in the step from a CI secret, for example
49
+ `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` or `OPENROUTER_API_KEY`, and pass `--model <provider>/<model>`.
50
+
51
+ **A key from your personal account.** Write a `models.json` provider whose `apiKey` names an
52
+ environment variable (`"$NAME"` is read from the environment):
53
+
54
+ ```json
55
+ {
56
+ "providers": {
57
+ "ci-account": {
58
+ "baseUrl": "https://plugin.staging.explyt.ai/openai/api/v1",
59
+ "api": "openai-completions",
60
+ "apiKey": "$CI_ACCOUNT_KEY",
61
+ "models": [{ "id": "<model id from your account>" }]
62
+ }
63
+ }
64
+ }
65
+ ```
66
+
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
+ `--model ci-account/<model id>` and set `CI_ACCOUNT_KEY` from a secret.
69
+
70
+ **Your own provider.** Any server that speaks an API the agent supports (a company proxy, vLLM, LM
71
+ Studio, a hosted gateway) is a `models.json` provider of its own. `apiKey` and every `headers` value
72
+ may name an environment variable:
73
+
74
+ ```json
75
+ {
76
+ "providers": {
77
+ "corp": {
78
+ "baseUrl": "https://llm.example.com/v1",
79
+ "api": "openai-completions",
80
+ "apiKey": "$CORP_LLM_KEY",
81
+ "headers": { "X-Team": "$CORP_TEAM" },
82
+ "models": [{ "id": "qwen2.5-coder-32b" }]
83
+ }
84
+ }
85
+ }
86
+ ```
87
+
88
+ Then run with `--model corp/qwen2.5-coder-32b`. `api` names the protocol the server speaks:
89
+ `openai-completions` (most OpenAI-compatible servers), `openai-responses`, `azure-openai-responses`,
90
+ `anthropic-messages`, `google-generative-ai` or `mistral-conversations`.
91
+
92
+ Keep keys out of the command line: `--api-key` is visible to every process on the runner and can
93
+ end up in the step's log. When several sources hold a key, the agent takes the first of: `--api-key`,
94
+ `auth.json`, `apiKey` in `models.json`, the provider's environment variable.
95
+
96
+ **Where `models.json` and `auth.json` go.** Both live in the agent directory:
97
+
98
+ - the managed installation (the installer): `<installation root>/agent`, by default
99
+ `~/.local/share/explyt-ai-agent/agent`;
100
+ - a job-local npm install (see "Pinning a version"): `$XDG_DATA_HOME/explyt-ai-agent/agent`, or
101
+ `~/.local/share/explyt-ai-agent/agent` when `XDG_DATA_HOME` is unset.
102
+
103
+ With default paths both are the same directory. `PI_CODING_AGENT_DIR` set in the step points either
104
+ form at a directory of your choice, for example one the job writes `models.json` into.
105
+
106
+ ## Permissions
107
+
108
+ A run starts in the permission mode of a terminal session: `default`, unless
109
+ `permissions.defaultMode` says otherwise (`settings.md`). In `default` a call that would ask for
110
+ approval is blocked, because nobody can answer, and the model is told why. To let every call run:
111
+
112
+ ```bash
113
+ explyt --permission-mode bypassPermissions -p "fix the failing test"
114
+ ```
115
+
116
+ A resumed chat (`--continue`) starts in the mode saved with it, and a saved `afk` starts as
117
+ `bypassPermissions`.
118
+
119
+ **Untrusted content.** A job that runs on pull-request content reads whatever instructions that
120
+ content holds. Until a person you trust has read that content, do not give the job secrets, in any
121
+ permission mode. `default` blocks only the
122
+ calls that would ask; every other command runs without a question, network commands such as
123
+ `curl` and commands that print the environment included. A project's MCP servers run commands from
124
+ the project's own files before the model sees anything. A run loads the project's own resources as the
125
+ terminal does: `.explyt/settings.json`, rules (`.explyt/rules/`, `AGENTS.md`), Skills
126
+ (`.explyt/skills`, `.agents/skills`), helper agents and model profiles, and enabled Marketplace
127
+ plugins. It also reads the rule and Skill files of other agents that `rules.md` and `skills.md` list
128
+ (`CLAUDE.md`, `.claude/`, …; the files under "Rules of other agents" in `rules.md` only for an agent `otherAgents` enables) and starts the MCP servers of the project's MCP files (`mcp.md`). It
129
+ does not load the engine's `.pi` settings, system prompts, packages or extensions. A later version
130
+ will start a project's MCP servers only after they are approved; until then a run starts them without
131
+ asking.
132
+
133
+ Text from a pull request, an issue or a comment never goes on the command line. Keep the `-p`
134
+ argument your own fixed text and pass the untrusted text on stdin, where the agent reads it as
135
+ plain text: write it to a file and redirect it (`< "$RUNNER_TEMP/input.txt"`). In GitHub Actions
136
+ never put `${{ github.event.* }}`, or any expression whose value someone else controls, inside
137
+ `run:`: the runner pastes the value into the script before the shell starts, so it can run
138
+ commands. Pass it through `env:` and refer to the variable instead.
139
+
140
+ In GitHub Actions, `on: pull_request` gives a pull request from a fork no secrets, so a review job
141
+ there has no key and fails. Do not switch such a job to `pull_request_target`, or to `workflow_run`
142
+ with a checkout of the pull request's head: both hand the secrets to the fork's content. A pull
143
+ request from your own repository does get secrets, so the example workflow below keeps the key in a
144
+ GitHub environment with required reviewers: the job waits until a reviewer has read the pull
145
+ request and approves the run, and only then sees the key. Create the environment (`agent-review`
146
+ below) under Settings → Environments, add yourself or your team as required reviewers, turn on
147
+ "Prevent self-review", and store the key as an environment secret, not a repository secret. The
148
+ example also keeps the job's own token out of reach: `persist-credentials: false` leaves no token
149
+ in `.git/config`, and `permissions: contents: read` limits what it could do.
150
+
151
+ ## Installing on a fresh runner
152
+
153
+ The installer installs the newest version of a channel:
154
+
155
+ ```bash
156
+ curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/explyt/explyt-ai-agent-distribution/main/install.sh | sh -s -- --channel stable
157
+ ```
158
+
159
+ Without a terminal the installer does not add `~/.local/bin` to `PATH`; it only reports the line to
160
+ add. A later step calls `~/.local/bin/explyt` by its full path, or adds the directory first:
161
+
162
+ ```bash
163
+ echo "$HOME/.local/bin" >> "$GITHUB_PATH"
164
+ ```
165
+
166
+ ## Pinning a version
167
+
168
+ The installer takes no version. To pin one, install the package into the job's temporary directory
169
+ and run it from there. It needs Node.js 22.19 or newer on `PATH` first, for example from
170
+ `actions/setup-node`:
171
+
172
+ ```bash
173
+ npm install --prefix "$RUNNER_TEMP/agent" @explyt/ai-agent@<version>
174
+ exec "$RUNNER_TEMP/agent/node_modules/.bin/explyt" -p -- "$PROMPT"
175
+ ```
176
+
177
+ This install puts nothing on `PATH`. It does not apply the release's pinned transitive
178
+ dependencies, so those may differ from the managed installation's. `npx` is not recommended in CI:
179
+ npm then stays the step's top process, and it does not pass every cancel signal on.
180
+
181
+ ## Cancelling and time limits
182
+
183
+ Make the agent the last command of the step with `exec`:
184
+
185
+ ```bash
186
+ exec explyt -p -- "$PROMPT"
187
+ ```
188
+
189
+ On cancel the runner signals only the step's shell. With `exec` the agent is that process, so it
190
+ stops at once. Without `exec` the shell ends and the agent keeps running, and keeps spending tokens,
191
+ until the runner tears the job down. A pipe into the agent (`git diff | exec explyt …`) keeps
192
+ the shell on top as well; use a file instead ("The invocation"). Give the step a time limit
193
+ (`timeout-minutes` in GitHub Actions); the agent has no turn or time limit of its own. If the agent
194
+ is killed outright (`kill -9`, the out-of-memory killer), its engine notices within about a second
195
+ and stops on its own.
196
+
197
+ ## Exit codes
198
+
199
+ | Run | Exit code |
200
+ |---|---|
201
+ | print mode, the answer succeeds | 0 |
202
+ | print mode, the answer ends with an error or an abort | 1 |
203
+ | JSON mode, any model outcome | 0, the outcome is in the events |
204
+ | no prompt | 1 |
205
+ | no key found, or the engine cannot start | non-zero |
206
+ | cancelled by a signal | 128 + the signal: 130 for `SIGINT`, 143 for `SIGTERM` |
207
+
208
+ A GitHub Actions cancel of a step that runs `exec explyt -p ...` reports 130, because the runner
209
+ sends `SIGINT` first.
210
+
211
+ ## A complete GitHub Actions workflow
212
+
213
+ ```yaml
214
+ name: review
215
+ on: pull_request
216
+ permissions:
217
+ contents: read
218
+ jobs:
219
+ review:
220
+ runs-on: ubuntu-latest
221
+ environment: agent-review # required reviewers; the key is an environment secret
222
+ timeout-minutes: 15
223
+ steps:
224
+ - uses: actions/checkout@v4
225
+ with:
226
+ fetch-depth: 0
227
+ persist-credentials: false
228
+ - name: Install the agent
229
+ run: curl --proto '=https' --tlsv1.2 -fsSL https://raw.githubusercontent.com/explyt/explyt-ai-agent-distribution/main/install.sh | sh -s -- --channel stable
230
+ - name: Review the diff
231
+ env:
232
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
233
+ BASE: ${{ github.base_ref }}
234
+ run: |
235
+ git diff "origin/$BASE...HEAD" > "$RUNNER_TEMP/diff.txt"
236
+ exec ~/.local/bin/explyt --model anthropic/claude-sonnet-4-6 -p "Review this diff" < "$RUNNER_TEMP/diff.txt"
237
+ ```
@@ -0,0 +1,62 @@
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
+ ## Plugin commands
22
+
23
+ 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`.
24
+
25
+ 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.
26
+
27
+ 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.
28
+
29
+ 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.
30
+
31
+ ## Values and credentials
32
+
33
+ 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:
34
+
35
+ ```text
36
+ explyt plugin install <plugin-id>[@<version>] --values-file <values-file>
37
+ ```
38
+
39
+ ```json
40
+ { "github_pat": "ghp_...", "mode": "http" }
41
+ ```
42
+
43
+ Later changes go through `config set`:
44
+
45
+ ```text
46
+ explyt plugin config set <plugin-id>@<version> <values-file>
47
+ explyt plugin config set <plugin-id>@<version> --project <values-file>
48
+ ```
49
+
50
+ 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:
51
+
52
+ ```json
53
+ { "values": { "mode": "mcp" }, "unset": ["api_key"] }
54
+ ```
55
+
56
+ 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.
57
+
58
+ 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:
59
+
60
+ ```text
61
+ explyt plugin config set-run-mode <plugin-id>@<version> <server-name> <index>
62
+ ```
@@ -15,7 +15,49 @@ does not repeat them in every conversation.
15
15
  | `<project>/.claude/CLAUDE.md` | `project:.claude/CLAUDE.md` | plain Markdown |
16
16
  | `<project>/CLAUDE.local.md` | `project:CLAUDE.local.md` | plain Markdown |
17
17
 
18
- Only these locations, plus the rules of the Marketplace plugins the project enables (dogfood builds
18
+ These seven are always read.
19
+
20
+ ### Rules of other agents
21
+
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.
26
+
27
+ | Agent | Path | Rule ID | Format |
28
+ |---|---|---|---|
29
+ | `claude` | `~/.claude/rules/**/*.md` | `user:.claude/rules/style.md` | Claude rule |
30
+ | `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
+ | `opencode` | `~/.config/opencode/AGENTS.md` | `user:.config/opencode/AGENTS.md` | plain Markdown |
32
+ | `claude` | `<project>/.claude/rules/**/*.md` | `project:.claude/rules/api.md` | Claude rule |
33
+ | `cursor` | `<project>/.cursorrules` | `project:.cursorrules` | plain Markdown |
34
+ | `cursor` | `<project>/.cursor/rules/**/*.mdc` | `project:.cursor/rules/ts.mdc` | Cursor rule |
35
+ | `codex` | `<project>/AGENTS.override.md` | `project:AGENTS.override.md` | plain Markdown |
36
+
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.
40
+
41
+ - **Claude rule** — optional frontmatter of which only `paths` counts: a YAML list whose every
42
+ element is one glob, or one string of globs separated by commas (`src/*.{ts,tsx}, test/**` is
43
+ two). With `paths` the body
44
+ applies after a matching read, as `filePattern` does; without it, or when the frontmatter is not
45
+ valid YAML, the file is a whole-session rule with the frontmatter removed. A file whose
46
+ frontmatter block is not closed is a broken rule: it does not apply and is reported.
47
+ - **Cursor rule** — frontmatter with `alwaysApply`, `globs` and `description`. `alwaysApply: true`
48
+ applies for the whole session; otherwise `globs` (a list whose every element is one glob, or a
49
+ comma-separated string) applies after a matching read. When the frontmatter is not valid YAML
50
+ (Cursor writes `globs: *.ts` unquoted), the three fields are read from their lines as written:
51
+ `globs` as a comma-separated string, split outside `{…}`; `alwaysApply` only when it is exactly
52
+ `true`; `description` as is. Lists, quotes and comments are understood only in valid YAML. A file with neither is an
53
+ agent-requested or manual Cursor rule: `/rules` lists it as invalid with that reason, and it does not
54
+ apply. A file whose frontmatter
55
+ block is not closed is a broken rule: it does not apply and is reported.
56
+
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.
59
+
60
+ Besides these, only the rules of the Marketplace plugins the project enables (dogfood builds
19
61
  only). A `CLAUDE.md`
20
62
  or `AGENTS.md` in a subdirectory is not picked up, and there is no search up the directory tree —
21
63
  the project is the session's working directory.
@@ -29,6 +29,9 @@ One object per section, with the setting's keys inside it:
29
29
  },
30
30
  "subagents": {
31
31
  "maxConcurrency": 20
32
+ },
33
+ "workflows": {
34
+ "disabledWorkflows": ["audit-routes"]
32
35
  }
33
36
  }
34
37
  ```
@@ -44,10 +47,15 @@ rest of the file as it is.
44
47
  | `skills.disabledSkills` | array of strings | `[]` | Skill names that are unavailable; see `skills.md` |
45
48
  | `sessionTitle.enabled` | boolean | `true` | whether a new chat gets a short title generated by the model after its first turn succeeds |
46
49
  | `permissions.defaultMode` | string | `"default"` | the permission mode a new chat starts in: `default`, `paranoid` or `bypassPermissions`; global layer only |
50
+ | `otherAgents.enabled` | array of agent ids | unset | other agents whose **home** files are read; global layer only; see "Other agents" below |
51
+ | `otherAgents.asked` | array of agent ids | unset | agents whose home answer is already given, read or not read; global layer only |
52
+ | `otherAgents.projectDefault` | object | `{}` | per agent id, `"allow"` or `"deny"` for its project files in every project; global layer only |
53
+ | `otherAgents.projects` | object | `{}` | per project path, per agent id, `"allow"` or `"deny"` for its project files in that project; wins over `projectDefault`; global layer only |
47
54
  | `afk.maxContinuations` | positive integer | `10` | how many follow-ups the `afk` mode sends after the last user message before it stops; global layer only |
48
55
  | `subagents.maxConcurrency` | positive integer | `20` | Maximum simultaneously running or waiting children |
49
56
  | `subagents.disabledAgents` | array of strings | `[]` | helper agent names that are unavailable; see `agents.md` |
50
57
  | `subagents.disabledProfiles` | array of strings | `[]` | model profile names that are unavailable; see `agents.md` |
58
+ | `workflows.disabledWorkflows` | array of strings | `[]` | workflow names that are unavailable by name; see `workflows.md` |
51
59
  | `tui.mascot` | string | `"cat"` | the animated mascot in the terminal's working row: `cat`, `snake`, `pacman`, `tetris`, `fishing`, `robot`, `pong`, `crab`, or `custom` for the user's own |
52
60
  | `tui.customMascotFrames` | array of strings | `[]` | the frames of the custom mascot, one string per frame, played in order |
53
61
  | `tui.customMascotText` | string | `"Working…"` | the word in front of the custom mascot |
@@ -62,10 +70,39 @@ rest of the file as it is.
62
70
  | `notifications.whenFocusUnknown` | string | `"off"` | `off`, `idle` or `always`: what to do when the terminal cannot tell whether its window is active |
63
71
  | `notifications.idleSeconds` | whole number | `60` | for `idle`: seconds without a key before a notification is sent, 5 to 3600 |
64
72
 
65
- The rule, Skill, agent and profile list settings take exact, case-sensitive entries. None supports
73
+ The rule, Skill, agent, profile and workflow list settings take exact, case-sensitive entries. None supports
66
74
  globs or prefixes: `"pdf-*"` matches nothing. An entry matching nothing is kept, not an error.
67
- A `disabledAgents` or `disabledProfiles` value that is not an array of strings, such as
68
- `"disabledProfiles": "strong"`, is ignored for that layer with a warning.
75
+ A `disabledAgents`, `disabledProfiles` or `disabledWorkflows` value that is not an array of
76
+ strings, such as `"disabledProfiles": "strong"`, is ignored for that layer with a warning.
77
+
78
+ ### Other agents: `otherAgents`
79
+
80
+ Which other coding agents' rule files are read, by agent id: `claude`, `cursor`, `codex`,
81
+ `opencode`, `pi`, `kilo`, `gemini` (exact, lower case). `rules.md` lists the files per agent.
82
+ The four keys are read from the **global** layer only, so a cloned repository cannot turn another
83
+ agent's files on; the same keys in a project `settings.json` are ignored with a warning.
84
+
85
+ ```json
86
+ {
87
+ "otherAgents": {
88
+ "enabled": ["claude", "codex"],
89
+ "projectDefault": { "cursor": "deny" },
90
+ "projects": { "/home/me/work/app": { "cursor": "allow", "claude": "allow" } }
91
+ }
92
+ }
93
+ ```
94
+
95
+ - `enabled` decides the home files; `projects` and `projectDefault` decide the project-root files.
96
+ The two are independent.
97
+ - A key of `projects` is the project's absolute path; it matches the project through symlinks and,
98
+ on a case-insensitive disk, whatever its letter case. When two keys name one project, `deny` wins.
99
+ - A value that is not of the shape above is ignored with a warning; valid entries next to it still
100
+ apply. An unknown agent id is ignored. Of `projects`, only the entries whose key names this
101
+ project are checked; another project's entries are left alone.
102
+ - A change applies at the next session start or the engine's `/reload`, not mid-session.
103
+
104
+ The Claude `CLAUDE.md` files and the Skill directories of other agents (`skills.md`) are read
105
+ whatever these keys hold; the keys only add other agents' rule files.
69
106
 
70
107
  For `subagents.maxConcurrency`, a valid project value overrides the global value. An invalid
71
108
  value is ignored for that layer with a warning, so the other layer or the default still applies.
@@ -73,7 +110,10 @@ value is ignored for that layer with a warning, so the other layer or the defaul
73
110
  No setting chooses a subagent's permission mode. A subagent starts in the permission mode its
74
111
  parent session has when the subagent starts (`default`, `paranoid`, `bypassPermissions` or `afk`),
75
112
  with a copy of the parent's "Allow for this session" approvals, and follows the parent's later
76
- switches. A `permission` key left in the `subagents` section is ignored. The user switches the mode
113
+ switches. The one exception is a workflow's stage agents:
114
+ every stage agent runs in `bypassPermissions`, whatever the session's mode, because the user
115
+ approved the workflow's launch question for them (see `workflows.md`). A `permission` key left in
116
+ the `subagents` section is ignored. The user switches the mode
77
117
  in the chat (the IDE's mode control, or the `Shift+Tab` quick switch, `/mode` and
78
118
  `--permission-mode` in the terminal), and each chat keeps its own.
79
119
 
@@ -100,11 +140,15 @@ in one mode, for example without questions:
100
140
 
101
141
  ### The `afk` mode and `afk.maxContinuations`
102
142
 
103
- `afk` is for a run nobody watches. Like `bypassPermissions` it asks nothing; in addition
104
- `ask_user_question` answers the model at once that the user is away, and after each run the agent
105
- sends the model a follow-up telling it to continue, until the model ends a run with a last line
106
- `AFK_DONE` or `afk.maxContinuations` follow-ups have been sent since the last user message. A chat
107
- saved in `afk` reopens in `bypassPermissions`.
143
+ `afk` is for a run nobody watches. Like `bypassPermissions` it runs every command without asking;
144
+ in addition `ask_user_question` answers the model at once that the user is away, and after each run
145
+ the agent sends the model a follow-up telling it to continue, until the model ends a run with a last
146
+ line `AFK_DONE` or `afk.maxContinuations` follow-ups have been sent since the last user message.
147
+ No dialog appears in `afk` at all: an MCP server's form or URL elicitation is cancelled, an MCP
148
+ sampling confirmation is approved, and a subagent's permission question gets Allow once.
149
+ Every follow-up is a full model request, so a long unattended run can use many tokens. When the
150
+ model last heard that the user is away, the user's next message outside `afk` tells it the user
151
+ is back, also in a reopened chat. A chat saved in `afk` reopens in `bypassPermissions`.
108
152
 
109
153
  ```json
110
154
  { "afk": { "maxContinuations": 25 } }
@@ -223,7 +267,9 @@ that is not a whole number from 5 to 3600 takes that key's default; the other ke
223
267
  The terminal UI runs **full screen** by default: the editor and the status lines stay at the bottom,
224
268
  the conversation scrolls inside the window (mouse wheel, `PgUp`/`PgDn`, `Ctrl+Home`/`Ctrl+End`), and
225
269
  on exit the conversation is printed to the terminal. Text selected with the mouse is **not** copied
226
- by itself: `Ctrl+X` copies the selection.
270
+ by itself: `Ctrl+C` copies the selection and drops it (`Ctrl+X` copies and keeps it; with no selection it copies the last answer). Without a selection `Ctrl+C`
271
+ clears the prompt, and pressed twice it exits. With `fullscreenCopyOnSelect` on, releasing the mouse
272
+ already copies, and `Ctrl+C` keeps its clear/exit meaning.
227
273
 
228
274
  The two keys behind this are the engine's own, not `.explyt/` settings. They live in the
229
275
  engine's settings file, `<root>/agent/settings.json` (`updates.md` says where `<root>` is). The user
@@ -247,6 +293,6 @@ IDE.
247
293
 
248
294
  ## How the two layers combine
249
295
 
250
- A rule, Skill, agent or profile is affected when its ID or name appears in **either** layer's array, with one
296
+ A rule, Skill, agent, profile or workflow is affected when its ID or name appears in **either** layer's array, with one
251
297
  exception stated in `rules.md`: a rule owned by the project can be disabled only through the
252
298
  project layer.
@@ -38,6 +38,7 @@ The product ships its own Skills, listed in `/skills` with the source `builtin`:
38
38
  | Name | What it does |
39
39
  |---|---|
40
40
  | `code-review-orchestrated` | Agrees a review setup with the user, runs independent reviewers and publishes one report |
41
+ | `debug-root-cause` | Proves the cause of a bug before any code change, then fixes that cause with a failing test first |
41
42
 
42
43
  A built-in Skill lives inside the installed product, not under any root above — do not look for
43
44
  it there or edit it in place. To change one, write a Skill with the **same `name`** in any root
@@ -77,7 +78,9 @@ when_to_use: Use when the user asks for a changelog or release notes
77
78
  The `name` in the frontmatter is the Skill's identity; it does not have to match the directory
78
79
  name, but making them equal keeps things findable. Two `SKILL.md` files claiming one name make
79
80
  **both** unavailable — neither wins. This includes plugin Skills: an ordinary Skill named like a
80
- Skill of an enabled plugin makes both unavailable.
81
+ Skill of an enabled plugin makes both unavailable. A Skill and a workflow with the same name
82
+ are both unavailable as well: neither the Skill nor the workflow command works until one of them
83
+ is renamed. A workflow's name is the `meta.name` of its `WORKFLOW.ts` (see `workflows.md`).
81
84
 
82
85
  A plugin Skill's frontmatter follows the plugin format: `name` and `description` follow the rules
83
86
  above, and instead of the two boolean fields it has `invocation` — `any` (the default: the user
@@ -86,7 +89,8 @@ and the model), `user` (only the user) or `model` (only the model).
86
89
  A Skill is **invalid** — and unavailable — when the frontmatter is missing, unparseable or not a
87
90
  YAML mapping, when `name` or `description` breaks a rule above, when an optional field has the
88
91
  wrong type, or when `name` is already taken by a command that exists — a built-in such as `model`,
89
- `compact` or `settings`, or one this product registers such as `rules` or `skills`; renaming the
92
+ `compact` or `settings`, one this product registers such as `rules` or `skills`, or one the IDE
93
+ connection handles itself (`autocompact`, `steering`, `follow-up`); renaming the
90
94
  Skill is the fix. A field that is not in the table is
91
95
  ignored and never makes a Skill invalid. An empty body is valid.
92
96
 
@@ -14,7 +14,7 @@ write a token or a Telegram setting into any `settings.json`; nothing reads it t
14
14
  1. The user creates a bot of their own with `@BotFather` in Telegram (`/newbot`) and copies its
15
15
  token. The product has no shared bot and no server of its own: the terminal talks to Telegram
16
16
  directly.
17
- 2. The user opens @BotFather's mini app (the Open button in the BotFather chat) → the bot →
17
+ 2. The user opens @BotFather → **Open** (the mini app) → the bot → **Bot Settings** →
18
18
  **Threads Settings**; the classic `/mybots` menu does not have these settings. There:
19
19
  - turn **on** **Threaded Mode**. Setup refuses a bot with Threaded Mode off, because a session
20
20
  the user opens gets a topic of its own (topics exist only on demand; see below);
@@ -23,8 +23,9 @@ write a token or a Telegram setting into any `settings.json`; nothing reads it t
23
23
  create threads, setup warns and still pairs, and the bot posts the same warning once in its
24
24
  main chat.
25
25
  3. In the terminal: `/telegram`, then `Set up…`. It asks for the token in a masked prompt.
26
- 4. Setup shows a single-use link `https://t.me/<bot>?start=<code>` and a QR code. The user opens it
27
- on the phone within 5 minutes and presses Start. The Telegram account that does this becomes the
26
+ 4. Setup shows a single-use link `https://t.me/<bot>?start=<code>` and a QR code; it does not open
27
+ a browser. The user opens the link within 5 minutes (clicking it in the terminal or scanning the
28
+ code with the phone) and presses Start. The Telegram account that does this becomes the
28
29
  only one that can control the agent. A wrong, expired or used code gets no reply in Telegram;
29
30
  the terminal says to open the newest link that setup showed. A link from an earlier setup
30
31
  or an earlier terminal run is no longer valid. The link and QR code leave the terminal once the
@@ -52,6 +53,9 @@ connection (`online` or `offline`) and whether you are marked away:
52
53
  | `Re-pair the bot…` | set the remote up again (above), after a confirmation |
53
54
  | `Unpair…` | after a confirmation, delete the bot's topics in the chat, the token and all remote state |
54
55
 
56
+ A choice in `Notifications` or `Message during a run`, or Esc there, returns to the main menu, which
57
+ shows the value now stored; Esc in the main menu closes it.
58
+
55
59
  Before pairing the menu has one item, `Set up…`. While a setup waits for `/start`, the menu offers
56
60
  `Cancel setup` first; it takes the link off the screen, and the link no longer pairs anyone. If the
57
61
  setup had already paired by then, the terminal says so; unpair from the menu to undo it. If the link