@plurnk/plurnk-service 1.21.1 → 1.23.0

package/.env.defaults

@@ -10,6 +10,13 @@
 # Database path; empty = $XDG_DATA_HOME/plurnk/plurnk.db (~/.local/share by default).
 # Module operational state: $XDG_STATE_HOME/plurnk (~/.local/state/plurnk by default).
 PLURNK_SERVICE_DB_PATH=
+# A private daemon's root ({§state-root}): empty = the XDG homes; an absolute path (a leading ~/
+# expands) roots data, state, cache and runtime under it as <root>/{data,state,cache,runtime}/plurnk.
+# Configuration and the shared Agent Skills root never move; PLURNK_SERVICE_DB_PATH still wins.
+PLURNK_SERVICE_STATE_ROOT=
+# Where `share` writes when no folder is named: each share is a stamped child folder.
+# A leading ~/ expands; empty = $XDG_STATE_HOME/plurnk/shares (~/.local/state/plurnk/shares by default).
+PLURNK_SERVICE_SHARE_FOLDER=
 # The listener's address, PLURNK_HOST and PLURNK_PORT, is shared with every client and so is
 # declared by @plurnk/plurnk-contracts; --host and --port still spell it for one invocation.
 
@@ -63,7 +70,7 @@ PLURNK_SERVICE_FILE_MATERIALIZE_MAX_BYTES=104857600
 # --- Loop limits and recovery ---
 # Default child model: alias or provider/model. Unset = inherit the spawning loop's model.
 # PLURNK_MODEL_CHILD=fast
-# Model turns per loop, including resumes; -1 = unlimited. Client limits may tighten it.
+# Model calls across the worker tree, including BARE and resumes; -1 = unlimited. Clients may tighten it.
 PLURNK_SERVICE_MAX_TURNS=-1
 # Actions per emission; -1 = unlimited. Final disposition remains; excess actions report an error.
 PLURNK_SERVICE_MAX_COMMANDS=-1
@@ -75,9 +82,10 @@ PLURNK_SERVICE_LOOP_TIMEOUT=86400000
 PLURNK_SERVICE_LIVE_TIMEOUT=600000
 # Shutdown settlement deadline, positive ms; abandon outstanding waits after expiry.
 PLURNK_SERVICE_STOP_TIMEOUT_MS=30000
-# Provider recovery window, ms; 0 = park immediately. Expiry parks until the next prompt/wake. Loop and BARE calls alike.
+# Provider recovery window, ms; 0 = no reissue. Expiry parks attended loops until a prompt/wake;
+# unattended loops conclude and BARE returns the provider failure.
 PLURNK_SERVICE_PROVIDER_RECOVERY=900000
-# First recovery delay, ms; doubles on failure, capped at 12 times this value.
+# First recovery delay, ms; doubles on failure up to PROVIDER_RECOVERY_BACKOFF_MAX below.
 PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF=5000
 # Ceiling of that doubling delay, ms.
 PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF_MAX=60000
@@ -109,6 +117,11 @@ PLURNK_SERVICE_EXEC_CONCURRENCY=12
 PLURNK_SERVICE_EXEC_INPUT_TIMEOUT_MS=10000
 # Deadline for one runtime's availability probe at boot, positive ms; expiry reports it unavailable.
 PLURNK_SERVICE_EXEC_PROBE_TIMEOUT_MS=3000
+# Directory a non-file execution source (`sh (log:///…)`) is written to for its run, created 0700
+# on first use ({§exec-scratch-directory}). Empty = $XDG_RUNTIME_DIR/plurnk, else the platform
+# temporary directory. An executor in another filesystem namespace (a container that mounts only
+# the repository) must see the same directory: point this at one it mounts.
+PLURNK_SERVICE_EXEC_SCRATCH=
 # What an operation that runs code or changes the world does: propose = it needs a settlement;
 # auto = it runs ungated. This covers a subprocess and an outbound POST, PUT or DELETE alike.
 PLURNK_SERVICE_EFFECT_HOST=propose

package/INSTALL.md

@@ -15,7 +15,7 @@ plurnk-service start
 ```
 
 First start seeds the user's configuration once. No model ships active;
-choose a model route before starting a model loop. The version-1 database
+[choose a model route](https://github.com/plurnk/plurnk-service/blob/main/plurnk-providers/README.md#configure-a-model) before starting a model loop. The version-1 database
 baseline is disposable during development.
 
 | Resource | Default location |
@@ -62,7 +62,7 @@ the owning declaration specifies its meaning.
 | File creation and membership | Separate policies. Creating an out-of-root file, admitting a new file, and editing an existing member are distinct decisions. |
 | User-facing behavior | Operating policy; use configuration for runtime controls. |
 
-The `@plurnk/plurnk-providers` README covers alias tuning, reasoning and output
+The [`@plurnk/plurnk-providers` README](https://github.com/plurnk/plurnk-service/blob/main/plurnk-providers/README.md#configure-a-model) covers alias tuning, reasoning and output
 budgets, local endpoints, caching, and connectivity; the
 [model chapter](skill://plurnk/references/models.md) is what a model is told.
 The defaults catalog groups the remaining settings by their owning subsystem:

package/README.md

@@ -27,7 +27,7 @@ Clients use AG-UI management actions and AG-UI Run streams exposed by
 a second client transport.
 
 `models.list` locally lists catalog routes, configuration readiness, and each
-route's accepted `capabilities.reasoningPolicies`. `worker.reasoning.get`
+route's accepted `capabilities.efforts`. `worker.effort.get`
 reports the choices shared by a worker's selected model and spawn override.
 
 ## Start