pi-open-agents 0.1.4 → 0.1.5

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 (2) hide show
  1. package/README.md +143 -155
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -6,182 +6,187 @@
6
6
 
7
7
  Unified agent and subagent management for [pi](https://pi.dev), with [OpenCode](https://github.com/sst/opencode)-compatible agent definitions.
8
8
 
9
- Replaces `pi-agent-mode` and `@johnnywu/pi-subagents` with a single, coherent plugin.
9
+ Replaces `pi-agent-mode` + `@johnnywu/pi-subagents` with one coherent plugin.
10
10
 
11
11
  ---
12
12
 
13
- ## Why
13
+ ## Quick start
14
14
 
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.
15
+ ```bash
16
+ pi install pi-open-agents
17
+ ```
19
18
 
20
- ### Comparison
19
+ Remove old plugins from `~/.pi/agent/settings.json`:
21
20
 
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 | ❌ | ❌ | ✅ |
21
+ ```json
22
+ {
23
+ "packages": ["npm:pi-open-agents"]
24
+ }
25
+ ```
30
26
 
31
- ## Known issues with separate extensions
27
+ Existing `.agent.md` files work without changes (default `mode: all`).
32
28
 
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**:
29
+ ---
37
30
 
38
- ### Model override conflicts
31
+ ## Why this exists
39
32
 
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`.
33
+ Pi splits agent management across two separate plugins — one for primary agents,
34
+ one for subagents. They use incompatible schemas, conflict on model routing, and
35
+ have no permission system. `pi-open-agents` replaces both:
42
36
 
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).
37
+ | | `pi-agent-mode` | `pi-subagents` | `pi-open-agents` |
38
+ |---|---|---|---|
39
+ | Primary agent switching | ✅ | ❌ | ✅ |
40
+ | Subagent delegation | ❌ | ✅ | ✅ |
41
+ | Per-agent thinking level | ❌ | ❌ | ✅ |
42
+ | Permission system | ❌ | ❌ | ✅ |
43
+ | OpenCode `.agent.md` format | ❌ | ❌ | ✅ |
45
44
 
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.
45
+ ---
49
46
 
50
- **`pi-open-agents` fixes this**: Each agent's `model:` frontmatter is respected
51
- independently. No global model override.
47
+ ## Features
52
48
 
53
- ### Thinking level defaults to `off`
49
+ ### Per-agent model, thinking, and permissions
54
50
 
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.
51
+ Every agent defines its own `model:`, `thinking:`, and `permission:` — no global
52
+ overrides, no sentinel values, no workarounds. An orchestrator can run on a strong
53
+ reasoning model while subagents run on a fast local model:
58
54
 
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.
55
+ ```yaml
56
+ ---
57
+ name: orchestrator
58
+ mode: primary
59
+ model: anthropic/claude-sonnet
60
+ thinking: high
61
+ ---
62
+ ```
62
63
 
63
- ### Incompatible frontmatter schemas
64
+ ```yaml
65
+ ---
66
+ name: fast-worker
67
+ mode: subagent
68
+ model: lm-studio/qwen-2.5-coder
69
+ thinking: off
70
+ ---
71
+ ```
64
72
 
65
- The two plugins use different frontmatter field names for the same concepts,
66
- and both ignore fields they don't recognize:
73
+ ### Permission system
67
74
 
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
+ Go beyond a simple tool whitelist. OpenCode-style rules with glob patterns, deny
76
+ rules, and per-action restrictions:
75
77
 
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.
78
+ ```yaml
79
+ permission:
80
+ "*": allow # default: everything allowed
81
+ "edit": deny # read-only agent
82
+ "bash":
83
+ "git *": allow # only git commands
84
+ "rm *": deny # never delete
85
+ "subagent": deny # no delegation
86
+ ```
79
87
 
80
- ### No permission system
88
+ Tool names are normalized automatically: `write` → `edit`, `task` → `subagent`,
89
+ `vscode` → `read`.
81
90
 
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.
91
+ ### Auto-injected delegation guidance
85
92
 
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.
93
+ If an agent has the `subagent` tool, the plugin automatically appends a
94
+ `## Subagent Delegation` block to its system prompt — listing available
95
+ subagents and the correct call syntax:
89
96
 
90
- ### Migration impact
97
+ ```
98
+ subagent({ agent: "<name>", task: "<task>" })
99
+ ```
91
100
 
92
- Real-world deployments using both plugins together have required workarounds
93
- such as:
101
+ You never need to explain delegation mechanics in agent prompts. The plugin
102
+ handles it, the same way pi handles tool descriptions.
94
103
 
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
104
+ ### Subagent execution engine
99
105
 
100
- All of these workarounds become unnecessary with `pi-open-agents`.
106
+ When an agent delegates, the plugin spawns a child pi process with the target
107
+ agent's configuration. The child runs in isolation — it gets `--model`,
108
+ `--system-prompt`, and `--tools` from the executor, not from `settings.json`.
109
+ This means:
101
110
 
102
- ## Who is this for?
111
+ - The primary agent's `defaultAgent` never leaks into subagents
112
+ - Each subagent runs with exactly the model and tools it declares
113
+ - Skills load per-agent, with wildcard support (`security-*`, `git-*`)
103
114
 
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
115
+ ### OpenCode compatibility
108
116
 
109
- ## Quick start
117
+ Your `.opencode/agent/` files work as-is. The `tools` map format is auto-converted
118
+ to permission rules, and pi-specific fields (`thinking`, `maxDepth`, `allowedAgents`)
119
+ are simply ignored by OpenCode without breaking:
110
120
 
111
- ```bash
112
- pi install pi-open-agents
121
+ ```yaml
122
+ # OpenCode format — works in pi without changes
123
+ name: triage
124
+ mode: subagent
125
+ tools:
126
+ read: true
127
+ bash: false
113
128
  ```
114
129
 
115
- Remove the old plugins from `~/.pi/agent/settings.json`:
116
-
117
- ```json
118
- {
119
- "packages": [
120
- "npm:pi-open-agents"
121
- ]
122
- }
123
- ```
130
+ ### Mode-based visibility
124
131
 
125
- That's it. Existing `.agent.md` files work without changes (default `mode: all`).
132
+ | `mode` | TUI selector | `subagent` tool | `set_agent` tool |
133
+ |--------|-------------|-----------------|------------------|
134
+ | `primary` | ✅ visible | ❌ | ✅ |
135
+ | `subagent` | ❌ | ✅ available | ✅ |
136
+ | `all` (default) | ✅ visible | ✅ available | ✅ |
126
137
 
127
- ## Features
138
+ Use `primary` for user-facing agents, `subagent` for delegated workers, `all` when
139
+ an agent serves both roles.
128
140
 
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`)
141
+ ---
136
142
 
137
143
  ## Agent definition format
138
144
 
139
145
  ```yaml
140
146
  ---
141
- # === Identity ===
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
147
+ name: my-agent # required
148
+ description: One-line description
149
+ mode: subagent # primary | subagent | all (default: all)
150
+ hidden: false # hide from TUI selectors
146
151
  color: "#44BA81"
147
152
 
148
- # === Model ===
149
- model: anthropic/claude-sonnet # per-agent override
150
-
151
- # === Execution ===
152
- thinking: xhigh # off|minimal|low|medium|high|xhigh
153
- systemPrompt: append # append | replace | replace-all (default: append)
153
+ model: anthropic/claude-sonnet # per-agent model override
154
+ thinking: xhigh # off|minimal|low|medium|high|xhigh
155
+ systemPrompt: replace # append | replace | replace-all (default: append)
154
156
 
155
- # === Permissions (OpenCode-style) ===
156
157
  permission:
157
158
  "*": allow
158
- "edit": deny # read-only agent
159
- "bash":
160
- "git *": allow # can run git commands only
159
+ "question": deny
160
+ "edit":
161
+ "*.env": deny
161
162
 
162
- # === Subagent controls ===
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
163
+ maxDepth: 5 # subagent recursion limit
164
+ allowedAgents: [explorer] # restrict which subagents this can spawn
165
+ skills: security-audit, git-* # per-agent skills with wildcards
166
166
  ---
167
- You are a code reviewer. Analyze code for bugs, security vulnerabilities,
168
- and maintainability issues. Never modify files — report findings only.
167
+ Your prompt goes here. This becomes the agent's system prompt.
169
168
  ```
170
169
 
171
- ### How the body becomes the system prompt
170
+ ### System prompt modes
171
+
172
+ The `systemPrompt` field controls how the agent body interacts with pi's default
173
+ prompt and workspace context files (CLAUDE.md, etc.):
174
+
175
+ | Mode | System prompt | Context files |
176
+ |------|---------------|---------------|
177
+ | `append` (default) | pi's prompt + agent body | ✅ loaded |
178
+ | `replace` | Agent body only | ✅ loaded |
179
+ | `replace-all` | Agent body only | ❌ disabled |
172
180
 
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:
181
+ Use `replace-all` for fully isolated agents that should not be influenced by
182
+ workspace context — e.g., a subagent that must run identically regardless of
183
+ the project it's invoked from.
175
184
 
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 |
185
+ For **subagents** (child process), the agent body **is** the system prompt —
186
+ pi's default prompt is not included. Skills are injected as an XML block after
187
+ the body.
181
188
 
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.
189
+ ---
185
190
 
186
191
  ## Discovery paths
187
192
 
@@ -195,13 +200,7 @@ Agents are loaded from multiple locations (project overrides global by name):
195
200
  | `.opencode/{agent,agents,mode}/*.md` | Project | OpenCode |
196
201
  | `.agents/*.md` | Project | Shared |
197
202
 
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 | ✅ |
203
+ ---
205
204
 
206
205
  ## Usage
207
206
 
@@ -224,36 +223,23 @@ Agents are loaded from multiple locations (project overrides global by name):
224
223
  | `search_agents` | Search agents by name/description/body |
225
224
  | `subagent` | Delegate task to a subagent (subagent/all mode only) |
226
225
 
227
- ## Migration from pi-agent-mode + pi-subagents
226
+ ---
228
227
 
229
- 1. Install: `pi install pi-open-agents`
230
- 2. Remove `npm:pi-agent-mode` and `npm:@johnnywu/pi-subagents` from settings
231
- 3. Existing agent `.md` files work without changes (default `mode: all`)
232
- 4. Gradually add `mode: primary` or `mode: subagent` to control visibility
233
- 5. Gradually adopt `permission:` over `tools:` whitelist
228
+ ## Migration
234
229
 
235
- ### Using OpenCode agents in pi
230
+ ```bash
231
+ pi install pi-open-agents
232
+ ```
236
233
 
237
- If you already have OpenCode agent definitions in `.opencode/agent/`, they work
238
- out of the box — no conversion needed:
234
+ Remove `npm:pi-agent-mode` and `npm:@johnnywu/pi-subagents` from `settings.json`.
235
+ Existing agent `.md` files work without changes.
239
236
 
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
- ```
237
+ Optional cleanup:
238
+
239
+ 1. Add `mode: primary` or `mode: subagent` to agent files for explicit visibility
240
+ 2. Gradually adopt `permission:` over the old `tools:` whitelist
253
241
 
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.
242
+ ---
257
243
 
258
244
  ## Development
259
245
 
@@ -271,6 +257,8 @@ docker compose run --rm pi-sandbox
271
257
 
272
258
  See [ARCHITECTURE.md](./ARCHITECTURE.md) for the full technical design.
273
259
 
260
+ ---
261
+
274
262
  ## Attribution
275
263
 
276
264
  This project builds on code and ideas from:
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-open-agents",
3
- "version": "0.1.4",
3
+ "version": "0.1.5",
4
4
  "description": "Unified agent and subagent management for pi coding agent, with OpenCode-compatible agent definitions.",
5
5
  "keywords": [
6
6
  "pi-package",