@plurnk/plurnk-service 1.8.0 → 1.9.0

package/.env.defaults

@@ -24,6 +24,11 @@
 # An explicit non-empty path overrides it; `~/` expands to home.
 PLURNK_SERVICE_DB_PATH=
 
+# Filesystem creation ceiling. none = deny new files; root = only project_root (default);
+# namespace = also permit canonical outside-root paths. Existing-member writes are unaffected.
+# A workspace may narrow this with settings.fileCreateScope, never widen it.
+PLURNK_SERVICE_FILE_CREATE_SCOPE=root
+
 # --- Sqlite tuning (curated knobs passed through to sqlrite; optional) ---
 # sqlrite already sets the safe posture (WAL + synchronous=NORMAL + busy_timeout=5000ms).
 # These are operator overrides — integers; unset = sqlrite/sqlite default. Uncomment to tune.
@@ -61,6 +66,12 @@ PLURNK_SERVICE_LIVE_TIMEOUT=600000
 # {§crash-only-stop} — the daemon's settle deadline on stop(): past this the
 # shutdown abandons its waits instead of hanging forever on a wedged child.
 PLURNK_SERVICE_STOP_TIMEOUT_MS=30000
+# Capability residency is demand-owned. After the final lease, keep the
+# worker warm this many ms for quick reuse. 0 = no grace; -1 = no time bound.
+PLURNK_SERVICE_WORKER_WARM_MS=900000
+# Maximum lease-free worker Functionality snapshots retained process-wide. Active work is
+# exempt. 0 = retain none; -1 = no idle-LRU bound.
+PLURNK_SERVICE_WORKER_WARM_MAX=2
 # Proposal resolution bound (ms). Empty = a stopped world waits for its human indefinitely;
 # a finite positive value auto-cancels unattended (outcome=timeout). Every other explicit
 # value is invalid and fails at the proposal lifecycle owner.
@@ -195,6 +206,15 @@ PLURNK_SERVICE_PROMPT_PROJECTION=25%
 # so an enabled tool is always discoverable. Empty → exclude nothing. Unknown names are inert.
 PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 
+# PLURNK_SERVICE_SKILLS_CLI — the standard Agent Skills installer command line beneath the Worker
+# `skills` Functionality family (`add` installs, `remove` uninstalls, `discover {source}` lists).
+# The installed SKILL.md, never the CLI's output, is the evidence. Point it at a pinned binary
+# or a fixture; it is never taught to the model or run by a client.
+PLURNK_SERVICE_SKILLS_CLI="npx --yes skills"
+# PLURNK_SERVICE_SKILLS_REGISTRY_URL — the ecosystem registry behind `discover {query}`
+# (GET <url>/api/search?q=…). Empty disables registry search (501 registry-not-configured).
+PLURNK_SERVICE_SKILLS_REGISTRY_URL=https://skills.sh
+
 # PLURNK_SERVICE_PACKET_INJECT — an operator markdown file injected as a section right after the teaching
 # (the cached prefix). Read per-turn (live edits); a set-but-unreadable path fails the turn HARD.
 # `~/` expands to home. Unset → no section. The pressure valve for "improve the packet" without a fork.

package/INSTALL.md

@@ -57,21 +57,19 @@ When a value is required, an unset or retired name fails boot naming the violate
 
 Plurnk reads the standard universal roots: project skills from
 `.agents/skills/<name>/SKILL.md`, then user-global skills from
-`~/.agents/skills/<name>/SKILL.md`. Package-bundled skills form
-the final layer; the default installation includes an attributed, pinned
-`find-skills`. Project names shadow global names, which shadow bundled names.
-Plurnk never copies a bundled skill into the shared global root and does not
-maintain a separate skill registry.
-
-Use the ecosystem CLI when you deliberately install something. A project
-installation is the ordinary default:
-
-```sh
-npx skills add <owner/repo@skill> --agent universal --yes
-```
-
-Add `--global` only when you intend to share that skill with every compatible
-agent using the universal user root.
+`~/.agents/skills/<name>/SKILL.md`. Project names shadow global names. Plurnk
+bundles no skills, never copies anything into a universal root by itself, and
+keeps no separate skill registry.
+
+Skills are managed per Worker through the common Functionality lifecycle —
+`worker.skills.{list,discover,add,enable,disable,remove}` from a client, the
+generated `EXEC [skills]` family from the model. `add` installs through the
+standard ecosystem CLI (`PLURNK_SERVICE_SKILLS_CLI`, default `npx --yes skills`) into
+the chosen scope, `discover` searches the ecosystem registry
+(`PLURNK_SERVICE_SKILLS_REGISTRY_URL`, default `https://skills.sh`), and a skill you
+install with the CLI yourself is admitted at the next turn. Prefer the project
+scope; choose `global` only when you intend to share a skill with every
+compatible agent using the universal user root.
 
 ## Couplings (the edges an agent gets wrong)
 
@@ -119,7 +117,7 @@ Each mirrors a `# --- section ---` in the floor; consult the floor for exact def
 - **Daemon transport** — bare `PLURNK_HOST`/`PLURNK_PORT`: THE client surface (the AG-UI+ listener, bound by the plurnk-agui module at boot). Production is single-listener; every first-party client rides it.
 - **Model selection** — bare `PLURNK_MODEL` selects a declared alias or exact provider/model route; `PLURNK_MODEL_<alias>` defines an optional friendly route and tuning scope; `PLURNK_BASEURL_<alias>` overrides that alias's endpoint. `PLURNK_MODEL_CHILD` accepts the same selector vocabulary for WORK/FORK descendants; unset inherits the spawning loop's provider.
 - **Loop control / engine rails** — `PLURNK_SERVICE_MAX_TURNS` (−1 = uncapped), `_MAX_COMMANDS`, `_MAX_STRIKES`, `_EMISSION_ATTEMPTS`, `_MIN_CYCLES`, `_MAX_CYCLE_PERIOD`, `_LOOP_TIMEOUT`, `_PROPOSAL_TIMEOUT_MS`, `_EXEC_HOLD`, `_OPTIMISTIC_WAIT_MS`, `_EXEC_POLL_SEC`/`_TURNS`, `_EXEC_KILL_GRACE_MS`, `_WORKSPACE_WORKERS_MAX_ACTIVE`.
-- **Git** — `PLURNK_SERVICE_GIT_ALLOWED` (0 = hard sandbox lockout), `_GIT_AUTO`.
+- **Files and Git** — `PLURNK_SERVICE_FILE_CREATE_SCOPE=none|root|namespace` bounds new filesystem files (`root` by default); `PLURNK_SERVICE_GIT_ALLOWED` (0 = hard sandbox lockout) and `_GIT_AUTO` govern Git participation. A workspace may narrow creation with `settings.fileCreateScope`.
 - **Packet / reference docs** — `PLURNK_SERVICE_FILES_ITEMS` (turn-0 shallow file-map cap), `_PREVIEW_LINES`/`_PREVIEW_CHARS`, `_LINE_ANCHOR_CONTEXT_LINES`, `_EDIT_RECEIPT_REVISION_CHARS`/`_CONTEXT_LINES`, `_BRANCH_RECEIPT_REVISION_CHARS`, `_DOCS_EXCLUDE`, `_PACKET_INJECT` (operator markdown section), `_POLICY`/`_PROJECT` (policy overrides), `_REQUIREMENTS` (Recap-source override), `_MD_<alias>` (materialized reference entry).
 - **Providers** — the portable provider knobs and defaults are defined by
   `@plurnk/plurnk-providers/.env.defaults`; any provider knob may take an alias

package/README.md

@@ -69,7 +69,7 @@ The default service installation includes `@plurnk/plurnk-mimetypes-embeddings`,
 
 ## The file sandbox
 
-Plurnk sees what Git or the client explicitly admits. The AGENTS.md policy path is injected separately as privileged policy, not as a file entry. A project file admitted by neither Git nor the client does not exist to the model, and an ignored secret can be neither read nor overwritten. New files can be created only inside the project and only where the result will remain visible; member edits are proposal-gated; an outside-root member is read-only unless the client explicitly granted it. `EXEC` deliberately reaches beyond this file sandbox, so its proposal policy is the machine perimeter. Details: SPEC {§scheme-address} ({§fs-namespace} through {§fs-world-state}).
+Plurnk sees what Git or an ordinary `pick` admits. The AGENTS.md policy path is injected separately as privileged policy, not as a file entry. A path admitted by neither source does not exist to the model and cannot be overwritten. Accepted creation is exclusive and never orphaned: it is Git-added or receives an inspectable exact pick. Creation defaults to `project_root`, can be disabled or expanded to the canonical namespace by operator policy, and only an explicit pick overrides Git ignore. Member edits remain proposal-gated; an outside-root member is read-only unless a pick grants it. `EXEC` deliberately reaches beyond this file sandbox, so its proposal policy is the machine perimeter. Details: SPEC {§scheme-address} ({§fs-namespace} through {§fs-world-state}).
 
 ## Tests