safe-bash: make agentCommands portable by default with optional regexExecutor injection

[kamilio]

The complete /portable preset delivered by #649 makes the Worker integration possible. Please simplify the public API so that portability is the default and hosts inject a regex executor only when they need to override it. This is a follow-up API design request, not a claim that #649 is still unfixed.

The proposed public API is below; these names are a design request, not documentation of the current API:

agentCommands(); // Safe, bounded, environment-neutral default.
agentCommands({ regexExecutor: createBoundedRegexExecutor() }); // Optional override.
agentCommands({ regexExecutor: customExecutor }); // Host-supplied implementation.
agentCommands({ regexExecutor: createWorkerThreadRegexExecutor() }); // Explicit Node opt-in.

Shell, MemoryFileSystem, and agentCommands should be available from the ordinary package entry. The proposed createWorkerThreadRegexExecutor factory must come from a host-specific entry so importing the default API never loads Node worker threads. regexExecutor describes the dependency's job more clearly than the generic provider.

The current provider's createWorker factory and worker-shaped messaging protocol are a lower-level abstraction. A simpler public executor contract may require an adapter over that existing implementation; this is not just a rename of createWorker, and current provider and proposed executor types should not be treated as interchangeable. Keep the worker protocol internal where possible, with a documented bounded-execution and cancellation contract for custom executors.

agentCommands() should supply a built-in bounded, environment-neutral executor. Callers should not need to select a separate portable command preset and wire up an executor just to use the same command inventory in a Worker. A Node worker-thread executor can remain an explicit opt-in executor from a host-specific entry.

The dependency graph matters as much as the function signature: importing the default public entry must not eagerly load unavailable Node filesystem or worker-thread integrations. Merely choosing a portable executor after importing a Node-dependent root would leave the original startup problem intact. Keep Node filesystem adapters, Node execution, and other host runtimes behind explicit host-specific imports/options.

Please retain these constraints when designing the default:

• Preserve execution budgets, cancellation, bounded regex semantics, and explicit unsupported-mode errors. A synchronous native JavaScript RegExp fallback with only an outer timeout is not a bounded executor and must not become the portable default.
• Apply the same executor policy to every relevant command, including expr, egrep, and fgrep, rather than maintaining divergent command lists for different environments.
• Define ownership and disposal for both the default executor and an injected executor; avoid leaking resources or unexpectedly disposing an executor shared by its caller.
• Preserve existing Node behavior through an explicit opt-in implementation. Keep existing /portable consumers working through an alias or a documented migration. Any incompatible root-export or semantic change needs an explicit compatibility/versioning plan, not a silent refactor.
• Keep networking and host execution capabilities explicit opt-ins; portable-by-default must not enable previously unavailable host capabilities.

Acceptance: the ordinary agentCommands() import and representative workflows from the complete command inventory run in actual workerd and browser environments as well as Node/Bun; an injected executor is honored consistently; the explicit Node executor retains its supported behavior; limits, cancellation, unsupported modes, and cleanup have regression coverage. If a fully bounded built-in executor needs a restricted regex dialect or another dependency, document that tradeoff rather than weakening the guarantees.

This request is separate from #662's Bun/Miniflare test-host lifecycle issue. Our application can use the released /portable API in the meantime; no breaking upstream implementation is requested without the compatibility plan above.

[kamilio]

Integration finding in 0.1.470: importing Shell from @poe-platform/safe-bash/browser and portableAgentCommands/createBoundedRegexProvider from /portable registers all79 names but breaks nested env/xargs execution (internal error, exit1). Switching Shell to the same /portable entry fixes all three native-filesystem integration tests: printf /notes/report.txt | xargs cat, env NOTE=local env, and unknown executable refusal via printf hello | xargs node (correct exit127).

The separately bundled entries appear to maintain separate runtime context. Unifying the default entry would avoid this integration trap; meanwhile document that Shell and plugin/provider must originate from the same entry.

[kamilio]

Naming suggestion for the proposed API: prefer regexExecutor over the generic provider, since it tells callers what the dependency does. For example (proposed names, not the current API):

agentCommands(); // Safe, bounded, environment-neutral default.
agentCommands({ regexExecutor: createBoundedRegexExecutor() }); // Optional override.
agentCommands({ regexExecutor: createWorkerThreadRegexExecutor() }); // Explicit Node opt-in.

The Node factory should come from a host-specific entry so the default import remains portable. Custom executors should satisfy a documented bounded-execution/cancellation contract.

The current provider's createWorker factory and worker-shaped messaging protocol are a lower-level abstraction. A simpler public executor interface may need an adapter over that existing contract; this suggestion is not merely to rename createWorker or imply that current provider and executor types are interchangeable. Keep that worker protocol internal where possible, while retaining the ownership, disposal, limits, and compatibility requirements above.

[kamilio]

Validated against current built public entries: mixing the browser Shell with the portable preset reproduces the nested env/xargs failure (Expected owned command arguments); same-entry portable usage passes. The root cause is duplicated argument-carrier runtime identity across independent bundles, not a reason to weaken branding. A shared-runtime regression and fix are in progress. Separately, the existing bounded ERE provider can be reused for optional/default preset injection; no native-RegExp timeout fallback is being introduced.

Compatibility/versioning plan is recorded in docs/plans/issue-669-portable-default-api.md. Additive mixed-entry/default-argument fixes can ship first, but #669 stays open until the full request passes. The ordinary root switch changes exports and regex semantics, so it is planned for an explicit >=0.2.0 scoped boundary and a declared breaking poe-code/safe-bash release, retaining the old Node surface through /node and /portable as a same-runtime alias. Current portable bundles still contain Node crypto/compression/stream imports: those must be addressed and exercised in an actual browser, not hidden behind a successful workerd-only or polyfilled harness result. No breaking root switch has been published.

[kamilio]

Implementation notes from a code + real-workerd investigation (2026-09-08)

Owner confirmed: no API users, breaking changes are fine, and no major release is required — so this can be a straight refactor with no compatibility aliases or deprecation window. Verified everything below against current src and a real workerd harness (wrangler dev --local, wrangler 4.129.1, compatibility_flags = ["nodejs_compat"]).

The executor abstraction already exists — the default just points at the Node one

RegexExecutor in commands/regex-execution/portable.ts is the single executor class. Its constructor is (provider: BoundedRegexProvider, options), and provider.createWorker() returns a RegexWorker. Two providers exist today:

• createBoundedRegexProvider() (bounded-provider.ts) → returns a CooperativeWorker that runs in-thread, no node:worker_threads. This is the portable/bounded default we want.
• client.ts RegexExecutor extends PortableRegexExecutor and supplies a createWorker that spawns a node:worker_threads Worker. This is the Node opt-in.

So the executor injection point the issue asks for is already the provider argument. The work is renaming it to regexExecutor, giving it a default, and stopping the default graph from importing client.ts.

What forces node:worker_threads into the default graph (all default to the worker executor)

• plugins/index.ts:2,10-13 — createAgentCommands builds its four family executors with new RegexExecutor(options.regex) from client.js.
• commands/grep.ts:2,6 — grepCommands() → new RegexExecutor(options) (client).
• commands/search/rg.ts:2,7 — rgCommand() → new RegexExecutor(...) (client).
• commands/expr/index.ts:2,9 — createExprCommand() → new RegexExecutor(...) (client).

All four are re-exported from the main . entry via commands/index.js, so import { Shell } from "@poe-platform/safe-bash" statically pulls client.ts → node:worker_threads. Fixing only plugins/index.ts is insufficient; grep/rg/expr must switch too, which also satisfies the issue's "apply the same executor policy to expr/egrep/fgrep."

Proposed: each of the four factories defaults to options.regexExecutor ?? createBoundedRegexProvider() and constructs the portable RegexExecutor. Mirror plugins/portable.ts's sharing (one executor for grep/aliases/expr, a second for search only when search.regex differs). Add regexExecutor?: BoundedRegexProvider to AgentCommandsOptions (composition.ts:33).

Node worker-thread executor becomes an explicit opt-in

Extract the createWorker closure from client.ts into createWorkerThreadRegexProvider(): BoundedRegexProvider and expose it from a new host-only entry ./node (src/node.ts; ./node is currently free — only ./commands/node exists). Nothing in the default graph imports it. Usage: agentCommands({ regexExecutor: createWorkerThreadRegexProvider() }).

browser + portable entries collapse into the default

• Delete src/browser.ts (+ ./browser export) and src/portable.ts (+ ./portable export) and src/plugins/portable.ts. Once agentCommands() is portable, portableAgentCommands is exactly agentCommands() and createBrowserCommands (a hand-picked 28-command subset) is redundant.
• Consumers are the tests, not runtime code: ~14 test files import browserCommands/createBrowserCommands from src/browser.js, and tests/plugins/portable-agent.test.ts imports src/portable.js. They use the browser entry as a fast, in-thread command set. Repoint them to agentCommands() (now portable/in-thread, so still fast). The playground does not use browser.ts — it builds its own kernel from plugins/index.js via esbuild, so it's unaffected.

Two node: leaks still block a true zero-nodejs_compat bundle (separate from worker_threads)

Even with the executor fixed, createAgentCommands's graph pulls Node builtins from contracts/io.ts:5 (TransformStream from node:stream/web) and contracts/path.ts:2 (posix from node:path) — this is #671 — plus node:crypto (checksums), node:zlib (compression), node:stream (archive) from the byte/archive families. Under workerd + nodejs_compat these all resolve, and I ran the full command inventory (grep/sed/awk/jq/pipelines/find) on real workerd that way with the in-thread provider and it passed. A zero-nodejs_compat bundle additionally needs: global TransformStream in contracts/io.ts, a portable posix path in contracts/path.ts, Web Crypto for checksums, and a portable gzip/stream — larger, and worth splitting out. Recommend scoping #669 to "portable default that runs on workerd (with nodejs_compat) without worker_threads," and tracking the zero-builtin bundle separately (#671 + a new issue for crypto/zlib/stream).

expr regex-match interaction with #670

The bounded provider (bounded-provider.ts:92) accepts only grep/rg selection descriptors and rejects the expr match descriptor (only grep and fixed rg selection descriptors are supported). So making expr default to the bounded provider keeps expr 2 + 3 (arithmetic) working but makes expr STR : REGEX fail until #670 lands. Either land #670 first, or ship the portable default with expr-regex documented as unsupported (clear error, not a native-RegExp fallback) and close the gap in #670.

Suggested acceptance additions

• CI: bundle the default entry with esbuild --conditions=workerd and assert zero node: specifiers once the zero-builtin goal is in scope; until then assert no node:worker_threads.
• A real-workerd smoke test (the harness above) running representative commands with compatibility_flags = ["nodejs_compat"] and the default agentCommands().

[kamilio]

Additive milestone delivered and remote main verified at 00a9182: browser/portable share actual runtime identity; nested env/xargs works across entries; portableAgentCommands defaults to the bounded provider; explicit Node provider injection is available. #670 bounded expr matching is included and closed. Packed Node/Bun and actual workerd checks pass; no full zero-Node preset claim. This issue remains open for the revised default-entry/regexExecutor refactor. Following the direct priority request, #672 is next; its installed-artifact Node-import failure is reproduced, and an isolated low-level portable-codec proof passes 45/45 cases without whole-input accumulation. Release monitoring continues without blocking that work.

[kamilio]

Delivered and verified on remote main at fd9ba58. Ordinary agentCommands now supplies the full bounded portable preset with regexExecutor injection; explicit Node provider opt-in remains available. The revised no-alias migration is documented. Maintained full npm test and normal npm run build pass, as do lint, installed Node/Bun smoke, strict browser declarations without ambient Node types, and the real browser/playground smoke. Fresh offline-installed artifacts passed 29/29 actual workerd cases with compatibility_flags=[], including all 79 command names, nested env/xargs, limits, cancellation and borrowed-provider ownership. The final rebased product tree was verified identical to that artifact source before push. Detailed provenance and cleanup are in docs/plans/issue-672-workerd-validation.md. Closing after verified push as requested; publication is still being monitored separately and is not claimed complete.

[kamilio]

Publication check from the downstream integration: root Release 34276528644 for fd9ba58 succeeded on attempt 2, but the separate scoped-package run 34276528355 for that same commit is cancelled. npm @poe-platform/safe-bash still resolves latest to 0.1.497; its inspected runtime/declaration files remain byte-identical to 0.1.491 and still expose the old /portable/provider API. Thus the root release did not deliver the requested scoped package yet. Please complete the supported scoped publication so we can install and verify the new ordinary-root regexExecutor API. We are preserving the integration work and waiting for the published artifact rather than consuming unreleased internals.