@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.
- package/README.md +3 -3
- package/THIRD-PARTY-NOTICES.md +10 -5
- package/agent-docs/README.md +4 -0
- package/agent-docs/ci.md +237 -0
- package/agent-docs/plugins.md +62 -0
- package/agent-docs/rules.md +43 -1
- package/agent-docs/settings.md +57 -11
- package/agent-docs/skills.md +6 -2
- package/agent-docs/telegram.md +7 -3
- package/agent-docs/updates.md +3 -1
- package/agent-docs/workflows.md +421 -0
- package/dist/cli/brand-profile.js +6 -6
- package/dist/cli/engine-signals.js +77 -0
- package/dist/cli/engine.js +416 -11
- package/dist/cli/index.js +185 -21
- package/dist/cli/install-net.js +147 -0
- package/dist/cli/install-node.js +10 -6
- package/dist/cli/install-npm.js +9 -1
- package/dist/cli/install-run.js +9 -4
- package/dist/cli/launch.js +4 -1
- package/dist/cli/plugin.js +1 -0
- package/dist/extensions/ask-user-question.js +1 -1
- package/dist/extensions/bash.js +1 -1
- package/dist/extensions/custom-provider.js +1 -1
- package/dist/extensions/explyt-account.js +1 -1
- package/dist/extensions/hello.js +1 -1
- package/dist/extensions/identity.js +1 -1
- package/dist/extensions/login-menu.js +1 -1
- package/dist/extensions/mcp.js +1 -1
- package/dist/extensions/misc-hacks.js +1 -1
- package/dist/extensions/notify.js +1 -1
- package/dist/extensions/plugins.js +1 -0
- package/dist/extensions/policy.js +1 -1
- package/dist/extensions/rules.js +1 -1
- package/dist/extensions/session-title.js +1 -1
- package/dist/extensions/skills.js +1 -1
- package/dist/extensions/subagents.js +55 -1
- package/dist/extensions/telegram.js +1 -1
- package/dist/extensions/telemetry.js +1 -1
- package/dist/extensions/todo.js +1 -1
- package/dist/extensions/tool-rows.js +1 -1
- package/dist/extensions/tui.js +1 -1
- package/dist/extensions/update-notice.js +1 -1
- package/dist/extensions/web-access.js +1 -1
- package/dist/extensions/write.js +1 -1
- package/dist/install/installer.js +126 -16
- package/dist/rpiv-ask-user-question/{chunk-NXE76BE4.js → chunk-27VC5VIA.js} +1 -1
- package/dist/rpiv-ask-user-question/{chunk-V6PM4YRC.js → chunk-3E6FYMMK.js} +6 -6
- package/dist/rpiv-ask-user-question/{chunk-CDNB7COL.js → chunk-R5GW6VHB.js} +1 -1
- package/dist/rpiv-ask-user-question/index.js +3 -3
- package/dist/rpiv-todo/{chunk-V6PM4YRC.js → chunk-3E6FYMMK.js} +6 -6
- package/dist/rpiv-todo/{chunk-7UKL4B2W.js → chunk-MENO7HZY.js} +1 -1
- package/dist/rpiv-todo/{chunk-RYUIY66D.js → chunk-V3SMMTR6.js} +1 -1
- package/dist/rpiv-todo/index.js +4 -4
- package/dist/skills/builtin/code-review-orchestrated/SKILL.md +3 -3
- package/dist/skills/builtin/debug-root-cause/SKILL.md +75 -0
- package/dist/vendor/acorn.js +5732 -0
- 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.
|
|
21
|
-
npx -y "@explyt/ai-agent@0.5.
|
|
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.
|
|
31
|
+
Run `npx -y @explyt/ai-agent@0.5.1 --help` for the available options.
|
package/THIRD-PARTY-NOTICES.md
CHANGED
|
@@ -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
|
|
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
|
package/agent-docs/README.md
CHANGED
|
@@ -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
|
|
package/agent-docs/ci.md
ADDED
|
@@ -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
|
+
```
|
package/agent-docs/rules.md
CHANGED
|
@@ -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
|
-
|
|
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.
|
package/agent-docs/settings.md
CHANGED
|
@@ -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
|
|
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 `
|
|
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.
|
|
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
|
|
104
|
-
`ask_user_question` answers the model at once that the user is away, and after each run
|
|
105
|
-
sends the model a follow-up telling it to continue, until the model ends a run with a last
|
|
106
|
-
`AFK_DONE` or `afk.maxContinuations` follow-ups have been sent since the last user message.
|
|
107
|
-
|
|
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
|
|
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.
|
package/agent-docs/skills.md
CHANGED
|
@@ -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`,
|
|
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
|
|
package/agent-docs/telegram.md
CHANGED
|
@@ -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
|
|
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
|
|
27
|
-
|
|
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
|