pi-open-agents 0.1.0 → 0.1.1
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 +187 -38
- package/package.json +13 -5
package/README.md
CHANGED
|
@@ -1,78 +1,189 @@
|
|
|
1
1
|
# pi-open-agents
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
[](https://www.npmjs.com/package/pi-open-agents)
|
|
4
|
+
[](https://opensource.org/licenses/MIT)
|
|
5
|
+
[](https://pi.dev)
|
|
4
6
|
|
|
5
|
-
|
|
7
|
+
Unified agent and subagent management for [pi](https://pi.dev), with [OpenCode](https://github.com/sst/opencode)-compatible agent definitions.
|
|
8
|
+
|
|
9
|
+
Replaces `pi-agent-mode` and `@johnnywu/pi-subagents` with a single, coherent plugin.
|
|
10
|
+
|
|
11
|
+
---
|
|
6
12
|
|
|
7
13
|
## Why
|
|
8
14
|
|
|
9
|
-
Pi delegates agent management to two separate npm plugins that use incompatible
|
|
15
|
+
Pi delegates agent management to two separate npm plugins that use incompatible
|
|
16
|
+
frontmatter schemas, divergent defaults, and fragmented semantics. This plugin
|
|
17
|
+
replaces both with one unified system that also reads OpenCode-format agent
|
|
18
|
+
definitions — so your agents work in **both** pi and OpenCode without modification.
|
|
10
19
|
|
|
11
|
-
|
|
20
|
+
### Comparison
|
|
12
21
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
|
|
19
|
-
|
|
22
|
+
| Feature | `pi-agent-mode` | `@johnnywu/pi-subagents` | `pi-open-agents` |
|
|
23
|
+
|---------|-----------------|--------------------------|------------------|
|
|
24
|
+
| Primary agent switching | ✅ | ❌ | ✅ |
|
|
25
|
+
| Subagent delegation | ❌ | ✅ | ✅ |
|
|
26
|
+
| Per-agent thinking level | ❌ *(broken)* | ❌ *(defaults to `off`)* | ✅ |
|
|
27
|
+
| OpenCode permission system | ❌ | ❌ | ✅ |
|
|
28
|
+
| OpenCode `.agent.md` format | ❌ | ❌ | ✅ |
|
|
29
|
+
| One plugin for everything | ❌ | ❌ | ✅ |
|
|
30
|
+
|
|
31
|
+
## Known issues with separate extensions
|
|
32
|
+
|
|
33
|
+
Before `pi-open-agents`, agent management in pi required two separate plugins:
|
|
34
|
+
`pi-agent-mode` (primary agents) and `@johnnywu/pi-subagents` (subagent delegation).
|
|
35
|
+
Using them together causes several problems that are **impossible to fix without
|
|
36
|
+
a unified plugin**:
|
|
37
|
+
|
|
38
|
+
### Model override conflicts
|
|
39
|
+
|
|
40
|
+
`pi-agent-mode` reads `defaultAgent` from `settings.json` and applies the primary
|
|
41
|
+
agent's model globally — including to subagents spawned by `pi-subagents`.
|
|
42
|
+
|
|
43
|
+
This breaks multi-provider setups where different agents need different models
|
|
44
|
+
(e.g., orchestrator on a strong reasoning model, subagents on a fast local model).
|
|
45
|
+
|
|
46
|
+
**Symptoms**: Subagents ignore their `model:` frontmatter and use the primary
|
|
47
|
+
agent's model. Workarounds like `defaultModel: "_none_"` or removing
|
|
48
|
+
`defaultAgent` entirely become necessary.
|
|
49
|
+
|
|
50
|
+
**`pi-open-agents` fixes this**: Each agent's `model:` frontmatter is respected
|
|
51
|
+
independently. No global model override.
|
|
52
|
+
|
|
53
|
+
### Thinking level defaults to `off`
|
|
54
|
+
|
|
55
|
+
`pi-subagents` hardcodes subagent thinking to `off`, ignoring
|
|
56
|
+
`defaultThinkingLevel` from `settings.json`. There is no way to configure
|
|
57
|
+
per-agent thinking levels.
|
|
58
|
+
|
|
59
|
+
**`pi-open-agents` fixes this**: Subagents inherit `defaultThinkingLevel` from
|
|
60
|
+
`settings.json` by default, and can override per-agent via the `thinking:`
|
|
61
|
+
frontmatter field.
|
|
62
|
+
|
|
63
|
+
### Incompatible frontmatter schemas
|
|
64
|
+
|
|
65
|
+
The two plugins use different frontmatter field names for the same concepts,
|
|
66
|
+
and both ignore fields they don't recognize:
|
|
67
|
+
|
|
68
|
+
| Concept | `pi-agent-mode` | `pi-subagents` | `pi-open-agents` |
|
|
69
|
+
|---------|-----------------|---------------|------------------|
|
|
70
|
+
| Thinking level | `reasoningEffort` *(ignored)* | Not supported | `thinking` |
|
|
71
|
+
| Tool restrictions | `tools` (CSV) | `tools` (CSV) | `permission` (rules) + `tools` (CSV) |
|
|
72
|
+
| Agent visibility | `mode` *(ignored)* | Not supported | `mode: primary\|subagent\|all` |
|
|
73
|
+
| Prompt injection | Not configurable | `systemPrompt` | `systemPrompt: append\|replace\|replace-all` |
|
|
74
|
+
| Model override | Global (all agents) | Per-agent | Per-agent |
|
|
75
|
+
|
|
76
|
+
**`pi-open-agents` fixes this**: One unified schema with all fields working
|
|
77
|
+
together. Backward compatible — existing fields (`tools`, `reasoningEffort`)
|
|
78
|
+
are normalized at parse time.
|
|
79
|
+
|
|
80
|
+
### No permission system
|
|
81
|
+
|
|
82
|
+
Neither plugin supports OpenCode-style permission rules. Tool restriction is
|
|
83
|
+
limited to a simple CSV whitelist (`tools: bash, read`) with no pattern matching,
|
|
84
|
+
no deny rules, and no per-file restrictions.
|
|
85
|
+
|
|
86
|
+
**`pi-open-agents` fixes this**: Full OpenCode permission system with
|
|
87
|
+
`allow`/`deny`/`ask` actions, glob patterns (`*.env`, `**/*.key`), and
|
|
88
|
+
last-match-wins evaluation.
|
|
89
|
+
|
|
90
|
+
### Migration impact
|
|
91
|
+
|
|
92
|
+
Real-world deployments using both plugins together have required workarounds
|
|
93
|
+
such as:
|
|
94
|
+
|
|
95
|
+
- Removing `defaultAgent` from `settings.json` and using `--agent` CLI flag instead
|
|
96
|
+
- Setting `defaultModel` to a sentinel value (`"_none_"`) to prevent global override
|
|
97
|
+
- Using context-based model IDs to force provider isolation
|
|
98
|
+
- Multiple rapid commits to diagnose model routing failures
|
|
99
|
+
|
|
100
|
+
All of these workarounds become unnecessary with `pi-open-agents`.
|
|
20
101
|
|
|
21
|
-
##
|
|
102
|
+
## Who is this for?
|
|
103
|
+
|
|
104
|
+
- **Pi users** frustrated with managing two plugins for agent switching and delegation
|
|
105
|
+
- **OpenCode users** who want to try pi without rewriting their agent definitions
|
|
106
|
+
- **Teams** who want a portable, version-controlled agent library that works across harnesses
|
|
107
|
+
- **Anyone** who wants per-agent thinking levels, permission rules, or model overrides in pi
|
|
108
|
+
|
|
109
|
+
## Quick start
|
|
22
110
|
|
|
23
111
|
```bash
|
|
24
112
|
pi install pi-open-agents
|
|
25
113
|
```
|
|
26
114
|
|
|
27
|
-
|
|
115
|
+
Remove the old plugins from `~/.pi/agent/settings.json`:
|
|
28
116
|
|
|
29
117
|
```json
|
|
30
118
|
{
|
|
31
119
|
"packages": [
|
|
32
|
-
"pi-open-agents"
|
|
120
|
+
"npm:pi-open-agents"
|
|
33
121
|
]
|
|
34
122
|
}
|
|
35
123
|
```
|
|
36
124
|
|
|
37
|
-
|
|
125
|
+
That's it. Existing `.agent.md` files work without changes (default `mode: all`).
|
|
126
|
+
|
|
127
|
+
## Features
|
|
128
|
+
|
|
129
|
+
- **Unified agent definitions** — one `.md` format, superset of OpenCode + pi
|
|
130
|
+
- **Mode-based visibility** — `primary` in the TUI selector, `subagent` for delegation, `all` for both
|
|
131
|
+
- **OpenCode-compatible** — reads agents from `.opencode/agent/`, `.opencode/mode/`, and `.agents/`
|
|
132
|
+
- **Permission system** — OpenCode-style `allow`/`deny`/`ask` with glob patterns, last-match-wins
|
|
133
|
+
- **Thinking level per-agent** — `off`/`minimal`/`low`/`medium`/`high`/`xhigh`, with fallback to `settings.json`
|
|
134
|
+
- **Subagent execution** — child pi process spawning with scoped tools, skills, and session fork
|
|
135
|
+
- **Skill loading** — per-agent skills with wildcard support (`lark-*`, `github`)
|
|
136
|
+
|
|
137
|
+
## Agent definition format
|
|
38
138
|
|
|
39
139
|
```yaml
|
|
40
140
|
---
|
|
41
141
|
# === Identity ===
|
|
42
|
-
name:
|
|
43
|
-
description:
|
|
44
|
-
mode: primary|subagent|all
|
|
45
|
-
hidden: false
|
|
142
|
+
name: code-reviewer # required
|
|
143
|
+
description: Reviews code for quality and security issues
|
|
144
|
+
mode: subagent # primary | subagent | all (default: all)
|
|
145
|
+
hidden: false # hide from TUI selectors
|
|
46
146
|
color: "#44BA81"
|
|
47
147
|
|
|
48
148
|
# === Model ===
|
|
49
|
-
model:
|
|
50
|
-
variant: thinking # model variant
|
|
51
|
-
temperature: 0.7
|
|
52
|
-
top_p: 0.95
|
|
149
|
+
model: anthropic/claude-sonnet # per-agent override
|
|
53
150
|
|
|
54
151
|
# === Execution ===
|
|
55
|
-
thinking: xhigh
|
|
56
|
-
|
|
57
|
-
systemPrompt: append|replace|replace-all # default: append
|
|
152
|
+
thinking: xhigh # off|minimal|low|medium|high|xhigh
|
|
153
|
+
systemPrompt: append # append | replace | replace-all (default: append)
|
|
58
154
|
|
|
59
155
|
# === Permissions (OpenCode-style) ===
|
|
60
156
|
permission:
|
|
61
|
-
|
|
62
|
-
edit:
|
|
63
|
-
|
|
64
|
-
"
|
|
65
|
-
read: allow
|
|
157
|
+
"*": allow
|
|
158
|
+
"edit": deny # read-only agent
|
|
159
|
+
"bash":
|
|
160
|
+
"git *": allow # can run git commands only
|
|
66
161
|
|
|
67
162
|
# === Subagent controls ===
|
|
68
|
-
maxDepth:
|
|
69
|
-
allowedAgents:
|
|
70
|
-
skills:
|
|
163
|
+
maxDepth: 5 # recursion limit when spawning subagents
|
|
164
|
+
allowedAgents: [explorer] # which subagents this can spawn
|
|
165
|
+
skills: security-audit, git-* # per-agent skills with wildcards
|
|
71
166
|
---
|
|
72
|
-
You are a
|
|
167
|
+
You are a code reviewer. Analyze code for bugs, security vulnerabilities,
|
|
168
|
+
and maintainability issues. Never modify files — report findings only.
|
|
73
169
|
```
|
|
74
170
|
|
|
75
|
-
|
|
171
|
+
### How the body becomes the system prompt
|
|
172
|
+
|
|
173
|
+
The markdown body after the frontmatter becomes the agent's prompt. The `systemPrompt`
|
|
174
|
+
field controls how it interacts with pi's default system prompt:
|
|
175
|
+
|
|
176
|
+
| Mode | Behavior |
|
|
177
|
+
|------|----------|
|
|
178
|
+
| `append` (default) | Agent body is prepended to pi's system prompt |
|
|
179
|
+
| `replace` | Agent body replaces pi's prompt (primary agents: same as `append` in inline mode) |
|
|
180
|
+
| `replace-all` | Only the agent body is used — pi's prompt is discarded entirely |
|
|
181
|
+
|
|
182
|
+
For **subagents** (child process), the agent body **is** the system prompt — pi's default
|
|
183
|
+
prompt is not included. If the agent has `skills:`, they are injected as an XML block
|
|
184
|
+
after the body.
|
|
185
|
+
|
|
186
|
+
## Discovery paths
|
|
76
187
|
|
|
77
188
|
Agents are loaded from multiple locations (project overrides global by name):
|
|
78
189
|
|
|
@@ -84,6 +195,14 @@ Agents are loaded from multiple locations (project overrides global by name):
|
|
|
84
195
|
| `.opencode/{agent,agents,mode}/*.md` | Project | OpenCode |
|
|
85
196
|
| `.agents/*.md` | Project | Shared |
|
|
86
197
|
|
|
198
|
+
### Mode-based visibility
|
|
199
|
+
|
|
200
|
+
| `mode` | TUI selector | `subagent` tool | `set_agent` tool |
|
|
201
|
+
|--------|-------------|-----------------|------------------|
|
|
202
|
+
| `primary` | ✅ visible | ❌ | ✅ |
|
|
203
|
+
| `subagent` | ❌ | ✅ available | ✅ |
|
|
204
|
+
| `all` (default) | ✅ visible | ✅ available | ✅ |
|
|
205
|
+
|
|
87
206
|
## Usage
|
|
88
207
|
|
|
89
208
|
### Interactive
|
|
@@ -95,7 +214,6 @@ Agents are loaded from multiple locations (project overrides global by name):
|
|
|
95
214
|
| `/agents` | List all agents |
|
|
96
215
|
| `/agent-search <query>` | Search agents |
|
|
97
216
|
| `Ctrl+Shift+M` | Cycle agents |
|
|
98
|
-
| `Alt+S` | Search prompt |
|
|
99
217
|
| `--agent <name>` | CLI flag for startup agent |
|
|
100
218
|
|
|
101
219
|
### Programmatic (LLM tools)
|
|
@@ -114,6 +232,29 @@ Agents are loaded from multiple locations (project overrides global by name):
|
|
|
114
232
|
4. Gradually add `mode: primary` or `mode: subagent` to control visibility
|
|
115
233
|
5. Gradually adopt `permission:` over `tools:` whitelist
|
|
116
234
|
|
|
235
|
+
### Using OpenCode agents in pi
|
|
236
|
+
|
|
237
|
+
If you already have OpenCode agent definitions in `.opencode/agent/`, they work
|
|
238
|
+
out of the box — no conversion needed:
|
|
239
|
+
|
|
240
|
+
```yaml
|
|
241
|
+
---
|
|
242
|
+
# OpenCode format — works as-is in pi
|
|
243
|
+
name: triage
|
|
244
|
+
mode: subagent
|
|
245
|
+
model: openai/gpt-4o
|
|
246
|
+
tools:
|
|
247
|
+
read: true
|
|
248
|
+
bash: false
|
|
249
|
+
description: Triages issues by reading and categorizing them.
|
|
250
|
+
---
|
|
251
|
+
You are an issue triage agent...
|
|
252
|
+
```
|
|
253
|
+
|
|
254
|
+
The `tools` map is automatically converted to permission rules (`true` → `allow`,
|
|
255
|
+
`false` → `deny`). Fields that are pi-specific (`thinking`, `maxDepth`,
|
|
256
|
+
`allowedAgents`) are ignored by OpenCode without breaking.
|
|
257
|
+
|
|
117
258
|
## Development
|
|
118
259
|
|
|
119
260
|
```bash
|
|
@@ -122,6 +263,14 @@ npm test # 84 tests
|
|
|
122
263
|
npm run typecheck # tsc --noEmit
|
|
123
264
|
```
|
|
124
265
|
|
|
266
|
+
### Docker testing
|
|
267
|
+
|
|
268
|
+
```bash
|
|
269
|
+
docker compose run --rm pi-sandbox
|
|
270
|
+
```
|
|
271
|
+
|
|
272
|
+
See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full technical design.
|
|
273
|
+
|
|
125
274
|
## Attribution
|
|
126
275
|
|
|
127
276
|
This project builds on code and ideas from:
|
|
@@ -130,7 +279,7 @@ This project builds on code and ideas from:
|
|
|
130
279
|
- [pi-subagents](https://github.com/jwu/pi-subagents) by jwu (MIT)
|
|
131
280
|
- [opencode](https://github.com/sst/opencode) by sst (MIT)
|
|
132
281
|
|
|
133
|
-
See
|
|
282
|
+
See [ATTRIBUTION.md](./ATTRIBUTION.md) for details.
|
|
134
283
|
|
|
135
284
|
## License
|
|
136
285
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pi-open-agents",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"pi-package",
|
|
@@ -48,10 +48,18 @@
|
|
|
48
48
|
"typebox": "*"
|
|
49
49
|
},
|
|
50
50
|
"peerDependenciesMeta": {
|
|
51
|
-
"@earendil-works/pi-ai": {
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
"
|
|
51
|
+
"@earendil-works/pi-ai": {
|
|
52
|
+
"optional": true
|
|
53
|
+
},
|
|
54
|
+
"@earendil-works/pi-coding-agent": {
|
|
55
|
+
"optional": true
|
|
56
|
+
},
|
|
57
|
+
"@earendil-works/pi-tui": {
|
|
58
|
+
"optional": true
|
|
59
|
+
},
|
|
60
|
+
"typebox": {
|
|
61
|
+
"optional": true
|
|
62
|
+
}
|
|
55
63
|
},
|
|
56
64
|
"devDependencies": {
|
|
57
65
|
"@types/node": "^24.0.0",
|