@plurnk/plurnk-execs-common 3.0.1 → 3.0.2

package/README.md

@@ -1,9 +1,9 @@
 # @plurnk/plurnk-execs-common
 
-The **universal subprocess executor** for
-[plurnk-service](https://github.com/plurnk/plurnk-service)'s `exec` scheme. One
-package offers the shell, Node.js, and Python 3 by default, with other supported
-host interpreters available as opt-ins. Node is guaranteed; the rest are detected.
+The **subprocess executor** for
+[plurnk-service](https://github.com/plurnk/plurnk-service)'s runtime-tag execution (`sh`, `js`, `python3`). One
+package offers the shell, Node.js, and Python 3. Node is guaranteed; the rest
+are detected.
 
 A `@plurnk/plurnk-execs-*` sibling built on the [plurnk-execs](https://github.com/plurnk/plurnk-service/tree/main/plurnk-execs) framework.
 
@@ -11,69 +11,63 @@ A `@plurnk/plurnk-execs-*` sibling built on the [plurnk-execs](https://github.co
 
 The manifest claims the subprocess tags. Per-tag `probe()` reports Node
 unconditionally because the daemon already runs on it. A cheap `command -v`
-detects every other interpreter, so one executor adapts to the host.
-
-| Tag                              | Binary            | Inline body via                          |
-| -------------------------------- | ----------------- | ---------------------------------------- |
-| `sh` 🐚                          | sh                | `-c <body>`                              |
-| `node` ⬢                         | node              | `-e <body>` (always available)           |
-| `python3` 🐍                     | python3           | `-c <body>`                              |
-| `perl` 🐪 / `ruby` 💎 / `lua` 🌙 | perl / ruby / lua | `-e <body>`                              |
-| `deno` 🦕                        | deno              | `eval <body>`                            |
-| `bun` 🥟                         | bun               | `-e <body>`                              |
-| `tcl` 🪶                         | tclsh             | stdin                                    |
-| `bc` 🧮                          | bc                | stdin (for example, `6 * 7`)             |
-| `awk` 🪄                         | awk               | program arg, empty stdin (`BEGIN { … }`) |
+detects `sh` and `python3`, so one executor adapts to the host.
+
+| Tag          | Binary  | Inline body via                |
+| ------------ | ------- | ------------------------------ |
+| `sh` 🐚      | sh      | `-c <body>`                    |
+| `js` ⬢       | node    | `-e <body>` (always available) |
+| `python3` 🐍 | python3 | `-c <body>`                    |
 
 Each enabled runtime's catalog Summary includes a short executable inline body, with
 literal `\n` separators keeping the invocation on one discovery line.
 
-### A script — the `(target)` slot
+### The `(target)` slot — a script or working directory
 
-The table above is the **inline** form: the body is the program. A file in the
-`(target)` slot is instead the script each interpreter reads directly, and the
-body becomes that script's stdin. A `[{"cwd": "<directory>"}]` block on the heading
-selects the working directory. Script arguments use `[{"args": ["arg",...]}]`;
-each string is passed literally, without shell expansion ({§executor-metadata}).
-These options work for local, Worker, and Skill script targets alike.
+The table above is the **inline** form: the body is the program. A directory in
+the `(target)` slot selects the working directory for that inline program. A
+file in the `(target)` slot is instead the script each interpreter reads
+directly, and the body is tokenized by shell quoting (`tokenizeArgv`) into the
+script's arguments ({§executor-subprocess}, {§executor-contract}).
 
 ```sh (./deploy.sh)
-yes
-yes
-no
+--release "two words"
 ```
 
-```python3 (transform.py) [{"args": ["--format","json"]}]
-3
-1
-4
-1
-5
+```python3 (transform.py)
+--format json
 ```
 
-The first operation answers a shell script's prompts through stdin. The second
-feeds records to a Python script.
-
-All declared tags run host code, so every invocation is proposal-gated. The
-current installed in-process evaluators are jq and SQLite; their
-`pure` or `read` invocations bypass the proposal gate but still return through
-the same next-turn stream path ({§executor-effect}). Inline programs have no
-separate input channel; script targets receive stdin from the body.
+All declared tags run host code, so every invocation is proposal-gated ({§executor-results}). Inline programs have no
+separate input channel; script targets receive their arguments from the body.
 
 ## Configuration
 
-The shipped [`.env.defaults`](./.env.defaults) disables `perl`, `ruby`, `lua`,
-`deno`, `bun`, `tcl`, `bc`, and `awk`. To expose one, set its switch to `1`
-in the ordinary environment cascade and restart the service; commented opt-ins
-are in [`.env.example`](./.env.example). For example, `PLURNK_EXECS_PERL=1`
-enables the Perl executor when Perl is installed. These switches do not prevent
-calling an interpreter through `sh`.
-
 Per-tag kill-switches (`PLURNK_EXECS_<TAG>=0`) and the
 `PLURNK_EXECS_ONLY` allowlist are honored by framework discovery, uniformly
 across every extension ({§executor-policy}). A disabled tag is not registered and
 never reaches this executor.
 
+## Alignment with Node's permission framework
+
+Node's `--permission` model is natively conditional: unflagged `js` invocations run
+with normal Node semantics, while passing `--permission` flags through
+`NODE_OPTIONS` confines `js` child processes at access time (`ERR_ACCESS_DENIED`)
+without adding any PLURNK-specific knob or altering default behavior.
+
+| Step | Existing surface | Effect |
+| --- | --- | --- |
+| 1. Remove out-of-model interpreters | `PLURNK_EXECS_ONLY=js` | Unregisters `sh` and `python3` at discovery ({§executor-policy}); downstream layers cannot re-enable them. |
+| 2. Confine `js` children | `NODE_OPTIONS="--permission --allow-fs-read=<workspace> --allow-fs-write=<workspace>"` | Confines filesystem reads and writes to `<workspace>` and denies `child_process` spawning (`ERR_ACCESS_DENIED`). |
+| 3. Discover daemon envelope (optional) | `node --permission-audit ...` | Audits paths the daemon itself touches (run root, checkout, `node_modules`) before launching the daemon under `--permission`. |
+
+**Scope choices** ({§execution-output-identity}):
+
+- **Workspace scope** (`plurnk_env (add)` with `scope: "workspace"`): `NODE_OPTIONS` reaches both `js` execution children and Node-based MCP server subprocesses in the workspace.
+- **Session scope** (`plurnk_env (add)` with `scope: "session"`): `NODE_OPTIONS` reaches `js` execution children of that session only.
+
+**Honest ledger:** Node's permission model provides same-UID accident containment, not adversarial security boundaries. PLURNK owns authority, consent, and audit, and never claims containment; for OS-account separation, combine with `PLURNK_EXECS_SPAWN_USER` ({§executor-policy}) or an external container/VM sandbox.
+
 ## Tests
 
 `test:lint`, `test:unit`. Live-eval tests auto-skip where the interpreter is absent.

package/dist/Common.d.ts

@@ -1,6 +1,7 @@
+import { type RuntimeTag } from "@plurnk/plurnk-contracts";
 import { SubprocessExecutor } from "@plurnk/plurnk-execs";
 import type { RuntimeAvailability, SpawnArgs } from "@plurnk/plurnk-execs";
-export declare const RUNTIME_TAGS: readonly string[];
+export declare const RUNTIME_TAGS: readonly RuntimeTag[];
 export default class Common extends SubprocessExecutor {
     #private;
     protected spawnArgs(runtime: string, command: string, target?: string | null): SpawnArgs;

package/dist/Common.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Common.d.ts","sourceRoot":"","sources":["../src/Common.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,kBAAkB,EAAwB,MAAM,sBAAsB,CAAC;AAChF,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAmC3E,eAAO,MAAM,YAAY,EAAE,SAAS,MAAM,EAAwC,CAAC;AAenF,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,kBAAkB;;IAClD,UAAmB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,GAAG,SAAS,CActG;IAQc,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAOnD;CACJ"}
+{"version":3,"file":"Common.d.ts","sourceRoot":"","sources":["../src/Common.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,0BAA0B,CAAC;AAC1E,OAAO,EAAE,kBAAkB,EAAsC,MAAM,sBAAsB,CAAC;AAC9F,OAAO,KAAK,EAAE,mBAAmB,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AAmB3E,eAAO,MAAM,YAAY,EAAE,SAAS,UAAU,EAA8D,CAAC;AAK7G,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,kBAAkB;;IAClD,UAAmB,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,IAAW,GAAG,SAAS,CAUtG;IAQc,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAOnD;CACJ"}

package/dist/Common.js

@@ -1,53 +1,29 @@
 import { spawnSync } from "node:child_process";
-import { SubprocessExecutor, SpawnAccounts, Shell } from "@plurnk/plurnk-execs";
+import { isExecutionOp } from "@plurnk/plurnk-contracts";
+import { SubprocessExecutor, SpawnAccounts, Shell, tokenizeArgv } from "@plurnk/plurnk-execs";
 const RECIPES = Object.freeze({
-    // Subprocess floor. `sh`'s bin is the shell the environment names ({§executor-shell}), resolved at use.
+    // Subprocess floor. `sh`'s bin is the shell the environment names ({§executor-subprocess}), resolved at use.
     sh: { bin: "sh", arg: (c) => ["-c", c] },
-    node: { bin: "node", arg: (c) => ["-e", c], alwaysAvailable: true },
+    js: { bin: "node", arg: (c) => ["-e", c], alwaysAvailable: true },
     python3: { bin: "python3", arg: (c) => ["-c", c] },
-    // Detected host interpreters.
-    perl: { bin: "perl", arg: (c) => ["-e", c] },
-    ruby: { bin: "ruby", arg: (c) => ["-e", c] },
-    lua: { bin: "lua", arg: (c) => ["-e", c] },
-    deno: { bin: "deno", arg: (c) => ["eval", c] },
-    bun: { bin: "bun", arg: (c) => ["-e", c] },
-    tcl: { bin: "tclsh", stdin: true },
-    bc: { bin: "bc", stdin: true },
-    awk: { bin: "awk", bare: true, script: (target) => ["-f", target] },
 });
 // Exposed for tests / consumers wanting the candidate set.
-export const RUNTIME_TAGS = Object.freeze(Object.keys(RECIPES));
-// PATH presence via POSIX `command -v` — robust across interpreters that don't
-// support `--version` (tclsh, bc, some awks). bin is from the fixed table above.
-const onPath = (bin) => spawnSync("sh", ["-c", `command -v "$1"`, "sh", bin], { ...SpawnAccounts.options() }).status === 0; // {§executor-spawn-account}
-// Detection harness: one package claiming the common-REPL tags. probe() lights
-// up only the interpreters present on this host, so the consumer offers the
-// model exactly what the platform has — "plurnk supports the host's REPLs out
-// of the box". The operator kill-switch (PLURNK_EXECS_<tag>=0 / _ONLY) is no
-// longer honored here — framework discovery applies it uniformly across every
-// extension ({§executor-policy}), so a disabled tag never reaches probe(). All run
-// arbitrary code → effect `host` (inherited, proposal-gated). Reuses
-// SubprocessExecutor's run() (streaming + process-group abort) via spawnArgs().
+export const RUNTIME_TAGS = Object.freeze(Object.keys(RECIPES).filter(isExecutionOp));
+const onPath = (bin) => spawnSync("sh", ["-c", `command -v "$1"`, "sh", bin], { ...SpawnAccounts.options() }).status === 0; // {§executor-policy}
 export default class Common extends SubprocessExecutor {
     spawnArgs(runtime, command, target = null) {
         const r = Common.#recipe(runtime);
         if (r === undefined)
             throw new Error(`plurnk-execs-common received unclaimed runtime tag '${runtime}'`);
-        // With a target the program IS the target and the body is its stdin
-        // ({§executor-subprocess-routing}). The interpreter reads the file;
-        // no executable bit is consulted or changed.
+        // With a target the program IS the target and the body is its arguments,
+        // tokenized by shell quoting ({§executor-subprocess}, {§executor-contract}).
+        // The interpreter reads the file; no executable bit is consulted or changed.
         if (target !== null) {
-            return { cmd: r.bin, args: r.script?.(target) ?? [target], useShell: false, stdin: command };
+            return { cmd: r.bin, args: [target, ...tokenizeArgv(command)], useShell: false };
         }
-        // Trailing newline so line-oriented readers (bc, tclsh) evaluate the
-        // final line before EOF rather than erroring on an unterminated line.
-        if (r.stdin)
-            return { cmd: r.bin, args: [], useShell: false, stdin: `${command}\n` };
-        if (r.bare)
-            return { cmd: r.bin, args: [command], useShell: false, stdin: "" };
         return { cmd: r.bin, args: r.arg(command), useShell: false };
     }
-    // {§executor-shell} `sh` runs the environment's shell; every other recipe is fixed.
+    // {§executor-subprocess} `sh` runs the environment's shell; every other recipe is fixed.
     static #recipe(runtime) {
         const r = RECIPES[runtime];
         return runtime === "sh" && r !== undefined ? { ...r, bin: Shell.current().path } : r;

package/dist/Common.js.map

@@ -1 +1 @@
-{"version":3,"file":"Common.js","sourceRoot":"","sources":["../src/Common.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAC/C,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAmBhF,MAAM,OAAO,GAAqC,MAAM,CAAC,MAAM,CAAC;IAC5D,wGAAwG;IACxG,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE;IACxC,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE,eAAe,EAAE,IAAI,EAAE;IACnE,OAAO,EAAE,EAAE,GAAG,EAAE,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE;IAClD,8BAA8B;IAC9B,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE;IAC5C,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE;IAC5C,GAAG,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE;IAC1C,IAAI,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,EAAE;IAC9C,GAAG,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,EAAE;IAC1C,GAAG,EAAE,EAAE,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE;IAClC,EAAE,EAAE,EAAE,GAAG,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE;IAC9B,GAAG,EAAE,EAAE,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE;CACtE,CAAC,CAAC;AAEH,2DAA2D;AAC3D,MAAM,CAAC,MAAM,YAAY,GAAsB,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC;AAEnF,+EAA+E;AAC/E,iFAAiF;AACjF,MAAM,MAAM,GAAG,CAAC,GAAW,EAAW,EAAE,CACpC,SAAS,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,GAAG,CAAC,EAAE,EAAE,GAAG,aAAa,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,4BAA4B;AAEpI,+EAA+E;AAC/E,4EAA4E;AAC5E,8EAA8E;AAC9E,6EAA6E;AAC7E,8EAA8E;AAC9E,mFAAmF;AACnF,qEAAqE;AACrE,gFAAgF;AAChF,MAAM,CAAC,OAAO,OAAO,MAAO,SAAQ,kBAAkB;IAC/B,SAAS,CAAC,OAAe,EAAE,OAAe,EAAE,MAAM,GAAkB,IAAI;QACvF,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,uDAAuD,OAAO,GAAG,CAAC,CAAC;QACxG,oEAAoE;QACpE,oEAAoE;QACpE,6CAA6C;QAC7C,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;YAClB,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC;QACjG,CAAC;QACD,qEAAqE;QACrE,sEAAsE;QACtE,IAAI,CAAC,CAAC,KAAK;YAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,GAAG,OAAO,IAAI,EAAE,CAAC;QACrF,IAAI,CAAC,CAAC,IAAI;YAAE,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC;QAC/E,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,IAAI,EAAE,CAAC,CAAC,GAAI,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC;IAClE,CAAC;IAED,oFAAoF;IACpF,MAAM,CAAC,OAAO,CAAC,OAAe;QAC1B,MAAM,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;QAC3B,OAAO,OAAO,KAAK,IAAI,IAAI,CAAC,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACzF,CAAC;IAEQ,KAAK,CAAC,KAAK;QAChB,MAAM,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,KAAK,SAAS;YAAE,OAAO,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,oBAAoB,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QAC9F,IAAI,CAAC,CAAC,eAAe;YAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,KAAK,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;QACtG,OAAO,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC;YAChB,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,CAAC,GAAG,EAAE;YACpC,CAAC,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,GAAG,cAAc,EAAE,CAAC;IAC/D,CAAC;CACJ"}
+{"version":3,"file":"Common.js","sourceRoot":"","sources":["../src/Common.ts"],"names":[],"mappings":"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"}

package/dist/runtimes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtimes.d.ts","sourceRoot":"","sources":["../src/runtimes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AAsN/D,eAAO,MAAM,QAAQ,QAAO,WAAW,EAAoE,CAAC"}
+{"version":3,"file":"runtimes.d.ts","sourceRoot":"","sources":["../src/runtimes.ts"],"names":[],"mappings":"AAEA,OAAO,EAAS,KAAK,WAAW,EAAE,MAAM,sBAAsB,CAAC;AA8D/D,eAAO,MAAM,QAAQ,QAAO,WAAW,EAAoE,CAAC"}

package/dist/runtimes.js

@@ -1,16 +1,16 @@
-// {§executor-dynamic-runtimes} The common package's declarations. `sh` names the shell it runs
-// ({§executor-shell}), resolved on this host; every other declaration is fixed.
+// {§executor-discovery} The common package's declarations. `sh` names the shell it runs
+// ({§executor-subprocess}), resolved on this host; every other declaration is fixed.
 import { Shell } from "@plurnk/plurnk-execs";
 const SH = {
     name: "sh",
     glyph: "🐚",
     invocation: {
         body: {
-            role: "the shell program; stdin when the target is a script",
+            role: "the shell program; arguments when the target is a script",
             required: false,
         },
         target: {
-            role: "script; never a command or a directory",
+            role: "script, or working directory for an inline program",
             required: false,
             kind: "script",
         },
@@ -21,16 +21,16 @@ const SH = {
 };
 const FIXED = [
     {
-        name: "node",
+        name: "js",
         glyph: "⬢",
         summary: "Run JavaScript code or scripts with Node.js.",
         invocation: {
             body: {
-                role: "JavaScript program; stdin when the target is a script",
+                role: "JavaScript program; arguments when the target is a script",
                 required: false,
             },
             target: {
-                role: "script; never a command or a directory",
+                role: "script, or working directory for an inline program",
                 required: false,
                 kind: "script",
             },
@@ -45,11 +45,11 @@ const FIXED = [
         summary: "Run Python 3 code or scripts.",
         invocation: {
             body: {
-                role: "Python program; stdin when the target is a script",
+                role: "Python program; arguments when the target is a script",
                 required: false,
             },
             target: {
-                role: "script; never a command or a directory",
+                role: "script, or working directory for an inline program",
                 required: false,
                 kind: "script",
             },
@@ -58,158 +58,6 @@ const FIXED = [
             },
         },
     },
-    {
-        name: "perl",
-        glyph: "🐪",
-        summary: "Run Perl code or scripts.",
-        invocation: {
-            body: {
-                role: "Perl program; stdin when the target is a script",
-                required: false,
-            },
-            target: {
-                role: "script; never a command or a directory",
-                required: false,
-                kind: "script",
-            },
-            example: {
-                body: "print 42;",
-            },
-        },
-    },
-    {
-        name: "ruby",
-        glyph: "💎",
-        summary: "Run Ruby code or scripts.",
-        invocation: {
-            body: {
-                role: "Ruby program; stdin when the target is a script",
-                required: false,
-            },
-            target: {
-                role: "script; never a command or a directory",
-                required: false,
-                kind: "script",
-            },
-            example: {
-                body: "puts 42",
-            },
-        },
-    },
-    {
-        name: "lua",
-        glyph: "🌙",
-        summary: "Run Lua code or scripts.",
-        invocation: {
-            body: {
-                role: "Lua program; stdin when the target is a script",
-                required: false,
-            },
-            target: {
-                role: "script; never a command or a directory",
-                required: false,
-                kind: "script",
-            },
-            example: {
-                body: "print(42)",
-            },
-        },
-    },
-    {
-        name: "deno",
-        glyph: "🦕",
-        summary: "Run TypeScript or JavaScript code or scripts with Deno.",
-        invocation: {
-            body: {
-                role: "Deno program; stdin when the target is a script",
-                required: false,
-            },
-            target: {
-                role: "script; never a command or a directory",
-                required: false,
-                kind: "script",
-            },
-            example: {
-                body: "console.log(42)",
-            },
-        },
-    },
-    {
-        name: "bun",
-        glyph: "🥟",
-        summary: "Run TypeScript or JavaScript code or scripts with Bun.",
-        invocation: {
-            body: {
-                role: "Bun program; stdin when the target is a script",
-                required: false,
-            },
-            target: {
-                role: "script; never a command or a directory",
-                required: false,
-                kind: "script",
-            },
-            example: {
-                body: "console.log(42)",
-            },
-        },
-    },
-    {
-        name: "tcl",
-        glyph: "🪶",
-        summary: "Run Tcl code or scripts.",
-        invocation: {
-            body: {
-                role: "Tcl program; stdin when the target is a script",
-                required: false,
-            },
-            target: {
-                role: "script; never a command or a directory",
-                required: false,
-                kind: "script",
-            },
-            example: {
-                body: "puts 42",
-            },
-        },
-    },
-    {
-        name: "bc",
-        glyph: "🧮",
-        summary: "Evaluate calculations with bc.",
-        invocation: {
-            body: {
-                role: "bc program; stdin when the target is a script",
-                required: false,
-            },
-            target: {
-                role: "script; never a command or a directory",
-                required: false,
-                kind: "script",
-            },
-            example: {
-                body: "6 * 7",
-            },
-        },
-    },
-    {
-        name: "awk",
-        glyph: "🪄",
-        summary: "Run AWK code or scripts.",
-        invocation: {
-            body: {
-                role: "AWK program; stdin when the target is a script",
-                required: false,
-            },
-            target: {
-                role: "script; never a command or a directory",
-                required: false,
-                kind: "script",
-            },
-            example: {
-                body: "BEGIN { print 42 }",
-            },
-        },
-    },
 ];
 export const runtimes = () => [{ ...SH, summary: Shell.summary(Shell.current()) }, ...FIXED];
 //# sourceMappingURL=runtimes.js.map

package/dist/runtimes.js.map

@@ -1 +1 @@
-{"version":3,"file":"runtimes.js","sourceRoot":"","sources":["../src/runtimes.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,gFAAgF;AAChF,OAAO,EAAE,KAAK,EAAoB,MAAM,sBAAsB,CAAC;AAE/D,MAAM,EAAE,GAAiC;IACrC,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,UAAU,EAAE;QACR,IAAI,EAAE;YACF,IAAI,EAAE,sDAAsD;YAC5D,QAAQ,EAAE,KAAK;SAClB;QACD,MAAM,EAAE;YACJ,IAAI,EAAE,wCAAwC;YAC9C,QAAQ,EAAE,KAAK;YACf,IAAI,EAAE,QAAQ;SACjB;QACD,OAAO,EAAE;YACL,IAAI,EAAE,oBAAoB;SAC7B;KACJ;CACJ,CAAC;AAEF,MAAM,KAAK,GAA2B;IAClC;QACI,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,GAAG;QACV,OAAO,EAAE,8CAA8C;QACvD,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,uDAAuD;gBAC7D,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,iBAAiB;aAC1B;SACJ;KACJ;IACD;QACI,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,+BAA+B;QACxC,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,mDAAmD;gBACzD,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,WAAW;aACpB;SACJ;KACJ;IACD;QACI,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,2BAA2B;QACpC,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,iDAAiD;gBACvD,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,WAAW;aACpB;SACJ;KACJ;IACD;QACI,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,2BAA2B;QACpC,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,iDAAiD;gBACvD,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,SAAS;aAClB;SACJ;KACJ;IACD;QACI,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,0BAA0B;QACnC,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,gDAAgD;gBACtD,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,WAAW;aACpB;SACJ;KACJ;IACD;QACI,IAAI,EAAE,MAAM;QACZ,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,yDAAyD;QAClE,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,iDAAiD;gBACvD,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,iBAAiB;aAC1B;SACJ;KACJ;IACD;QACI,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,wDAAwD;QACjE,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,gDAAgD;gBACtD,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,iBAAiB;aAC1B;SACJ;KACJ;IACD;QACI,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,0BAA0B;QACnC,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,gDAAgD;gBACtD,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,SAAS;aAClB;SACJ;KACJ;IACD;QACI,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,gCAAgC;QACzC,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,+CAA+C;gBACrD,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,OAAO;aAChB;SACJ;KACJ;IACD;QACI,IAAI,EAAE,KAAK;QACX,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,0BAA0B;QACnC,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,gDAAgD;gBACtD,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,wCAAwC;gBAC9C,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,oBAAoB;aAC7B;SACJ;KACJ;CACJ,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAkB,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,CAAC,CAAC"}
+{"version":3,"file":"runtimes.js","sourceRoot":"","sources":["../src/runtimes.ts"],"names":[],"mappings":"AAAA,wFAAwF;AACxF,qFAAqF;AACrF,OAAO,EAAE,KAAK,EAAoB,MAAM,sBAAsB,CAAC;AAE/D,MAAM,EAAE,GAAiC;IACrC,IAAI,EAAE,IAAI;IACV,KAAK,EAAE,IAAI;IACX,UAAU,EAAE;QACR,IAAI,EAAE;YACF,IAAI,EAAE,0DAA0D;YAChE,QAAQ,EAAE,KAAK;SAClB;QACD,MAAM,EAAE;YACJ,IAAI,EAAE,oDAAoD;YAC1D,QAAQ,EAAE,KAAK;YACf,IAAI,EAAE,QAAQ;SACjB;QACD,OAAO,EAAE;YACL,IAAI,EAAE,oBAAoB;SAC7B;KACJ;CACJ,CAAC;AAEF,MAAM,KAAK,GAA2B;IAClC;QACI,IAAI,EAAE,IAAI;QACV,KAAK,EAAE,GAAG;QACV,OAAO,EAAE,8CAA8C;QACvD,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,2DAA2D;gBACjE,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,oDAAoD;gBAC1D,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,iBAAiB;aAC1B;SACJ;KACJ;IACD;QACI,IAAI,EAAE,SAAS;QACf,KAAK,EAAE,IAAI;QACX,OAAO,EAAE,+BAA+B;QACxC,UAAU,EAAE;YACR,IAAI,EAAE;gBACF,IAAI,EAAE,uDAAuD;gBAC7D,QAAQ,EAAE,KAAK;aAClB;YACD,MAAM,EAAE;gBACJ,IAAI,EAAE,oDAAoD;gBAC1D,QAAQ,EAAE,KAAK;gBACf,IAAI,EAAE,QAAQ;aACjB;YACD,OAAO,EAAE;gBACL,IAAI,EAAE,WAAW;aACpB;SACJ;KACJ;CACJ,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAAG,GAAkB,EAAE,CAAC,CAAC,EAAE,GAAG,EAAE,EAAE,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,GAAG,KAAK,CAAC,CAAC"}

package/docs/js.md

@@ -0,0 +1,18 @@
+# js
+
+A JavaScript snippet, run via `node -e`. Node is the daemon's own runtime, so it
+is always available (no PATH probe).
+
+```js <!-- the body is the snippet -->
+const os = require("node:os");
+console.log(JSON.stringify({ platform: os.platform(), cpus: os.cpus().length }));
+```
+
+`js (tool.js)` runs that JavaScript file and passes the body as its arguments
+(tokenized by shell quoting), also for `session://` and `skill://` targets.
+Relative imports resolve from the script; ordinary relative filesystem paths
+resolve from the working directory. Environment, working directory, channels,
+output on completion, exit status and lifetime are every subprocess executor's,
+as `plurnk:///sh.md` states. Stdout is text, so structured output is serialized
+(`console.log(JSON.stringify(value))`); a thrown error exits nonzero with its
+stack on stderr.

package/docs/python3.md

@@ -1,18 +1,17 @@
 # python3
 
-The body is Python code, run with `python3 -c`. A script target instead runs
-that file and receives the body as stdin; `[{"args": [...]}]` passes literal
-arguments and `[{"cwd": "<directory>"}]` selects the working directory, as for
-every interpreter (`sh.md`).
+The body is Python code, run with `python3 -c`. A directory in the `(target)`
+slot selects the working directory for that inline code. A script target instead
+runs that file and passes the body as its arguments (tokenized by shell
+quoting), as for every interpreter (`plurnk:///sh.md`).
 
 ```python3 <!-- the body is the program -->
 import json, sys
 print(json.dumps({"python": list(sys.version_info[:2])}))
 ```
 
-```python3 (tools/report.py) [{"args": ["--help"]}]
+```python3 (tools/report.py)
+--help
 ```
 
 Native skill files retain their sibling imports and source-relative assets.
-Live input (`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md`
-shows.

package/docs/sh.md

@@ -9,31 +9,27 @@ printf 'hello\n' > hello.txt
 wc -l hello.txt
 ```
 
-A script target runs that script: `sh (greet.sh)` runs it with an empty stdin;
-a nonempty body becomes its stdin. The interpreter reads the script directly,
-so it needs no executable bit; a script path authored inside a shell body still
-follows the kernel's ordinary executable-bit rules. Script arguments go in
-`[{"args": ["--release","two words"]}]`: each string is one literal argument,
-without shell expansion. The target is a program, never a command and never a
-directory; a target that is not a script is refused before anything runs. The
-same options apply to local, `worker://`, and `skill://` script targets across
-every interpreter.
+A script target runs that script: `sh (greet.sh)` runs it with no arguments;
+a nonempty body is tokenized by shell quoting and passed as its arguments
+(plain words split on whitespace, quoted arguments stay whole, nothing is
+expanded). The interpreter reads the script directly, so it needs no executable
+bit; a script path authored inside a shell body still follows the kernel's
+ordinary executable-bit rules. The same applies to local, `session://`, and
+`skill://` script targets across every interpreter.
 
 ## Environment
 
 The command receives a scoped environment: provider keys and every `PLURNK_*`
 setting are stripped before the child starts, so `printenv` cannot read
-plurnk's credentials, and the project's environment passes through.
-`[{"env": {"LC_ALL": "C"}}]` on the fence line sets variables for this run
-alone, over the entries in the `env` registry (`env.md`); plurnk's own names
-are refused by name.
+plurnk's credentials, and the project's environment passes through, overlaid
+with the `env` registry (`mcp:///plurnk_env.md`).
 
 ## Working directory
 
 The working directory is the workspace project root, or in a workspace without
-one the directory the shell would run in anyway. `[{"cwd": "<directory>"}]` on
-the fence line overrides it for its body; a receipt names the directory,
-relative to the project root, only when the command ran elsewhere.
+one the directory the shell would run in anyway. A directory in the `(target)`
+slot overrides it for an inline body (`sh (packages/api)`); a receipt names the
+directory, relative to the project root, only when the command ran elsewhere.
 
 ## Channels
 
@@ -67,10 +63,4 @@ npm test
 
 Expiry closes the stream with status 504. By contrast, `WAIT [30]` limits one
 wait to 30 seconds without stopping the command. Without `lifetime`,
-the command is loop-bound; see `env.md` for other lifetime values.
-
-## Live input
-
-`[{"stdin": "open"}]` keeps stdin open for later SENDs to the returned execution
-address; `[{"eof": true}]` closes it. The worked example, including newline
-framing, is on `node.md`.
+the command is loop-bound; see `mcp:///plurnk_env.md` for other `lifetime` values (`detached`, `turn`).

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plurnk/plurnk-execs-common",
-  "version": "3.0.1",
-  "description": "Universal subprocess executor for plurnk-service's exec scheme — one package exposing the shell, Node.js, Python 3, and supported host interpreters.",
+  "version": "3.0.2",
+  "description": "Subprocess executor for plurnk-service's exec scheme — exposing the shell, Node.js, and Python 3.",
   "keywords": [
     "plurnk",
     "exec",
@@ -10,7 +10,7 @@
     "subprocess",
     "repl",
     "shell",
-    "node",
+    "js",
     "python3"
   ],
   "homepage": "https://github.com/plurnk/plurnk-service/tree/main/plurnk-execs-common#readme",
@@ -49,13 +49,11 @@
   "files": [
     "dist/**/*",
     "README.md",
-    ".env.defaults",
-    ".env.example",
     "docs/**/*"
   ],
   "scripts": {
     "test:lint": "tsc --noEmit",
-    "test:unit": "node --conditions=plurnk-dev --env-file-if-exists=.env.defaults --env-file-if-exists=../plurnk-execs/.env.defaults --test ${PLURNK_TEST_CONCURRENCY:+--test-concurrency=$PLURNK_TEST_CONCURRENCY} \"src/**/*.test.ts\"",
+    "test:unit": "node --conditions=plurnk-dev --env-file-if-exists=../plurnk-execs/.env.defaults --experimental-test-coverage --test-coverage-include-all '--test-coverage-include=src/**' --test ${PLURNK_TEST_CONCURRENCY:+--test-concurrency=$PLURNK_TEST_CONCURRENCY} \"src/**/*.test.ts\"",
     "test": "npm run test:lint && npm run test:unit",
     "build:clean": "rm -rf dist",
     "build:dist": "tsc -p tsconfig.build.json",
@@ -64,7 +62,8 @@
     "prepublishOnly": "npm audit --audit-level=moderate && npm test"
   },
   "peerDependencies": {
+    "@plurnk/plurnk-contracts": "^7.0.0",
     "@plurnk/plurnk-execs": "^4.0.0"
   },
-  "gitHead": "d2647f7ec0d352b276714f22a93267aac04634b3"
+  "gitHead": "db65532b51408a2014f7ff53a288d834ff6694f2"
 }

package/.env.defaults

@@ -1,11 +0,0 @@
-# @plurnk/plurnk-execs-common — secondary interpreters are opt-in.
-# Set a runtime to 1 to register it; its interpreter must also be on PATH.
-# sh, node, and python3 remain enabled through the executor framework's default.
-PLURNK_EXECS_PERL=0
-PLURNK_EXECS_RUBY=0
-PLURNK_EXECS_LUA=0
-PLURNK_EXECS_DENO=0
-PLURNK_EXECS_BUN=0
-PLURNK_EXECS_TCL=0
-PLURNK_EXECS_BC=0
-PLURNK_EXECS_AWK=0

package/.env.example

@@ -1,13 +0,0 @@
-# @plurnk/plurnk-execs-common — environment
-
-# sh, node, and python3 are enabled when their interpreter is available.
-# Uncomment any optional runtime to enable it at the next service start.
-# An enabled runtime still requires its interpreter on PATH.
-# PLURNK_EXECS_PERL=1
-# PLURNK_EXECS_RUBY=1
-# PLURNK_EXECS_LUA=1
-# PLURNK_EXECS_DENO=1
-# PLURNK_EXECS_BUN=1
-# PLURNK_EXECS_TCL=1
-# PLURNK_EXECS_BC=1
-# PLURNK_EXECS_AWK=1

package/docs/awk.md

@@ -1,21 +0,0 @@
-# awk
-
-The body is the AWK program, passed as the one positional argument with an
-empty stdin: with no input file it only runs `BEGIN` blocks. Input files are
-named in `[{"args": [...]}]`; a script target runs that file and receives the
-body as stdin. Working directory, environment, channels and exit status are
-every subprocess executor's (`sh.md`); `exit 1` in the program is a nonzero `exitCode`.
-
-```awk [{"args": ["data.csv"]}] <!-- the body is the program -->
-BEGIN { FS = "," }
-NR > 1 { total += $3 }
-END { printf "rows=%d total=%.2f\n", NR - 1, total }
-```
-
-```awk (tools/summarize.awk) <!-- the script runs; the body is its stdin -->
-alpha,1
-beta,2
-```
-
-Live input (`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md`
-shows.

package/docs/bc.md

@@ -1,17 +0,0 @@
-# bc
-
-The body is a `bc` program fed on stdin (a trailing newline is added, so the
-last line evaluates). Arbitrary precision: `scale` is set before dividing, or
-every quotient is truncated to an integer.
-
-```bc <!-- the body is the program -->
-scale=6
-22/7
-2^64
-```
-
-Each expression prints its value on its own line to `#stdout`; `#stderr`
-carries parse errors such as `syntax error`, and the exit status is 0 even when
-a line failed to parse, so a missing result is explained on `#stderr`. A script
-target (`bc (rates.bc)`) runs that file with the body as stdin. Live input
-(`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md` shows.

package/docs/bun.md

@@ -1,18 +0,0 @@
-# bun
-
-The body is TypeScript or JavaScript, run with `bun -e`. A script target runs
-that file and receives the body as stdin; `[{"args": [...]}]` passes literal
-arguments, readable as `Bun.argv` or `process.argv`. Node is always present;
-bun only when the host has it.
-
-```bun <!-- the body is the program -->
-const file = Bun.file("package.json");
-console.log((await file.json()).name);
-```
-
-```bun (scripts/build.ts) [{"args": ["--watch=false"]}]
-```
-
-`console.log` streams to `#stdout`, `console.error` to `#stderr`; an uncaught
-error or `process.exit(1)` is a nonzero `exitCode`. Live input
-(`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md` shows.

package/docs/deno.md

@@ -1,19 +0,0 @@
-# deno
-
-The body is TypeScript or JavaScript, run with `deno eval` (permissions are
-Deno's defaults for `eval`; imports come from the project or a URL). A script
-target runs that file and receives the body as stdin; `[{"args": [...]}]` passes
-literal arguments, readable as `Deno.args`. Node is always present; deno only
-when the host has it.
-
-```deno <!-- the body is the program -->
-const versions: Record<string, string> = Deno.version;
-console.log(JSON.stringify(versions));
-```
-
-```deno (scripts/check.ts) [{"args": ["--strict"]}]
-```
-
-`console.log` streams to `#stdout`, `console.error` to `#stderr`; an uncaught
-error or `Deno.exit(1)` is a nonzero `exitCode`. Live input
-(`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md` shows.

package/docs/lua.md

@@ -1,20 +0,0 @@
-# lua
-
-The body is Lua code, run with `lua -e`. A script target runs that file and
-receives the body as stdin; `[{"args": [...]}]` passes literal script
-arguments, readable through the `arg` table.
-
-```lua <!-- the body is the program -->
-local t = { 3, 1, 2 }
-table.sort(t)
-print(table.concat(t, ","))
-```
-
-```lua (scripts/lint.lua) [{"args": ["src/main.lua"]}]
-```
-
-`print` streams to `#stdout`, `io.stderr:write` to `#stderr`; `error(...)` or
-`os.exit(1)` is a nonzero `exitCode`. The standalone interpreter is the host's
-`lua` on PATH; project modules resolve through its ordinary `package.path` from
-the working directory. Live input (`[{"stdin": "open"}]`, SEND,
-`[{"eof": true}]`) is as `node.md` shows.

package/docs/node.md

@@ -1,44 +0,0 @@
-# node
-
-A JavaScript snippet, run via `node -e`. Node is the daemon's own runtime, so it
-is always available (no PATH probe).
-
-```node <!-- the body is the snippet -->
-const os = require("node:os");
-console.log(JSON.stringify({ platform: os.platform(), cpus: os.cpus().length }));
-```
-
-`node (tool.js)` runs that JavaScript file and receives the body as stdin;
-`[{"args": ["--format","json"]}]` passes literal script arguments, also for
-`worker://` and `skill://` targets. Relative imports resolve from the script;
-ordinary relative filesystem paths resolve from the working directory.
-Environment, working directory, channels, output on completion, exit status and lifetime
-are every subprocess executor's, as `sh.md` states. Stdout is text, so structured
-output is serialized (`console.log(JSON.stringify(value))`); a thrown error
-exits nonzero with its stack on stderr.
-
-## Live input
-
-`[{"stdin": "open"}]` keeps stdin open for later SENDs to the receipt's execution
-address. Without it, initial input ends with EOF as usual.
-
-```node [{"stdin": "open"}]
-process.stdin.on("data", chunk => process.stdout.write(chunk));
-```
-
-Using the address returned by that invocation (here `node:///ab3d5678`):
-
-```SEND (node:///ab3d5678)
-hello
-
-```
-
-The blank line before the closing fence supplies a newline after `hello`.
-SEND adds no newline of its own. Its receipt acknowledges pipe delivery, not
-program completion. READ that same address to inspect stdout while it runs.
-
-```SEND (node:///ab3d5678) [{"eof": true}]
-```
-
-EOF closes stdin, not the process. KILL terminates the execution. Any worker
-in the workspace can send input to the same execution address.

package/docs/perl.md

@@ -1,19 +0,0 @@
-# perl
-
-The body is Perl code, run with `perl -e`; `-n`/`-p` have no equivalent here,
-so a line loop is written in the body. A script target runs that file and
-receives the body as stdin; `[{"args": [...]}]` passes literal arguments.
-Environment, channels and exit status are every subprocess executor's (`sh.md`):
-`die` or a nonzero `exit` is a nonzero `exitCode`.
-
-```perl <!-- the body is the program -->
-use strict; use warnings;
-my %count; $count{$_}++ for qw(a b a c a);
-printf "%s=%d\n", $_, $count{$_} for sort keys %count;
-```
-
-```perl (tools/rename.pl) [{"args": ["--dry-run"]}]
-```
-
-Live input (`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md`
-shows.

package/docs/ruby.md

@@ -1,20 +0,0 @@
-# ruby
-
-The body is Ruby code, run with `ruby -e`. A script target runs that file and
-receives the body as stdin; `[{"args": [...]}]` passes literal `ARGV` entries.
-
-```ruby <!-- the body is the program -->
-require "json"
-words = %w[alpha beta alpha]
-puts JSON.generate(words.tally)
-```
-
-```ruby (bin/migrate.rb) [{"args": ["--check"]}]
-```
-
-`puts` and `print` stream to `#stdout`, `warn` to `#stderr`; an unrescued
-exception or `exit 1` is a nonzero `exitCode` with the backtrace on stderr. Gems
-resolve from the project's ordinary Ruby environment; `[{"cwd": "<directory>"}]`
-selects the working directory when the project's `Gemfile` lives elsewhere.
-Environment metadata is every subprocess executor's (`sh.md`). Live input
-(`[{"stdin": "open"}]`, SEND, `[{"eof": true}]`) is as `node.md` shows.

package/docs/tcl.md

@@ -1,20 +0,0 @@
-# tcl
-
-The body is a Tcl script fed to `tclsh` on stdin (a trailing newline is added).
-A script target runs that file and receives the body as stdin;
-`[{"args": [...]}]` passes literal arguments, readable as `$argv`.
-
-```tcl <!-- the body is the program -->
-set words {alpha beta alpha}
-foreach w $words { dict incr count $w }
-puts [dict get $count alpha]
-```
-
-```tcl (tests/all.tcl) [{"args": ["-verbose","bps"]}]
-```
-
-`puts` streams to `#stdout`, `puts stderr ...` to `#stderr`; an uncaught error
-or `exit 1` is a nonzero `exitCode` with the Tcl error info on stderr. tclsh
-evaluates the script line by line, so an incomplete command at the end is an
-error, not a silent no-op. Live input (`[{"stdin": "open"}]`, SEND,
-`[{"eof": true}]`) is as `node.md` shows.