pi-landstrip 0.18.26 → 0.18.28
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 +112 -194
- package/dist/index.ts +482 -215
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,18 +1,16 @@
|
|
|
1
1
|
# pi-landstrip
|
|
2
2
|
|
|
3
3
|
`pi-landstrip` adds sandboxed Bash, primary agents, and process-backed subagents
|
|
4
|
-
to [Pi](https://pi.dev/).
|
|
5
|
-
|
|
4
|
+
to [Pi](https://pi.dev/). It requires Pi 0.82.0 or later and Node.js 22.19.0 or
|
|
5
|
+
later.
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
## Installation
|
|
7
|
+
## Install
|
|
10
8
|
|
|
11
9
|
```sh
|
|
12
10
|
pi install npm:pi-landstrip
|
|
13
11
|
```
|
|
14
12
|
|
|
15
|
-
For a manual install, add the package to
|
|
13
|
+
For a manual global or trusted-project install, add the package to Pi's
|
|
16
14
|
`settings.json`:
|
|
17
15
|
|
|
18
16
|
```json
|
|
@@ -21,228 +19,148 @@ For a manual install, add the package to global or trusted project
|
|
|
21
19
|
}
|
|
22
20
|
```
|
|
23
21
|
|
|
24
|
-
The package includes
|
|
25
|
-
Arm64.
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
AI Bash calls and shell commands entered with `!` or `!!` run through
|
|
30
|
-
Landstrip. Subagents run as separate Pi RPC processes and are sandboxed unless
|
|
31
|
-
the sandbox is explicitly disabled.
|
|
22
|
+
The package includes Landstrip binaries for Linux, macOS, and Windows on x64 and
|
|
23
|
+
Arm64. If sandboxing is enabled but the binary or platform is unusable, Bash,
|
|
24
|
+
shell commands, and sandboxed workers fail closed. Only `--no-sandbox` or
|
|
25
|
+
`"enabled": false` permits execution without OS isolation.
|
|
32
26
|
|
|
33
|
-
|
|
34
|
-
outside the OS sandbox. Agent permissions still control tool dispatch, but they
|
|
35
|
-
are not an OS isolation boundary. On Linux and macOS, primary Bash reads therefore
|
|
36
|
-
use the same host view by default; writes remain sandboxed. Subagent processes
|
|
37
|
-
retain the configured read and write policy.
|
|
27
|
+
## Permissions
|
|
38
28
|
|
|
39
|
-
|
|
40
|
-
restricts worker reads within the user's home to the project and a few bootstrap
|
|
41
|
-
files. Direct network access is blocked. When the platform permits loopback, the
|
|
42
|
-
extension's proxy filters allowed HTTP and HTTPS domains.
|
|
29
|
+
Pi evaluates two permission categories:
|
|
43
30
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
- `/sandbox` inspects and toggles the sandbox.
|
|
49
|
-
- `/agents` selects agents, edits agent settings, and shows task sessions.
|
|
50
|
-
- `Ctrl+Shift+A` cycles visible primary agents while Pi is idle.
|
|
31
|
+
| Category | Checked | Controls |
|
|
32
|
+
| -------- | --------------------------------------- | -------------------------------- |
|
|
33
|
+
| Agent | Before dispatch | Whether an agent may call a tool |
|
|
34
|
+
| Sandbox | Before file access and during processes | Filesystem and network resources |
|
|
51
35
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
Use `--no-sandbox` or set `enabled` to `false` in `sandbox.json`:
|
|
55
|
-
|
|
56
|
-
```json
|
|
57
|
-
{
|
|
58
|
-
"enabled": false
|
|
59
|
-
}
|
|
60
|
-
```
|
|
36
|
+
Agent rules return `deny`, `ask`, or `allow`. An agent approval authorizes only
|
|
37
|
+
tool dispatch and cannot bypass a sandbox hard denial.
|
|
61
38
|
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
39
|
+
By default, primary `read`, `write`, `edit`, and `apply_patch` tools run in the
|
|
40
|
+
trusted Pi process and only agent permissions apply. Set
|
|
41
|
+
`toolFilesystemPolicy` to `"sandbox"` to preflight their paths against
|
|
42
|
+
`sandbox.json`. `denyWrite` remains a hard denial. If both agent and sandbox
|
|
43
|
+
approval are needed, Pi presents one prompt for the call.
|
|
65
44
|
|
|
66
|
-
|
|
45
|
+
AI Bash, `!`, `!!`, and subagent processes use OS isolation. Subagents rely on
|
|
46
|
+
that isolation instead of repeating file-tool preflight. Pi presents all agent
|
|
47
|
+
and sandbox requests through one FIFO prompt queue.
|
|
67
48
|
|
|
68
|
-
|
|
69
|
-
|
|
70
|
-
|
|
71
|
-
intentional stricter boundary. Worker processes always use the filesystem read
|
|
72
|
-
policy. Windows always uses policy reads because its sandbox requires an explicit
|
|
73
|
-
read allowlist.
|
|
49
|
+
Sandbox approvals may apply once, for the session, to the project, or globally.
|
|
50
|
+
Persistent approvals update `.pi/sandbox.json` or
|
|
51
|
+
`~/.pi/agent/sandbox.json`. Headless requests that require approval are denied.
|
|
74
52
|
|
|
75
|
-
|
|
53
|
+
## Sandbox configuration
|
|
76
54
|
|
|
77
|
-
|
|
78
|
-
| ---------------- | ------------------ | ------------------------------ |
|
|
79
|
-
| Agent permission | Before a tool runs | Which tools the agent may call |
|
|
80
|
-
| Sandbox policy | During a command | Filesystem and network access |
|
|
55
|
+
Sandbox policy merges in this order:
|
|
81
56
|
|
|
82
|
-
|
|
83
|
-
|
|
57
|
+
1. bundled [`sandbox.json`](./sandbox.json);
|
|
58
|
+
2. `~/.pi/agent/sandbox.json`;
|
|
59
|
+
3. `.pi/sandbox.json` for a trusted project.
|
|
84
60
|
|
|
85
|
-
|
|
61
|
+
Objects merge recursively, arrays combine, and later scalar values replace
|
|
62
|
+
earlier values. `/sandbox` displays or toggles the policy. It writes the project
|
|
63
|
+
policy in a trusted project and the global policy otherwise.
|
|
86
64
|
|
|
87
|
-
|
|
88
|
-
|
|
89
|
-
|
|
65
|
+
| Field | Bundled default |
|
|
66
|
+
| ----------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
67
|
+
| `enabled` | `true` |
|
|
68
|
+
| `shell.readAccess` | `"host"` |
|
|
69
|
+
| `filesystem.denyRead` | `["/Users", "/home"]` |
|
|
70
|
+
| `filesystem.allowRead` | `[".", "~/.gitconfig", "~/.config/git/config", "/dev/null"]` |
|
|
71
|
+
| `filesystem.allowWrite` | `[".", "/dev/null"]` |
|
|
72
|
+
| `filesystem.denyWrite` | `["**/.env", "**/.env.*", "**/*.pem", "**/*.key", ".pi/sandbox.json", "~/.pi/agent/sandbox.json"]` |
|
|
73
|
+
| `network.allowNetwork` | `false` |
|
|
74
|
+
| `network.allowLocalBinding` | `false` |
|
|
75
|
+
| `network.allowAllUnixSockets` | `false` |
|
|
76
|
+
| `network.allowUnixSockets` | `[]` |
|
|
77
|
+
| `network.allowedDomains` | `[]` |
|
|
78
|
+
| `network.deniedDomains` | `[]` |
|
|
79
|
+
| `windows.appContainerMode` | `"standard"` |
|
|
80
|
+
| `windows.allowLoopback` | `false` |
|
|
90
81
|
|
|
91
|
-
|
|
82
|
+
Filesystem and core network semantics follow the main
|
|
83
|
+
[Landstrip policy](https://github.com/landstrip/landstrip#policy). `allowedDomains`
|
|
84
|
+
and `deniedDomains` are plugin fields enforced by the local HTTP/HTTPS proxy.
|
|
92
85
|
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
"subagent_type": "explore",
|
|
98
|
-
"task_id": "optional-session-id",
|
|
99
|
-
"command": "optional-originating-command",
|
|
100
|
-
"background": false
|
|
101
|
-
}
|
|
102
|
-
```
|
|
86
|
+
`shell.readAccess: "host"` gives primary Bash and `!`/`!!` the trusted host read
|
|
87
|
+
view on Linux and macOS while retaining sandboxed writes. `"policy"` applies
|
|
88
|
+
`denyRead` and `allowRead`. Workers always use policy reads. Windows always uses
|
|
89
|
+
policy reads because it requires an explicit read allowlist.
|
|
103
90
|
|
|
104
|
-
`
|
|
105
|
-
|
|
106
|
-
completion later. Continue a saved task with `task_id`; inspect it with
|
|
107
|
-
`/agents <id>`.
|
|
91
|
+
With `enabled: false`, subagents remain separate processes but lose Landstrip OS
|
|
92
|
+
isolation; Pi warns once per session.
|
|
108
93
|
|
|
109
|
-
|
|
110
|
-
fresh process; continuing a task restores its saved session in a new process.
|
|
111
|
-
Agent `deny`, `ask`, and `allow` rules are checked before tool dispatch.
|
|
94
|
+
## Agent configuration
|
|
112
95
|
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
that access, so install only trusted plugins and use suitable credentials.
|
|
96
|
+
Agent configuration merges built-ins, global configuration, then trusted-project
|
|
97
|
+
configuration. Use either dedicated files:
|
|
116
98
|
|
|
117
|
-
|
|
99
|
+
- `~/.pi/agent/landstrip.json`
|
|
100
|
+
- `.pi/landstrip.json`
|
|
118
101
|
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
`~/.pi/agent/sandbox.json` and `.pi/sandbox.json`.
|
|
102
|
+
or a top-level `landstrip` object in the matching `settings.json`. Using both
|
|
103
|
+
forms at one scope is an error.
|
|
122
104
|
|
|
123
105
|
```json
|
|
124
106
|
{
|
|
125
|
-
"
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
134
|
-
|
|
135
|
-
}
|
|
136
|
-
}
|
|
137
|
-
},
|
|
138
|
-
"permission": {
|
|
139
|
-
"task": {
|
|
140
|
-
"*": "deny",
|
|
141
|
-
"review": "allow"
|
|
107
|
+
"maxSubagents": 2,
|
|
108
|
+
"toolFilesystemPolicy": "sandbox",
|
|
109
|
+
"agent": {
|
|
110
|
+
"review": {
|
|
111
|
+
"description": "Review without modifying files",
|
|
112
|
+
"mode": "subagent",
|
|
113
|
+
"prompt": "Report concrete findings.",
|
|
114
|
+
"permission": {
|
|
115
|
+
"edit": "deny",
|
|
116
|
+
"bash": "ask"
|
|
142
117
|
}
|
|
143
118
|
}
|
|
119
|
+
},
|
|
120
|
+
"permission": {
|
|
121
|
+
"task": {
|
|
122
|
+
"*": "deny",
|
|
123
|
+
"review": "allow"
|
|
124
|
+
}
|
|
144
125
|
}
|
|
145
126
|
}
|
|
146
127
|
```
|
|
147
128
|
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
`landstrip.agent` settings override Markdown agents with the same name.
|
|
155
|
-
Project definitions override global definitions.
|
|
156
|
-
|
|
157
|
-
For example, save this advisor subagent as `~/.pi/agent/agents/advisor.md`:
|
|
158
|
-
|
|
159
|
-
```markdown
|
|
160
|
-
---
|
|
161
|
-
description: Escalate to a stronger reviewer for a plan, correction, or stop signal
|
|
162
|
-
mode: subagent
|
|
163
|
-
hidden: false
|
|
164
|
-
variant: high
|
|
165
|
-
permission:
|
|
166
|
-
'*': deny
|
|
167
|
-
read: allow
|
|
168
|
-
grep: allow
|
|
169
|
-
glob: allow
|
|
170
|
-
list: allow
|
|
171
|
-
---
|
|
172
|
-
|
|
173
|
-
You are an advisor model in an advisor-strategy pattern. An executor model is running a task end-to-end — calling tools, reading results, iterating toward a solution. When the executor hits a decision it cannot reasonably solve alone, it consults you for guidance via the `task` tool with `subagent_type: "advisor"`.
|
|
174
|
-
|
|
175
|
-
The executor should put the full situation in the task prompt: the goal, what it has tried, tool results that matter, current hypothesis, and the decision it needs. You may use read-only tools to verify claims against the repository when file paths are given; do not modify anything.
|
|
176
|
-
|
|
177
|
-
Return ONE of:
|
|
178
|
-
|
|
179
|
-
- a **plan** (concrete next steps the executor should take),
|
|
180
|
-
- a **correction** (the executor is going down a wrong path — redirect it),
|
|
181
|
-
- a **stop signal** (the executor should halt and escalate to the user).
|
|
182
|
-
|
|
183
|
-
Be concise, directive, and grounded in the shared context. Name files, functions, and line numbers where possible. No preamble, no apologies, no meta-commentary about being an advisor — just the guidance the executor needs.
|
|
184
|
-
|
|
185
|
-
Give advice serious weight for the executor: prefer primary-source evidence and root causes over temporary fixes. If requirements are ambiguous or contradictory, stop and say what the user must decide.
|
|
186
|
-
```
|
|
187
|
-
|
|
188
|
-
See the main [Landstrip documentation](https://github.com/landstrip/landstrip#readme)
|
|
189
|
-
for `sandbox.json` fields and platform policy semantics.
|
|
190
|
-
|
|
191
|
-
### Platform notes
|
|
192
|
-
|
|
193
|
-
- **Linux:** blocked operations can be approved while the command is running.
|
|
194
|
-
- **macOS:** a worker's Seatbelt policy is fixed at startup; restart the task to
|
|
195
|
-
apply new filesystem access.
|
|
196
|
-
- **Windows:** the bundled policy uses standard AppContainer because Pi's Git
|
|
197
|
-
Bash cannot start in LPAC. Standard mode is weaker than LPAC.
|
|
198
|
-
`windows.allowLoopback` enables the domain proxy but exposes every local
|
|
199
|
-
loopback service. Restricted-user mode avoids that broad exemption.
|
|
129
|
+
| Field | Default | Values |
|
|
130
|
+
| ---------------------- | --------------- | -------------------------------------------- |
|
|
131
|
+
| `maxSubagents` | `1` | integer from 0 through 16; 0 disables `task` |
|
|
132
|
+
| `toolFilesystemPolicy` | `"host"` | `"host"` or `"sandbox"` |
|
|
133
|
+
| `agent` | built-in agents | named agent definitions |
|
|
134
|
+
| `permission` | built-in rules | global tool/resource rules |
|
|
200
135
|
|
|
201
|
-
|
|
202
|
-
|
|
203
|
-
|
|
204
|
-
|
|
205
|
-
npx @landstrip/landstrip windows install
|
|
206
|
-
npx @landstrip/landstrip windows status
|
|
207
|
-
```
|
|
136
|
+
Agent definitions accept `name`, `description`, `prompt`, `mode`, `model`,
|
|
137
|
+
`variant`, `temperature`, `top_p`, `steps`, `color`, `hidden`, `disable`,
|
|
138
|
+
`options`, and `permission`. `mode` is `primary`, `subagent`, or `all` and
|
|
139
|
+
defaults to `all`.
|
|
208
140
|
|
|
209
|
-
|
|
141
|
+
The built-in primary agents are `build` and `plan`; built-in subagents are
|
|
142
|
+
`general`, `scout`, and `explore`. Pi also loads Markdown agents from
|
|
143
|
+
`~/.pi/agent/agents/` and `.pi/agents/`. Project definitions override global
|
|
144
|
+
definitions, and configured agents override Markdown agents with the same name.
|
|
210
145
|
|
|
211
|
-
##
|
|
146
|
+
## Commands and tasks
|
|
212
147
|
|
|
213
|
-
|
|
214
|
-
|
|
215
|
-
|
|
216
|
-
- `getContext()` for sandbox and task context.
|
|
217
|
-
- `registerShellProvider()` for replacing POSIX shell invocation preparation.
|
|
218
|
-
- `prepareProcess()` for one policy-aware process launch.
|
|
219
|
-
- `registerWorkerExtension()` for trusted worker extensions.
|
|
220
|
-
- `on()` for sandbox and subagent lifecycle events.
|
|
221
|
-
|
|
222
|
-
A shell provider receives the command, working directory, composed command
|
|
223
|
-
environment, and abort signal. It returns an executable, arguments, minimal
|
|
224
|
-
launcher environment, required read paths, and optional cleanup. Landstrip adds
|
|
225
|
-
platform variables required by its launcher, such as Windows `ProgramData`.
|
|
226
|
-
Providers should pass the composed environment through a private temporary file,
|
|
227
|
-
include that file in `readPaths`, and remove it in `dispose()`; do not copy secrets
|
|
228
|
-
into `launcherEnv`. Landstrip remains responsible for starting the process, applying
|
|
229
|
-
policy, proxying network access, handling traps, and prompting for additional
|
|
230
|
-
access. Only one external provider can be active; disposing it restores the
|
|
231
|
-
built-in POSIX provider.
|
|
232
|
-
|
|
233
|
-
Use `provideLandstripShell()` to register a provider independently of extension
|
|
234
|
-
load order. Shell providers and worker extensions are trusted code. Workers also
|
|
235
|
-
receive an informational `LANDSTRIP_CONTEXT` environment value; it is not proof
|
|
236
|
-
of authorization.
|
|
148
|
+
- `/sandbox` inspects and toggles sandboxing.
|
|
149
|
+
- `/agents` selects or edits agents and lists task sessions.
|
|
150
|
+
- `Ctrl+Shift+A` cycles visible primary agents while Pi is idle.
|
|
237
151
|
|
|
238
|
-
|
|
152
|
+
The `task` tool requires `description`, `prompt`, and `subagent_type`. Optional
|
|
153
|
+
`task_id` continues a saved task, `command` records the originating command, and
|
|
154
|
+
`background: true` returns immediately. `/agents <task-id>` inspects a task.
|
|
155
|
+
Each invocation starts a fresh Pi RPC process; continuation restores its saved
|
|
156
|
+
session in a new process.
|
|
239
157
|
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
158
|
+
Workers use normal Pi resource and plugin discovery. Their model requests can
|
|
159
|
+
read Pi authentication and inherited credential environment variables. Install
|
|
160
|
+
only trusted worker plugins and use credentials appropriate for the sandboxed
|
|
161
|
+
task.
|
|
243
162
|
|
|
244
163
|
## License
|
|
245
164
|
|
|
246
|
-
`pi-landstrip` is licensed under `Apache-2.0`.
|
|
247
|
-
|
|
248
|
-
`Apache-2.0 AND LGPL-2.1-or-later`.
|
|
165
|
+
`pi-landstrip` is licensed under `Apache-2.0`. The bundled Landstrip package is
|
|
166
|
+
licensed separately as `Apache-2.0 AND LGPL-2.1-or-later`.
|