@plurnk/plurnk-execs-common 1.17.0 → 1.19.0

package/docs/awk.md

@@ -24,3 +24,7 @@ Output goes to `#stdout`, diagnostics to `#stderr`; `exit 1` in the program
 closes with status 500. `[{"cwd": "<directory>"}]` selects the working directory
 for relative file arguments. AWK is the right tool for column arithmetic and
 line reshaping over text; for JSON use `jq`, for anything else `node` or `sh`.
+
+`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
+alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
+(`PLURNK_*`, provider credentials) are refused by name.

package/docs/bc.md

@@ -17,6 +17,6 @@ scale=6
 Each expression prints its value on its own line to `#stdout`; `#stderr`
 carries parse errors such as `syntax error`. The exit status is 0 even when
 a line failed to parse, so read `#stderr` when a result is missing. A script
-target (````` ````bc (rates.bc) `````) runs that file with the body as stdin.
+target (`bc (rates.bc)`) runs that file with the body as stdin.
 Use bc for exact decimal or big-integer arithmetic; for anything with strings,
 loops over data, or JSON, reach for `awk`, `node`, or `sh`.

package/docs/node.md

@@ -53,8 +53,12 @@ it, never output; a non-200 receipt with no `stream` address ran nothing.
 Runs in the workspace project root by default, or the daemon's own cwd in a
 workspace without one; a `[{"cwd": "<directory>"}]` block on the opening fence line selects
 another. The target is a script, never a command or a directory:
-````` ````node (tool.js) ````` runs that JavaScript file and receives the body as
+`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 cwd. The receipt names cwd
 when it differs from the project root.
+
+`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
+alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
+(`PLURNK_*`, provider credentials) are refused by name.

package/docs/python3.md

@@ -20,3 +20,7 @@ Each argument is a literal string, without shell expansion. `[{"cwd": "<director
 selects the working directory; otherwise it remains the workspace root. The
 same options apply to local and `worker://` script targets. Native skill files
 retain their sibling imports and source-relative assets.
+
+`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
+alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
+(`PLURNK_*`, provider credentials) are refused by name.

package/docs/ruby.md

@@ -20,3 +20,7 @@ puts JSON.generate(words.tally)
 exception or `exit 1` closes with status 500 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.
+
+`[{"env": {"NAME": "value"}}]` on the same fence line sets variables for this run
+alone, over the entries in your `env` registry; names are the shell's, and plurnk's own
+(`PLURNK_*`, provider credentials) are refused by name.

package/docs/sh.md

@@ -29,7 +29,15 @@ pwd
 
 The receipt always names the directory the command ran in.
 
-A script target runs that script: ````` ````sh (greet.sh) ````` runs it with an empty
+`env` on the same line sets variables for this run alone, over the entries in
+your `env` registry; plurnk's own names (`PLURNK_*`, provider credentials) are
+refused by name:
+
+````sh [{"env": {"LC_ALL": "C"}}]
+sort names.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.
@@ -50,8 +58,8 @@ runs. Output then streams under the receipt's `stream` address, such as
 `## Delegation` 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: its first page
-(up to 16 lines), `range` extent, and terminal exit status. READ the `stream`
-address for more; the `log:///…/READ` item holds only its recorded page:
+(up to 16 lines), `range` extent, and terminal exit status. READ that observation's
+`path` for more; the `log:///…/READ` item holds only its recorded page:
 
 ````READ (sh:///ab3d5678#stdout) <17,40>
 ````
@@ -64,34 +72,21 @@ never output: output lives on the stream and in the harness READs. A receipt
 with a non-200 status and no `stream` address ran nothing; its body is still
 your program, and its Problem says why it was refused.
 
-## Deadlines & polling — `<timeout, poll>`
+## Lifetime
 
-For a long-running command, the `<L>` slot carries `<timeout, poll>` in minutes:
+How long a command may run is one metadata field; absent, it ends with the loop.
 
-````sh <30>
-npm run build
-````
-
-````sh <30,5>
+````sh [{"lifetime": "30m"}]
 npm run e2e
 ````
 
-````sh <-1,5>
-npm run test
-````
-
-````sh <-1,0>
-tail -f app.log
+````sh [{"lifetime": "detached"}]
+npm run dev
 ````
 
-The first coordinate is the timeout: a positive value kills at that deadline;
-`-1` declines the deadline and the process outlives the loop — it runs until it
-exits or you KILL it, so a server you must leave running takes `<-1>`; `0` keeps
-the process only through the current turn. Anything without `-1` is reaped when
-the loop ends. The optional
-positive second coordinate fixes the poll cadence while a loop is parked on
-the stream. With no explicit poll, the consumer uses exponential backoff so a
-parked loop can inspect partial output and decide whether to wait or KILL. A
-second coordinate of `0` disables timer polling for that stream; its eventual
-closure still wakes the loop. Polling wakes the loop but never interrupts the
-command.
+A duration (`30s`, `30m`, `2h`) kills the command at that deadline. `detached`
+outlives the loop — it runs until it exits or you KILL it, so a server you must
+leave running takes it. `turn` keeps the command only through the current turn.
+While you wait on a stream, the service wakes you to inspect it; you never ask
+for that, and you never poll from inside a loop. To act again later with nothing
+in flight, add a rule with the `schedule` family targeting yourself.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@plurnk/plurnk-execs-common",
-    "version": "1.17.0",
+    "version": "1.19.0",
     "description": "Universal subprocess executor for plurnk-service's exec scheme — one package exposing the shell, Node.js, Python 3, and supported host interpreters.",
     "keywords": [
         "plurnk",
@@ -270,6 +270,6 @@
         "prepublishOnly": "npm audit --audit-level=moderate && npm test"
     },
     "peerDependencies": {
-        "@plurnk/plurnk-execs": "^1.17.0"
+        "@plurnk/plurnk-execs": "^1.19.0"
     }
 }