@plurnk/plurnk-service 1.0.4 → 1.0.6

package/.env.defaults

@@ -45,9 +45,11 @@ PLURNK_PORT=3044
 # strikes, or cycle detection). A positive value is an inviolable hard cap a
 # per-call loop.run({maxTurns}) cannot exceed (min wins).
 PLURNK_SERVICE_MAX_TURNS=-1
-# Per-emission op cap (runaway-loop guard). A client may tighten it per session via
-# session.create settings.maxCommands (min wins); never raise it past this (#232).
-PLURNK_SERVICE_MAX_COMMANDS=99
+# Per-emission op ceiling. -1 (default) = no cap: every generated op dispatches (a runaway
+# op-loop is a sampler concern, not grounds to drop already-generated work). A positive value
+# is an operator ceiling a client may tighten per workspace via workspace.create settings.maxCommands
+# (min wins), never raise past (#232).
+PLURNK_SERVICE_MAX_COMMANDS=-1
 # Proposal resolution bound (ms). Empty = a stopped world waits for its human indefinitely;
 # set to auto-cancel unattended (resolves cancel, outcome=timeout).
 PLURNK_SERVICE_PROPOSAL_TIMEOUT_MS=
@@ -70,10 +72,10 @@ PLURNK_SERVICE_LOOP_TIMEOUT=86400000
 
 # Operator questions (SEND[300] — ask-the-user multiple choice / open question). Three states:
 # unset (shipped) = ALLOWED but not enabled — a client must affirmatively pass its own
-# PLURNK_QUESTIONS=1 (rides session.create settings.questions) to enable its sessions;
-# uncomment =0 to DENY servicewide (a ceiling the client cannot override). Enabled sessions
+# PLURNK_QUESTIONS=1 (rides workspace.create settings.questions) to enable its workspaces;
+# uncomment =0 to DENY servicewide (a ceiling the client cannot override). Enabled workspaces
 # get the questions.md teaching injected automatically (the same conditional-doc mechanism as
-# the EXEC plugin docs) — an un-enabled session is never taught the op it can't use, and an
+# the EXEC plugin docs) — an un-enabled workspace is never taught the op it can't use, and an
 # emitted [300] is refused with a self-decide steer instead of parking into the void.
 # PLURNK_QUESTIONS=0
 
@@ -83,27 +85,39 @@ PLURNK_SERVICE_MIN_CYCLES=3
 PLURNK_SERVICE_MAX_CYCLE_PERIOD=4
 
 # --- Schemes ---
-# (Workspace root for file ops is per-session — supplied at
-# session.create({projectRoot}) or never (headless is forever);
-# stored on sessions.project_root. No env-level default.)
+# (Workspace root for file ops is per-workspace — supplied at
+# workspace.create({projectRoot}) or never (headless is forever);
+# stored on workspaces.project_root. No env-level default.)
 
 # --- Git integration ---
 # PLURNK_SERVICE_GIT_ALLOWED — hard ceiling for git membership + integration (repo telemetry,
-# EXEC[git]). =1 permits it (then declared repos + per-session config decide; a client
-# may deny its own session via session.create settings.git:false, #232); =0 flatly
+# EXEC[git]). =1 permits it (then declared repos + per-workspace config decide; a client
+# may deny its own workspace via workspace.create settings.git:false, #232); =0 flatly
 # denies it service-wide, un-re-enableable (the sandbox/benchmark lockout).
 PLURNK_SERVICE_GIT_ALLOWED=1
 # PLURNK_SERVICE_GIT_AUTO — default repo declaration. =1 auto-declares an implicit `repo` at
 # project_root (no-op when it isn't a git tree); =0 declares nothing — clients add
 # repos explicitly via the `repo` overlay. SPEC §membership forest.
 PLURNK_SERVICE_GIT_AUTO=1
+# PLURNK_SERVICE_GIT_NATIVE — git READ backend. Default (0) = in-process isomorphic-git:
+# portable, sandbox-safe, no subprocess, hermetic by construction. =1 routes membership +
+# status to the system git binary — in-process membership measures ~8x native (~130ms at
+# 20k files) and the status read ~55x, so a large-repo host with git buys the hot path back.
+PLURNK_SERVICE_GIT_NATIVE=0
+
+# PLURNK_SERVICE_ARRIVAL_PREVIEW_LINES — the arrival law (§arrival-law, #499): content another
+# actor pushes at a worker (a prompt, a child's deliverable) rides OPEN only up to this many
+# lines AND 80×N chars (the char cap guards single-line bombs); over, a bounded head + the
+# address + the full price ride instead. Self-invited content (a worker's own READ/FIND) is
+# budget-bounded, never previewed. 16 = generous but not dangerous.
+PLURNK_SERVICE_ARRIVAL_PREVIEW_LINES=16
 
 # --- Reference docs (auto-READ at turn 1) ---
 # PLURNK_SERVICE_MD_<ALIAS>=<path> materializes <path>'s markdown as a plurnk://<ALIAS>.md
 # entry the model READs at turn 0 — an idiomatic way to inject standing context
 # (an ordinary entry + READ op, not a bespoke packet section). ~ expands to home;
 # relative paths resolve against the package root. A client may add its own docs
-# per session via session.create settings.mdDocs (content, not a path); those UNION
+# per workspace via workspace.create settings.mdDocs (content, not a path); those UNION
 # with these env docs, keyed by alias — the client wins a collision (#231).
 # Commented out = no docs by default. (The operating policy is NOT a doc: readSystemPolicy
 # already renders ~/.plurnk/AGENTS.md as the ## Plurnk Service Policy section — pointing a
@@ -114,19 +128,19 @@ PLURNK_SERVICE_GIT_AUTO=1
 # the model's own memory reads as withheld. This knob's first-N cap applies ONLY to the FILE list
 # (FIND(file:///**)), the one catalog that's external and arbitrarily large: -1 = the whole tree
 # (everything full); N = the first N files (memory still full); 0 = preview off entirely (the model
-# FINDs on demand). Servicewide default; a client overrides per session via session.create
+# FINDs on demand). Servicewide default; a client overrides per workspace via workspace.create
 # settings.filesItems (#231).
 PLURNK_SERVICE_FILES_ITEMS=-1
 
-# Session-tier ceiling on CONCURRENT active runs (a run with a non-terminal loop)
+# Workspace-tier ceiling on CONCURRENT active runs (a run with a non-terminal loop)
 # — the fork-bomb / destabilization brake. -1 = no cap (default); only concurrency
-# is bounded, never lifetime, since sessions persist for months. A spawn/fork past
+# is bounded, never lifetime, since workspaces persist for months. A spawn/fork past
 # the ceiling fails hard (508 — no queue, no retry); the acting run counts itself.
-PLURNK_SERVICE_SESSION_RUNS_MAX_ACTIVE=-1
+PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=-1
 
 # --- The window partition (§tokenomics-window-partition) — PER ALIAS (#352) ---
-# The window splits WITHOUT remainder: promptBudget = min(CTX, real window) − REASONING −
-# ASSISTANT − SAFETY is what the service may send; REASONING+ASSISTANT is the generation
+# The window splits WITHOUT remainder: promptBudget = min(CONTEXT_WINDOW, real window) − REASONING −
+# COMPLETION − SAFETY is what the service may send; REASONING+COMPLETION is the generation
 # envelope (max_tokens on every call — no decode is unbounded); SAFETY covers chat-template
 # overhead. The prompt ceiling is DERIVED, never set directly.
 #
@@ -136,19 +150,26 @@ PLURNK_SERVICE_SESSION_RUNS_MAX_ACTIVE=-1
 # a max-output field, so "send generous, let the backend clamp" is the honest cloud posture).
 # This makes connecting a cloud reasoner a zero-config on-ramp: a DeepSeek-V4 that burns ~16k on
 # reasoning alone gets the headroom to finish its DSL instead of dying at finish=length (#351).
-PLURNK_SERVICE_CTX=163840
+PLURNK_SERVICE_CONTEXT_WINDOW=163840
 PLURNK_SERVICE_REASONING=16384
-PLURNK_SERVICE_ASSISTANT=49152
+PLURNK_SERVICE_COMPLETION=49152
 PLURNK_SERVICE_SAFETY=1024
 #
+# PLURNK_SERVICE_BUDGET_MERMAID — the Budget section as visual mermaid (#440, §budget-mermaid). Default
+# `on`: the ceiling/usage/free headline PLUS three budget-scaled diagrams (turn-composition treemap,
+# heaviest-items xychart, used/free pie) — budget-awareness at a glance, and the pie doubles as a
+# training exemplar for the model's own user-facing SENDs. Validated to render on GitHub. Set `off` to
+# A/B against the tabular baseline (#440's before/after measurement).
+PLURNK_SERVICE_BUDGET_MERMAID=on
+#
 # LOCAL aliases (llama-server) MUST keep a MEASURED envelope: llama-server honors n_predict to
 # the context wall, and an unbounded decode wall-runs into 30k+ junk tokens (providers#10 — the
 # reason the cap doctrine exists). The tinkerer with a graphics card UNCOMMENTS a block keyed to
 # their alias and their model's real n_ctx (example alias name 'myalias'; a local model
 # run under the bare cloud-generous defaults fails HARD at build with a remedy naming these knobs):
-# PLURNK_SERVICE_CTX_myalias=78848
+# PLURNK_SERVICE_CONTEXT_WINDOW_myalias=78848
 # PLURNK_SERVICE_REASONING_myalias=4096
-# PLURNK_SERVICE_ASSISTANT_myalias=8192
+# PLURNK_SERVICE_COMPLETION_myalias=8192
 # PLURNK_SERVICE_SAFETY_myalias=1024
 # COUPLING (F7): per-request numeric reasoning budgets are IGNORED by llama-server — a local
 # thinking model's serving box MUST clamp via --reasoning-budget = its PLURNK_SERVICE_REASONING_<alias>,
@@ -207,15 +228,18 @@ PLURNK_SERVICE_SEMANTIC_CHUNK_OVERLAP=0.15
 # hosts/runs that don't want vector search; the fast test lane sets it in .env.test.
 PLURNK_SERVICE_EMBED_DISABLE=0
 
-# --- Search prefetch (§search-prefetch, #333) ---
-# Exec runtimes whose #results digest declares web members: on conclusion every candidate url
-# is materialized into an ordinary http entry (inside the EXEC_HOLD window) and #results is
-# rewritten as the survivor render — chooser context + live token/line costs, dead rows gone.
-PLURNK_SERVICE_SEARCH_PREFETCH_RUNTIMES=search
-# Fan-out width for the materialization pass.
-PLURNK_SERVICE_SEARCH_PREFETCH_CONCURRENCY=4
-# Per-page ceiling (ms): a page slower than this is not a member (rummy: parallel, 10s).
-PLURNK_SERVICE_SEARCH_PREFETCH_TIMEOUT_MS=10000
+# Which exec runtimes the search gate treats as searches — the per-turn cap and identical-query
+# dedup apply to these (the search family delegates page fetches to the entry() sink; §exec-entry-sink).
+PLURNK_SERVICE_SEARCH_RUNTIMES=search
 # Per-turn search flood cap: the (N+1)th search EXEC in one turn is refused 429 (dedup of
 # identical queries is unconditional and separate — it strikes and serves the prior results).
 PLURNK_SERVICE_SEARCH_MAX_PER_TURN=3
+# FIND match-render budget: a FIND whose match set exceeds this returns a COUNT + narrow-your-query
+# steer instead of enumerating every match (§find-count-not-contents) — a repo-scale FIND(**) over
+# a 19k-entry workspace grinds clean instead of overflowing the window. 0/unset = no gate.
+PLURNK_SERVICE_FIND_MAX_MATCHES=500
+# Derivation-pump concurrency: how many entries' embeds run at once. The embedder's worker pool is
+# data-parallel but starves on sequential per-entry calls (#416) — overlapping K embeds saturates
+# it (a large-workspace ingest goes from a single-core minutes-long grind to a fast multi-core
+# pass). 1 = sequential (default, safe). Set to ~cores for repo-scale ingest.
+PLURNK_SERVICE_DERIVE_CONCURRENCY=1

package/INSTALL.md

@@ -37,7 +37,7 @@ A bare flag is a signal: more than one component depends on it. A prefixed one i
 
 These are relationships *between* flags. Set them as a unit.
 
-- **The window partition is exact.** `promptBudget = min(PLURNK_SERVICE_CTX, real window) − REASONING − ASSISTANT − SAFETY`; `REASONING + ASSISTANT` is the per-call `max_tokens`. Shipped invariant: any window ≥ 77Ki partitions to **exactly 65536** prompt tokens (`78848 − 4096 − 8192 − 1024`). Reserves exceeding the window fail the boot. *(Pinned: `Engine.budget` / `shipped-defaults`.)*
+- **The window partition is exact.** `promptBudget = min(PLURNK_SERVICE_CONTEXT_WINDOW, real window) − REASONING − COMPLETION − SAFETY`; `REASONING + COMPLETION` is the per-call `max_tokens`. Shipped invariant: any window ≥ 77Ki partitions to **exactly 65536** prompt tokens (`78848 − 4096 − 8192 − 1024`). Reserves exceeding the window fail the boot. *(Pinned: `Engine.budget` / `shipped-defaults`.)*
 - **Reasoning capacity is one number in three places.** `PLURNK_SERVICE_REASONING` (the partition's reserve) **must equal** `PLURNK_PROVIDERS_THINKING_CAPACITY` (the provider's thinking cap) **must equal** the serving box's `--reasoning-budget` launch flag. llama-server ignores per-request numeric budgets, so only the launch flag clamps it; a mismatch makes the reserve fiction. The daemon warns at boot when thinking is on. *(Pinned: `shipped-defaults` asserts the first equality.)*
 - **Grammar rails ship on, gated on the provider's claim (#336).** A backend that doesn't enforce grammars drops it cleanly — the daemon boots with a notice, unconstrained on that alias. A backend that CLAIMS enforcement (`constrainsOutput`) is **verified end-to-end at boot** and fails hard if it returns unconstrained output. Daemon-global — not alias-scoped (one backend per daemon). For a known llama-server alias, pin `PLURNK_PROVIDERS_LLAMA_SERVER_<alias>=1` — it transports the grammar deterministically instead of probing `/v1/models` (a probe race once silently disabled the rails). *(Pinned: `grammar-enforcement-verify`.)*
 - **A think-trained model must think somewhere.** `PLURNK_PROVIDERS_THINKING=off` reroutes a reasoning model's thought into the grammar's legal free zone as prose. Keep it `on` with a capacity; providers auto-clamp thinking on in-band grammar backends, so one setting is right everywhere.
@@ -60,10 +60,10 @@ Each mirrors a `# --- section ---` in the floor; consult the floor for exact def
 - **Git** — `PLURNK_SERVICE_GIT_ALLOWED` (0 = hard sandbox lockout), `_GIT_AUTO`.
 - **Packet / reference docs** — `PLURNK_SERVICE_FILES_ITEMS` (turn-1 file catalog cap), `_PROMPT_PREVIEW_CHARS`, `_DOCS_EXCLUDE`, `_PACKET_INJECT` (operator markdown section), `_POLICY`/`_PROJECT`/`_REQUIREMENTS` (policy + footer overrides; unset = the seeded/packaged defaults), `_MD_<alias>` (inject a markdown doc as a turn-0 entry).
 - **Providers** — `PLURNK_PROVIDERS_THINKING`/`_THINKING_CAPACITY`, `_TEMPERATURE`, `_REPEAT_PENALTY`, `_FETCH_TIMEOUT`, `_RETRY_ATTEMPTS`/`_RETRY_DELAY`, `_PROBE_ATTEMPTS`/`_PROBE_DELAY`, `_GBNF` (grammar variant), `_LLAMA_SERVER_<alias>`, `_CONTEXT_SIZE`, `_GBNF_DEBUG`. Alias-scopable: any knob takes a `_<alias>` suffix that wins over the bare fallback.
-- **The window partition** — `PLURNK_SERVICE_CTX`/`_REASONING`/`_ASSISTANT`/`_SAFETY` (see Couplings).
+- **The window partition** — `PLURNK_SERVICE_CONTEXT_WINDOW`/`_REASONING`/`_ASSISTANT`/`_SAFETY` (see Couplings).
 - **Plugins** — bare `PLURNK_PLUGINS_TRUSTED_ONLY` (0/unset = load all installed; a value = `@plurnk/*` plus an allowlist).
 - **Semantic search** — `PLURNK_SERVICE_SEMANTIC_CHUNK_TOKENS`/`_CHUNK_OVERLAP` (service-side chunking), `PLURNK_SERVICE_EMBED_DISABLE` (FTS-only), `PLURNK_MIMETYPES_EMBED_WORKERS` (the embedder's pool — mimetypes-owned).
 - **Schemes: http** — `PLURNK_SCHEMES_HTTP_FETCH_TIMEOUT`/`_SALVAGE_MIN_BODY_CHARS`/`_IDLE_TIMEOUT` (required on the HTML render path), optional Playwright/Chromium knobs.
 - **Execs** — `PLURNK_EXECS_<runtime>=0` disables a runtime; `PLURNK_EXECS_MCP_<server>` bridges an MCP server; `PLURNK_EXECS_SEARCH_SEARXNG_URL` enables web search (unset = search off).
 
-The client's own knobs live under `PLURNK_CLIENT_*` (`--session`, `--run`, `--yolo`, `--json`…) — see `plurnk --help`.
+The client's own knobs live under `PLURNK_CLIENT_*` (`--workspace`, `--run`, `--yolo`, `--json`…) — see `plurnk --help`.

package/README.md

@@ -6,18 +6,18 @@ LLM agent runtime engine. Consumes [plurnk-grammar](https://github.com/plurnk/pl
 
 Grammar ops: `PLAN` reason · `READ`/`EDIT` files · `FIND` search · `EXEC` run shell/code · `SEND` message or conclude · `COPY`/`MOVE`/`KILL` manage · `OPEN`/`FOLD` curate its own context.
 
-Over schemes: `file://` project files · `exec://` command output · `http(s)://` web fetch · `run://` sibling agent runs (spawn / fork / message) · `known://` scratch · `log://` own history.
+Over schemes: `file://` project files · `exec://` command output · `http(s)://` web fetch · `worker://` sibling agent runs (spawn / fork / message) · `known://` scratch · `log://` own history.
 
 ## Loop model
 
-Session = the shared world (one filesystem + membership overlay). Run = one agent's private log. Loop = one `prompt → ops → SEND[terminal]` cycle; every turn leads with `PLAN`. Runs fork and message each other — many clients, many runs, one session.
+Workspace = the shared world (one filesystem + membership overlay). Run = one agent's private log. Loop = one `prompt → ops → SEND[terminal]` cycle; every turn leads with `PLAN`. Runs fork and message each other — many clients, many runs, one workspace.
 
 ## Integration (WebSocket JSON-RPC)
 
-Methods: `session.*` (create / attach / constrain / list…) · `loop.run` / `loop.inject` / `loop.resolve` · `op.*` (read / edit / find / exec / send…) · `log.read` · `run.fork`. Streams: `log/entry` → … → `loop/terminated`, plus `loop/proposal`, `telemetry/event`. Full live catalog: the `discover` RPC.
+Methods: `workspace.*` (create / attach / constrain / list…) · `loop.run` / `loop.inject` / `loop.resolve` · `op.*` (read / edit / find / exec / send…) · `log.read` · `run.fork`. Streams: `log/entry` → … → `loop/terminated`, plus `loop/proposal`, `telemetry/event`. Full live catalog: the `discover` RPC.
 
 ```
-ws connect → session.create({ projectRoot }) → loop.run({ prompt })
+ws connect → workspace.create({ projectRoot }) → loop.run({ prompt })
            → read log/entry notifications until loop/terminated
 ```