npm - pi-landstrip - Versions diffs - 0.18.33 → 0.18.35 - Mend

pi-landstrip 0.18.33 → 0.18.35

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 (5) hide show

package/README.md CHANGED Viewed

@@ -1,8 +1,7 @@
 # pi-landstrip
-`pi-landstrip` adds sandboxed Bash, primary agents, and process-backed subagents
-to [Pi](https://pi.dev/). It requires Pi 0.82.0 or later and Node.js 22.19.0 or
-later.
+Pi extension for sandboxed Bash, primary agents, and process-backed subagents.
+Pi 0.82.0 and Node.js 22.19.0 or newer are required.
 ## Install
@@ -10,189 +9,69 @@ later.
 pi install npm:pi-landstrip
 ```
-For a manual global or trusted-project install, add the package to Pi's
-`settings.json`:
-```json
-{
-  "packages": ["npm:pi-landstrip"]
-}
-```
-The package includes Landstrip binaries for Linux, macOS, and Windows on x64 and
-Arm64. If sandboxing is enabled but the binary or platform is unusable, Bash,
-shell commands, and sandboxed workers fail closed. Only `--no-sandbox` or
-`"enabled": false` permits execution without OS isolation.
+The package includes Landstrip binaries for Linux, macOS, and Windows on x64
+and Arm64. When sandboxing is enabled, an unusable binary or platform fails
+closed. Use `--no-sandbox` or set `enabled` to `false` for unsandboxed execution.
 ## Permissions
-Pi evaluates two permission categories:
-| Category | Checked                                 | Controls                         |
-| -------- | --------------------------------------- | -------------------------------- |
-| Agent    | Before dispatch                         | Whether an agent may call a tool |
-| Sandbox  | Before file access and during processes | Filesystem and network resources |
-Agent rules return `deny`, `ask`, or `allow`. An agent approval authorizes only
-tool dispatch and cannot bypass a sandbox hard denial.
-By default, primary `read`, `write`, `edit`, and `apply_patch` tools run in the
-trusted Pi process and only agent permissions apply. Set
-`toolFilesystemPolicy` to `"sandbox"` to preflight their paths against
-`sandbox.json`. `denyWrite` remains a hard denial. If both agent and sandbox
-approval are needed, Pi presents one prompt for the call.
-AI Bash, `!`, `!!`, and subagent processes use OS isolation. Subagents rely on
-that isolation instead of repeating file-tool preflight. Pi presents all agent
-and sandbox requests through one FIFO prompt queue.
-Sandbox approvals may apply once, for the session, to the project, or globally.
-Persistent approvals update `.pi/sandbox.json` or
-`~/.pi/agent/sandbox.json`. Headless requests that require approval are denied.
-## Sandbox configuration
+Agent permissions control tool dispatch. Sandbox permissions control filesystem
+and network access. Agent approval never bypasses a sandbox hard denial.
-Sandbox policy merges in this order:
+AI Bash, `!`, `!!`, and subagents use OS isolation. Primary file tools use the
+trusted Pi process unless `toolFilesystemPolicy` is `"sandbox"`. Persistent
+sandbox approvals update `.pi/sandbox.json` or `~/.pi/agent/sandbox.json`.
-1. bundled [`sandbox.json`](./sandbox.json);
-2. `~/.pi/agent/sandbox.json`;
-3. `.pi/sandbox.json` for a trusted project.
+## Sandbox settings
-Objects merge recursively, arrays combine, and later scalar values replace
-earlier values. `/sandbox` displays or toggles the policy. It writes the project
-policy in a trusted project and the global policy otherwise.
+Policy merges from bundled `sandbox.json`, global
+`~/.pi/agent/sandbox.json`, then trusted-project `.pi/sandbox.json`.
+`/settings` displays or toggles the effective policy.
-| Field                         | Bundled default                                                                                    |
-| ----------------------------- | -------------------------------------------------------------------------------------------------- |
-| `enabled`                     | `true`                                                                                             |
-| `shell.readAccess`            | `"host"`                                                                                           |
-| `filesystem.denyRead`         | `["/Users", "/home"]`                                                                              |
-| `filesystem.allowRead`        | `[".", "~/.gitconfig", "~/.config/git/config", "/dev/null"]`                                       |
-| `filesystem.allowWrite`       | `[".", "/dev/null"]`                                                                               |
-| `filesystem.denyWrite`        | `["**/.env", "**/.env.*", "**/*.pem", "**/*.key", ".pi/sandbox.json", "~/.pi/agent/sandbox.json"]` |
-| `network.allowNetwork`        | `false`                                                                                            |
-| `network.allowLocalBinding`   | `false`                                                                                            |
-| `network.allowAllUnixSockets` | `false`                                                                                            |
-| `network.allowUnixSockets`    | `[]`                                                                                               |
-| `network.allowedDomains`      | `[]`                                                                                               |
-| `network.deniedDomains`       | `[]`                                                                                               |
-| `windows.appContainerMode`    | `"standard"`                                                                                       |
-| `windows.allowLoopback`       | `false`                                                                                            |
-Filesystem and core network semantics follow the main
-[Landstrip policy](https://github.com/landstrip/landstrip#policy). `allowedDomains`
-and `deniedDomains` are plugin fields enforced by the local HTTP/HTTPS proxy.
-`shell.readAccess: "host"` gives primary Bash and `!`/`!!` the trusted host read
-view on Linux and macOS while retaining sandboxed writes. `"policy"` applies
-`denyRead` and `allowRead`. Workers always use policy reads. Windows always uses
-policy reads because it requires an explicit read allowlist.
-With `enabled: false`, subagents remain separate processes but lose Landstrip OS
-isolation; Pi warns once per session.
-## Agent configuration
+```json
+{
+  "enabled": true,
+  "shell": { "readAccess": "host" },
+  "filesystem": {
+    "allowWrite": ["."],
+    "denyWrite": ["**/.env", "**/*.pem"]
+  },
+  "network": { "allowNetwork": false }
+}
+```
-Agent configuration merges built-ins, global configuration, then trusted-project
-configuration. Use either dedicated files:
+See [`sandbox.json`](sandbox.json) for exact defaults. Workers always use policy
+reads. Windows requires an explicit read allowlist.
-- `~/.pi/agent/landstrip.json`
-- `.pi/landstrip.json`
+## Agents
-or a top-level `landstrip` object in the matching `settings.json`. Using both
-forms at one scope is an error.
+Configure agents in `~/.pi/agent/landstrip.json`, `.pi/landstrip.json`, or a
+`landstrip` object in the matching Pi settings file:
 ```json
 {
   "maxSubagents": 2,
   "toolFilesystemPolicy": "sandbox",
-  "agent": {
-    "review": {
-      "description": "Review without modifying files",
-      "mode": "subagent",
-      "prompt": "Report concrete findings.",
-      "permission": {
-        "edit": "deny",
-        "bash": "ask"
-      }
-    }
-  },
   "permission": {
-    "task": {
-      "*": "deny",
-      "review": "allow"
-    }
+    "task": { "*": "deny", "review": "allow" }
   }
 }
 ```
-| Field                  | Default         | Values                                       |
-| ---------------------- | --------------- | -------------------------------------------- |
-| `maxSubagents`         | `1`             | integer from 0 through 16; 0 disables `task` |
-| `toolFilesystemPolicy` | `"host"`        | `"host"` or `"sandbox"`                      |
-| `agent`                | built-in agents | named agent definitions                      |
-| `permission`           | built-in rules  | global tool/resource rules                   |
-Agent definitions accept `name`, `description`, `prompt`, `mode`, `model`,
-`variant`, `temperature`, `top_p`, `steps`, `color`, `hidden`, `disable`,
-`options`, and `permission`. `mode` is `primary`, `subagent`, or `all` and
-defaults to `all`. `/agents` Primary lists only `mode: primary` agents. The
-Subagent tab lists `mode: subagent` and `mode: all` agents, including JSON and
-Markdown definitions.
-The built-in primary agents are `build` and `plan`; built-in subagents are
-`general`, `scout`, and `explore`. Pi also loads Markdown agents from
-`~/.pi/agent/agents/` and `.pi/agents/`. Project definitions overlay global
-definitions. Configured fields overlay Markdown agents with the same name, so a
-model-only `landstrip.json` entry keeps the Markdown agent's mode, prompt, and
-permissions.
+`maxSubagents` accepts 0 through 16. Agent definitions can override model,
+prompt, mode, options, and permissions. Global definitions load before trusted
+project definitions.
 ## Commands and tasks
-- `/sandbox` inspects and toggles sandboxing.
-- `/agents` selects or edits agents and lists task sessions.
-- `Ctrl+Shift+A` cycles visible primary agents while Pi is idle.
-The `task` tool requires `description`, `prompt`, and `subagent_type`. Optional
-`task_id` continues a saved task, `command` records the originating command, and
-`background: true` returns immediately. `/agents <task-id>` inspects a task.
-Each invocation starts a fresh Pi RPC process; continuation restores its saved
-session in a new process.
-Workers use normal Pi resource and plugin discovery. Their model requests can
-read Pi authentication and inherited credential environment variables. Install
-only trusted worker plugins and use credentials appropriate for the sandboxed
-task.
-## Permission ask providers
-A separate Pi extension can resolve agent permission rules that return `ask` by
-registering one `LandstripPermissionAskProvider`:
-```ts
-import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
-import { provideLandstripPermissionAsk } from 'pi-landstrip/api';
-export default function permissionReviewer(pi: ExtensionAPI): void {
-  provideLandstripPermissionAsk(pi, {
-    id: 'example-reviewer',
-    async decide(request) {
-      if (request.toolName === 'bash' && request.input.command === 'git status') {
-        return { decision: 'allow' };
-      }
-      return { decision: 'abstain' };
-    },
-  });
-}
-```
+- `/settings` opens a screen-wide pane with sandbox and agent settings.
+- `/sandbox` opens the same pane on its sandbox section.
+- `/agents` selects agents and lists task sessions.
+- `Ctrl+Shift+A` cycles primary agents while Pi is idle.
-The provider receives the tool name and input, pending permission/resource pairs,
-the primary or subagent context, and an abort signal. `allow` approves that call,
-`deny` blocks it, and `abstain` uses the normal UI prompt or headless denial.
-Provider errors also fall back safely. Only one provider may be registered at a
-time; the helper works regardless of extension load order and returns a disposer.
+The `task` tool starts isolated workers. Set `background: true` to return
+immediately and use `task_id` to continue a saved task.
-## License
+## Licensing
-`pi-landstrip` is licensed under `Apache-2.0`. The bundled Landstrip package is
-licensed separately as `Apache-2.0 AND LGPL-2.1-or-later`.
+[Apache 2.0](../../LICENSE-APACHE-2.0).

package/api.ts CHANGED Viewed

@@ -6,6 +6,8 @@ import type { Readable, Writable } from 'node:stream';
 import type { ExtensionAPI, ExtensionContext } from '@earendil-works/pi-coding-agent';
+import { isRecord } from '@landstrip/landstrip/shared';
 export const LANDSTRIP_CONTEXT_ENV = 'LANDSTRIP_CONTEXT';
 export const LANDSTRIP_RUNTIME_VERSION = 2;
@@ -168,10 +170,6 @@ function eventBus(pi: ExtensionAPI): EventBusLike | undefined {
   return (pi as ExtensionAPI & { events?: EventBusLike }).events;
 }
-function isRecord(value: unknown): value is Record<string, unknown> {
-  return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function isRuntime(value: unknown): value is PiLandstripRuntimeV2 {
   return (
     isRecord(value) &&