pi-landstrip 0.19.13 → 0.19.14

package/README.md

@@ -9,52 +9,38 @@ Requires Pi ≥0.82.0 and Node.js ≥22.19.0.
 pi install npm:pi-landstrip
 ```
 
-Includes native binaries for Linux, macOS, and Windows on x64 and Arm64.
-Enabled sandboxing fails closed if the binary or platform is unusable;
-`--no-sandbox` or `enabled: false` explicitly permits unsandboxed execution.
+Unusable sandboxing fails closed; `--no-sandbox` or `enabled: false` permits
+unsandboxed execution.
 
 ## Permissions and configuration
 
-Agent permissions govern tool dispatch, not sandbox access: approval never
-bypasses a sandbox hard denial. With sandboxing enabled, AI Bash, `!`, `!!`, and
-subagents use OS isolation. Primary file tools run in trusted Pi; setting
-`toolFilesystemPolicy: "sandbox"` applies filesystem policy checks, not OS isolation.
+With sandboxing enabled, Bash (`bash`, `!`, `!!`) and workers are OS-isolated.
+Primary file tools remain in trusted Pi; `toolFilesystemPolicy: "sandbox"`
+adds policy checks, not isolation. Tool approval never bypasses hard denials.
 
-Policy merges from bundled [`sandbox.json`](sandbox.json), then
-`~/.pi/agent/sandbox.json`, then trusted-project `.pi/sandbox.json`.
-Arrays combine; later scalar values win. Persistent sandbox approvals update
-the global or project file. Store only overrides:
+Configuration: bundled [`sandbox.json`](sandbox.json) → `~/.pi/agent/sandbox.json`
+→ trusted-project `.pi/sandbox.json`. Arrays combine; later scalars win.
+Persistent approvals update global/project overrides. For policy-only shell reads:
 
 ```json
-{
-  "shell": { "readAccess": "policy" },
-  "filesystem": { "allowWrite": ["."] },
-  "network": { "allowNetwork": false }
-}
+{ "shell": { "readAccess": "policy" } }
 ```
 
-The bundled shell default is `readAccess: "host"`; workers always use policy
-reads. Windows requires an explicit read allowlist. Native policy and CLI
-semantics are in [landstrip(1)](../landstrip/man/man1/landstrip.1).
-Runtime seccomp traps and query approval are Linux-only. On macOS, `--trap`
-reports setup/launch errors only and closes on successful exec.
-
-Worker read boundaries:
-
-- Bootstrap grants can override bundled `denyRead` defaults, never persisted
-  global or trusted-project denies. Denied startup resources prevent launch.
-  Legacy copies of `/home` or `/Users` count as explicit denies: remove them only
-  if unintended; bundled defaults remain. New global files start as `{}`.
-- `filesystem.denyReadAlways` cannot be overridden by equal/nested read grants
-  or shell host reads. Private workers protect parent auth-file and lock roots
-  with this policy and `denyWrite`. Non-empty `denyReadAlways` and private worker
-  auth are unsupported on Windows.
-- `filesystem.denyWriteAlways` cannot be overridden by equal/nested write grants
-  or interactive prompts; write attempts are silently rejected. Non-empty
-  `denyWriteAlways` is unsupported on Windows.
-- External skill, prompt, and theme directories may need explicit discovery
-  access. Prefer resource file paths: resolved-file grants do not cover enclosing
-  directories.
+Shell reads default to `"host"`; workers always use policy reads. See
+[landstrip(1)](../landstrip/man/man1/landstrip.1) for native policy, traps,
+and platform limits, including Windows read grants and hard-denial restrictions.
+
+Worker boundaries:
+
+- Bootstrap grants override bundled `denyRead`, never global/trusted-project
+  denies. Denied startup resources prevent launch. Legacy `/home` or `/Users`
+  denies are explicit overrides; remove them only if unintended.
+- Hard read denials also apply to shell host reads. Private workers protect
+  parent auth-file/lock roots with `denyReadAlways` and `denyWrite`;
+  private worker authentication is unsupported on Windows.
+- `filesystem.denyWriteAlways` rejects write attempts without prompting.
+- External skills/prompts/themes may need directory discovery grants;
+  resolved-file grants do not include parent directories.
 
 ## Agents and tasks
 
@@ -69,49 +55,43 @@ Configure `~/.pi/agent/landstrip.json`, trusted-project `.pi/landstrip.json`, or
 }
 ```
 
-`maxSubagents` accepts 0–16. Agent definitions can override model, prompt, mode,
-options, and permissions.
+`maxSubagents`: 0–16. Agent definitions can override model, prompt, mode, options,
+and permissions.
 
-`/landstrip` opens the management pane; `/landstrip help` lists commands and
-shortcuts. Common commands:
+Use `/landstrip` for the management pane and `/landstrip help` for commands.
+Task IDs accept unique prefixes; bare IDs open logs. `/landstrip tasks kill <id>`
+terminates a task. `Ctrl+Shift+A` cycles primary agents while idle.
+The `task` tool accepts `background: true` for immediate return and `task_id`
+to continue a saved task. Press `Enter` in running/queued logs to steer workers.
 
-| Command                           | Action                          |
-| --------------------------------- | ------------------------------- |
-| `/landstrip status`               | Inspect sandbox, agents, tasks. |
-| `/landstrip settings`             | Set concurrency/file policy.    |
-| `/landstrip sandbox [on\|off]`    | Inspect/toggle OS isolation.    |
-| `/landstrip agents [@name]`       | List/select primary agents.     |
-| `/landstrip subagents`            | List process subagents.         |
-| `/landstrip tasks [list]`         | List task sessions.             |
-| `/landstrip tasks kill <task-id>` | Terminate a task.               |
-| `/landstrip logs [task-id]`       | Open task logs.                 |
+### Worker environment and authentication
 
-Task IDs accept unique prefixes; bare IDs open logs in the pane.
-`Ctrl+Shift+A` cycles primary agents while Pi is idle. The `task` tool accepts
-`background: true` for immediate return and `task_id` to continue a saved task.
-Press `Enter` in running/queued task logs to steer the worker.
+Workers start `--offline`; install resources and refresh model catalogs in the
+parent first. Provider endpoints still need network permission.
 
-### Worker environment and authentication
+Only runtime paths, locale, certificate paths, and supported Pi config are
+inherited—not parent API keys, tool tokens, proxy URLs, or arbitrary variables.
+The parent refreshes selected-provider auth and sends it, along with selected
+Bedrock/Vertex/Azure settings, over a private Unix pipe, not arguments or
+environment. Configure tool logins separately; authenticated workers cannot
+launch on Windows.
 
-Workers start `--offline`: install resources and refresh model catalogs in the
-parent first. Model/auth requests still need permitted endpoints.
+Ambient AWS profiles need an explicit region for non-ARN Bedrock models.
+Custom credential-chain environment paths are unsupported; use scoped keys or
+a Bedrock bearer token. Provider credential files need filesystem grants.
 
-Workers inherit only runtime paths, locale, certificate paths, and supported Pi
-configuration—not parent API keys, tool tokens, proxy URLs, or arbitrary variables.
-The parent refreshes selected-provider auth and sends it through a private Unix
-pipe, never arguments or worker environment. Environment-based tool logins need
-separate configuration; authenticated workers fail before spawning on Windows.
+## Extension API
 
-Selected Bedrock, Vertex, and Azure settings also travel privately. Ambient AWS
-profiles need an explicit region for non-ARN models; custom credential-chain
-environment paths are unsupported (use scoped keys or a Bedrock bearer token).
-Provider credential files still need filesystem permission.
+[`pi-landstrip/api`](api.ts) exports `createLandstrip`. `prepareProcess()` returns
+`undefined` without a runtime. Dispose prepared processes separately from the
+discovery handle; generic `spawn()` returns `ChildProcess`, RPC workers use
+piped streams.
 
 ## Development
 
-From this package: `npm ci`, then `npm run all` (format, lint, typecheck, build,
-and tests; building requires Bun). For a read-only formatting check: `npm run ci:fmt`.
+From this package: `npm ci && npm run all` (Bun required).
+`npm run ci:fmt` checks formatting without edits.
 
 ## License
 
-Apache-2.0; see [LICENSE](LICENSE).
+[Apache-2.0](LICENSE).

package/api.ts

@@ -105,6 +105,11 @@ export interface LandstripPreparedProcess {
   dispose(): Promise<void>;
 }
 
+export interface Landstrip {
+  prepareProcess(options: LandstripProcessOptions): Promise<LandstripPreparedProcess | undefined>;
+  dispose(): void;
+}
+
 export interface LandstripRpcChildProcess {
   readonly stdin: Writable;
   readonly stdout: Readable;
@@ -126,7 +131,7 @@ export type LandstripSpawn = (
   command: string,
   args: readonly string[],
   options: SpawnOptions,
-) => ChildProcess | LandstripRpcChildProcess;
+) => ChildProcess;
 
 export type LandstripEvent =
   | { readonly type: 'sandbox.changed'; readonly context: LandstripContextV2 }
@@ -184,35 +189,152 @@ function isRuntime(value: unknown): value is PiLandstripRuntimeV2 {
   );
 }
 
-export function useLandstrip(
+function isDisposableProcess(value: unknown): value is Pick<LandstripPreparedProcess, 'dispose'> {
+  return isRecord(value) && typeof value.dispose === 'function';
+}
+
+function isPreparedProcess(value: unknown): value is LandstripPreparedProcess {
+  return (
+    isRecord(value) &&
+    typeof value.command === 'string' &&
+    value.command.trim().length > 0 &&
+    Array.isArray(value.args) &&
+    [...value.args].every((arg: unknown) => typeof arg === 'string') &&
+    typeof value.cwd === 'string' &&
+    value.cwd.length > 0 &&
+    isRecord(value.env) &&
+    Object.values(value.env).every((entry) => entry === undefined || typeof entry === 'string') &&
+    typeof value.spawn === 'function' &&
+    isDisposableProcess(value)
+  );
+}
+
+function discoverLandstrip(
   pi: ExtensionAPI,
   callback: (runtime: PiLandstripRuntimeV2) => void,
+  onInvalid?: (error: Error) => void,
 ): () => void {
   const events = eventBus(pi);
   if (!events) return () => undefined;
 
   let current: PiLandstripRuntimeV2 | undefined;
-  const register = (runtime: PiLandstripRuntimeV2): void => {
-    if (runtime === current) return;
-    current = runtime;
-    callback(runtime);
+  let disposed = false;
+  const register = (value: unknown): void => {
+    if (disposed) return;
+    if (!isRuntime(value)) {
+      onInvalid?.(new Error('Invalid Landstrip runtime v2 declaration'));
+      return;
+    }
+    if (value === current) return;
+    current = value;
+    callback(value);
   };
   const unsubscribe = events.on(RUNTIME_REGISTER_EVENT, (value) => {
-    if (!isRecord(value) || value.version !== LANDSTRIP_RUNTIME_VERSION) return;
-    if (isRuntime(value.runtime)) register(value.runtime);
+    if (disposed) return;
+    if (!isRecord(value) || value.version !== LANDSTRIP_RUNTIME_VERSION) {
+      onInvalid?.(new Error('Invalid Landstrip runtime v2 registration'));
+      return;
+    }
+    register(value.runtime);
   });
+  const dispose = (): void => {
+    if (disposed) return;
+    disposed = true;
+    unsubscribe();
+  };
   try {
     events.emit(RUNTIME_DISCOVER_EVENT, {
       version: LANDSTRIP_RUNTIME_VERSION,
       register,
     } satisfies RuntimeDiscovery);
-    return unsubscribe;
+    return dispose;
   } catch (error) {
-    unsubscribe();
+    dispose();
     throw error;
   }
 }
 
+export function useLandstrip(
+  pi: ExtensionAPI,
+  callback: (runtime: PiLandstripRuntimeV2) => void,
+): () => void {
+  return discoverLandstrip(pi, callback);
+}
+
+export function createLandstrip(pi: ExtensionAPI): Landstrip {
+  let runtime: PiLandstripRuntimeV2 | undefined;
+  let runtimeError: Error | undefined;
+  let disposed = false;
+  const stopDiscovery = discoverLandstrip(
+    pi,
+    (value) => {
+      runtime = value;
+    },
+    (error) => {
+      runtimeError ??= error;
+    },
+  );
+  if (runtimeError) {
+    stopDiscovery();
+    throw runtimeError;
+  }
+
+  return {
+    async prepareProcess(options) {
+      if (disposed) throw new Error('Landstrip handle has been disposed');
+      if (runtimeError) throw runtimeError;
+      options.signal?.throwIfAborted();
+      if (!runtime) return undefined;
+
+      const prepared: unknown = await runtime.prepareProcess(options);
+      if (!isDisposableProcess(prepared)) {
+        throw new Error('Landstrip returned a process without a disposal method');
+      }
+      let disposePromise: Promise<void> | undefined;
+      const dispose = (): Promise<void> => {
+        disposePromise ??= Promise.resolve().then(() => prepared.dispose());
+        return disposePromise;
+      };
+      try {
+        options.signal?.throwIfAborted();
+        if (disposed) throw new Error('Landstrip handle has been disposed');
+        if (runtimeError) throw runtimeError;
+        if (!isPreparedProcess(prepared)) {
+          throw new Error('Landstrip returned an invalid prepared process');
+        }
+      } catch (error) {
+        try {
+          await dispose();
+        } catch (cleanupError) {
+          throw new AggregateError(
+            [error, cleanupError],
+            'Landstrip process preparation cleanup failed',
+          );
+        }
+        throw error;
+      }
+
+      return {
+        command: prepared.command,
+        args: prepared.args,
+        cwd: prepared.cwd,
+        env: prepared.env,
+        spawn(command, args, spawnOptions) {
+          if (disposePromise) throw new Error('Prepared Landstrip process has been disposed');
+          return prepared.spawn(command, args, spawnOptions);
+        },
+        dispose,
+      };
+    },
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      stopDiscovery();
+      runtime = undefined;
+    },
+  };
+}
+
 function provideExtensionProvider(
   pi: ExtensionAPI,
   register: (runtime: PiLandstripRuntimeV2) => () => void,
@@ -283,7 +405,8 @@ export function contextFromEnvironment(
       value.version !== LANDSTRIP_RUNTIME_VERSION ||
       value.host !== 'pi' ||
       value.role !== 'subagent' ||
-      !['enabled', 'disabled', 'unavailable'].includes(String(value.sandbox)) ||
+      typeof value.sandbox !== 'string' ||
+      !['enabled', 'disabled', 'unavailable'].includes(value.sandbox) ||
       typeof value.cwd !== 'string' ||
       !Number.isInteger(value.depth) ||
       (value.depth as number) < 0 ||

package/dist/index.ts

@@ -6029,7 +6029,7 @@ function createLandstripIntegrationWithPrompts(options, permissionPrompts) {
     if (!provider)
       return { decision: "abstain" };
     const result = await provider.decide(request);
-    if (typeof result !== "object" || result === null || !("decision" in result) || !["allow", "deny", "abstain"].includes(String(result.decision)) || "reason" in result && result.reason !== undefined && typeof result.reason !== "string") {
+    if (typeof result !== "object" || result === null || !("decision" in result) || typeof result.decision !== "string" || !["allow", "deny", "abstain"].includes(result.decision) || "reason" in result && result.reason !== undefined && typeof result.reason !== "string") {
       throw new Error(`Permission ask provider "${provider.id}" returned an invalid decision`);
     }
     return result;
@@ -6390,7 +6390,7 @@ ${paths}${note}`, PERMISSION_OPTIONS, promptSignal);
       }
     });
   }
-  function prepareUnsandboxedRpcWorker(options) {
+  function prepareUnsandboxedProcess(options) {
     let spawned = false;
     let disposed = false;
     let disposePromise;
@@ -6426,7 +6426,7 @@ ${paths}${note}`, PERMISSION_OPTIONS, promptSignal);
       }
     };
   }
-  async function prepareRpcWorker(options) {
+  async function prepareManagedProcess(options) {
     if (options.signal?.aborted)
       throw new Error("Task cancelled");
     if (!ensureSandboxState(options.ctx)) {
@@ -6437,7 +6437,7 @@ ${paths}${note}`, PERMISSION_OPTIONS, promptSignal);
         warnUnsandboxed(options.ctx, "Subagent processes are running without Landstrip sandboxing", "warning");
         unsandboxedWorkerWarningShown = true;
       }
-      return prepareUnsandboxedRpcWorker(options);
+      return prepareUnsandboxedProcess(options);
     }
     const allowances = {
       permissionPromptLabel: options.permissionPromptLabel,
@@ -6475,7 +6475,28 @@ ${paths}${note}`, PERMISSION_OPTIONS, promptSignal);
     let policy;
     let trapSocket;
     let childEnd;
+    let preparedChild;
     let disposed = false;
+    const cleanup = async () => {
+      const errors = [];
+      for (const release of [
+        () => stopPreparedChild(preparedChild),
+        () => trapSocket?.destroy(),
+        () => childEnd?.destroy(),
+        () => {
+          if (policy)
+            rmSync2(policy.dir, { recursive: true, force: true });
+        },
+        () => proxy?.stop()
+      ]) {
+        try {
+          await release();
+        } catch (error) {
+          errors.push(error);
+        }
+      }
+      return errors;
+    };
     try {
       if (options.signal?.aborted)
         throw new Error("Task cancelled");
@@ -6487,20 +6508,17 @@ ${paths}${note}`, PERMISSION_OPTIONS, promptSignal);
         attachWorkerTrap(trapSocket, options.ctx, options.cwd, processAllowances, options.signal);
       }
     } catch (error) {
-      trapSocket?.destroy();
-      childEnd?.destroy();
-      if (policy)
-        rmSync2(policy.dir, { recursive: true, force: true });
-      await proxy?.stop();
+      const cleanupErrors = await cleanup();
+      if (cleanupErrors.length > 0) {
+        throw new AggregateError([error, ...cleanupErrors], "Landstrip process preparation cleanup failed");
+      }
       throw error;
     }
     const workerPolicy = policy;
-    const workerTrapSocket = trapSocket;
     const workerChildEnd = childEnd;
     const workerEnv = createProxyEnvironment(proxy?.port ?? null, proxyToken, options.env ?? {});
     let spawned = false;
     let disposePromise;
-    let preparedChild;
     const spawnWorker = (_command, _args, spawnOptions) => {
       if (disposed)
         throw new Error("Prepared process has been disposed");
@@ -6535,9 +6553,9 @@ ${paths}${note}`, PERMISSION_OPTIONS, promptSignal);
         detached: true,
         stdio
       });
-      workerChildEnd?.destroy();
-      patchProcessGroupKill(child);
       preparedChild = child;
+      patchProcessGroupKill(child);
+      workerChildEnd?.destroy();
       return child;
     };
     return {
@@ -6549,21 +6567,29 @@ ${paths}${note}`, PERMISSION_OPTIONS, promptSignal);
       dispose() {
         disposePromise ??= (async () => {
           disposed = true;
-          await stopPreparedChild(preparedChild);
-          workerTrapSocket?.destroy();
-          workerChildEnd?.destroy();
-          rmSync2(workerPolicy.dir, { recursive: true, force: true });
-          await proxy?.stop();
+          const cleanupErrors = await cleanup();
+          if (cleanupErrors.length > 0) {
+            throw new AggregateError(cleanupErrors, "Landstrip process disposal cleanup failed");
+          }
         })();
         return disposePromise;
       }
     };
   }
+  async function prepareRpcWorker(options) {
+    const prepared = await prepareManagedProcess(options);
+    return {
+      ...prepared,
+      spawn(command, args, spawnOptions) {
+        return prepared.spawn(command, args, spawnOptions);
+      }
+    };
+  }
   async function prepareProcess(options) {
     if (process.platform === "win32" && (getNoSandboxFlag() || !loadConfig(options.cwd).enabled)) {
       throw new Error("Generic process preparation requires sandboxing on Windows");
     }
-    return prepareRpcWorker({
+    return prepareManagedProcess({
       ...options,
       env: options.env ?? process.env,
       readPaths: options.readPaths ?? [],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-landstrip",
-  "version": "0.19.13",
+  "version": "0.19.14",
   "description": "Sandboxed Bash and process-backed agents for Pi",
   "keywords": [
     "landstrip",
@@ -39,7 +39,7 @@
     "ci:test": "npm run test"
   },
   "dependencies": {
-    "@landstrip/landstrip-api": "^0.19.13",
+    "@landstrip/landstrip-api": "^0.19.14",
     "jsonc-parser": "^3.3.1",
     "minimatch": "^10.2.5",
     "undici": "^8.9.0",