@plurnk/plurnk-execs-common 3.0.2 → 3.0.3

package/README.md

@@ -30,12 +30,12 @@ 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)
---release "two words"
+```ts
+await plurnk.sh({ script: "./deploy.sh", args: '--release "two words"' });
 ```
 
-```python3 (transform.py)
---format json
+```ts
+await plurnk.python3({ script: "transform.py", args: "--format json" });
 ```
 
 All declared tags run host code, so every invocation is proposal-gated ({§executor-results}). Inline programs have no
@@ -63,8 +63,8 @@ without adding any PLURNK-specific knob or altering default behavior.
 
 **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.
+- **Workspace scope** (`plurnk.env` with `scope: "workspace"`): `NODE_OPTIONS` reaches both `js` execution children and Node-based MCP server subprocesses in the workspace.
+- **Session scope** (`plurnk.env` 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.
 

package/docs/js.md

@@ -3,16 +3,13 @@
 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 }));
-```
+await plurnk.js({ code: "const os = require(\"node:os\");\nconsole.log(JSON.stringify({ platform: os.platform(), cpus: os.cpus().length }));" }); // the code is the snippet
 
-`js (tool.js)` runs that JavaScript file and passes the body as its arguments
-(tokenized by shell quoting), also for `session://` and `skill://` targets.
+`await plurnk.js({ script: "tool.js", args: ["--flag"] });` runs that JavaScript file and passes `args` as its arguments,
+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
+output on completion, and exit status are every subprocess executor's,
+as `mcp:///plurnk/sh.json` 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,17 +1,11 @@
 # python3
 
-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`).
+The `code` is Python code, run with `python3 -c`. Setting `cwd` selects the
+working directory for that inline code. A `script` instead runs that file and
+passes `args` as its arguments, as for every interpreter (`mcp:///plurnk/sh.json`).
 
-```python3 <!-- the body is the program -->
-import json, sys
-print(json.dumps({"python": list(sys.version_info[:2])}))
-```
+await plurnk.python3({ code: "import json, sys\nprint(json.dumps({\"python\": list(sys.version_info[:2])}))" }); // the code is the program
 
-```python3 (tools/report.py)
---help
-```
+await plurnk.python3({ script: "tools/report.py", args: ["--help"] });
 
 Native skill files retain their sibling imports and source-relative assets.

package/docs/sh.md

@@ -1,19 +1,16 @@
 # sh
 
-The `sh` fence runs the body with `-c` in the shell its summary names: the
-environment's `$SHELL`, or `/bin/sh` when that names no executable file. The body
+`plurnk.sh` runs the `command` with `-c` in the shell its summary names: the
+environment's `$SHELL`, or `/bin/sh` when that names no executable file. The command
 reaches it character-perfect, whitespace included; write for that shell.
 
-```sh <!-- the body is the script itself -->
-printf 'hello\n' > hello.txt
-wc -l hello.txt
-```
+await plurnk.sh({ command: "printf 'hello\\n' > hello.txt\nwc -l hello.txt" }); // the command is the script itself
 
-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
+A `script` runs that script: `await plurnk.sh({ script: "greet.sh" });` runs it with no arguments;
+`args` (an array of argument strings or a shell-quoted string) is 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
+bit; a script path authored inside a shell `command` still follows the kernel's
 ordinary executable-bit rules. The same applies to local, `session://`, and
 `skill://` script targets across every interpreter.
 
@@ -22,13 +19,13 @@ ordinary executable-bit rules. The same applies to local, `session://`, and
 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, overlaid
-with the `env` registry (`mcp:///plurnk_env.md`).
+with the `env` registry (`mcp:///plurnk/env.json`).
 
 ## Working directory
 
 The working directory is the workspace project root, or in a workspace without
-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
+one the directory the shell would run in anyway. Setting `cwd` overrides it for
+an inline command (`await plurnk.sh({ command: "npm test", cwd: "packages/api" });`); a receipt names the
 directory, relative to the project root, only when the command ran elsewhere.
 
 ## Channels
@@ -37,13 +34,12 @@ An execution is a host effect, subject to approval. Output streams
 under the receipt's `stream` address, such as `sh:///ab3d5678`: `#stdout` is
 the default channel and `#stderr` the second; both are `text/stream`. While it
 runs, the packet's `## Open Work` streams list reports each channel's size and
-growth, and READ can inspect any range. On completion, the harness adds one
-`_plurnk` READ per channel: the whole output when it fits the context budget,
+growth, and `plurnk.read` can inspect any range. On completion, the harness adds one
+`_plurnk` `read` per channel: the whole output when it fits the context budget,
 otherwise a bodiless receipt naming its size, with the `range` extent and the
-terminal exit status. READ a range of the observation's `path` for any part:
+terminal exit status. Read a range of the observation's `path` for any part:
 
-```READ (sh:///ab3d5678#stdout) <17,40>
-```
+await plurnk.read({ path: "sh:///ab3d5678#stdout", range: "17,40" });
 
 The observation carries the `exitCode`; a nonzero one is the command's answer,
 not a failure. Stdout and stderr are separate channels,
@@ -51,16 +47,3 @@ and a diagnostic may be on either. The `log:///…/sh` receipt's own body is the
 program exactly as sent, never output. A receipt with a non-200 status and no
 `stream` address ran nothing; its body is still the program, and its Problem
 says why it was refused.
-
-## Lifetime
-
-The heading's `lifetime` metadata bounds the command's total runtime, not idle
-time. This command is stopped after 30 seconds if it has not finished:
-
-```sh [{"lifetime": "30s"}]
-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 `mcp:///plurnk_env.md` for other `lifetime` values (`detached`, `turn`).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plurnk/plurnk-execs-common",
-  "version": "3.0.2",
+  "version": "3.0.3",
   "description": "Subprocess executor for plurnk-service's exec scheme — exposing the shell, Node.js, and Python 3.",
   "keywords": [
     "plurnk",
@@ -65,5 +65,5 @@
     "@plurnk/plurnk-contracts": "^7.0.0",
     "@plurnk/plurnk-execs": "^4.0.0"
   },
-  "gitHead": "db65532b51408a2014f7ff53a288d834ff6694f2"
+  "gitHead": "9d234b81e14a1d3fe88b9be3f7c643a0eb929533"
 }