@plurnk/plurnk-service 1.10.1 → 1.12.0

package/.env.defaults

@@ -45,9 +45,13 @@ PLURNK_SERVICE_FILE_CREATE_SCOPE=root
 PLURNK_HOST=127.0.0.1
 # THE client surface — the AG-UI+ listener (the plurnk-agui daughter module binds it at boot).
 # Production is single-listener: every first-party client rides this surface.
-PLURNK_PORT=3044
+PLURNK_PORT=1066
 
 # --- Loop control ---
+# Service-wide capability ceiling as a CapabilityPolicy JSON object. `deny`
+# removes matching demands; an optional `only` admits only matching demands.
+# Workspace, Worker, and loop policies may narrow this ceiling, never widen it.
+PLURNK_SERVICE_CAPABILITIES={}
 # Optional default child-model selector (declared alias or provider/model route).
 # Unset = each WORK/FORK child inherits its spawning loop's model. Clients may
 # override this per top-level loop.
@@ -83,6 +87,9 @@ PLURNK_SERVICE_PROPOSAL_TIMEOUT_MS=
 # runtimes explicitly.
 PLURNK_SERVICE_EXEC_HOLD=
 PLURNK_SERVICE_EXEC_HOLD_MS=300000
+# Maximum EXEC producers admitted concurrently in one workspace. Additional
+# executions retain their durable streams and wait FIFO; -1 removes the bound.
+PLURNK_SERVICE_EXEC_CONCURRENCY=12
 # Effect admission overrides ({§effect-policy-tunable}): comma-separated
 # <effect>:<policy> entries (host/read/pure → propose/auto). Unlisted effects
 # keep the default map (host proposes; read/pure auto-run). Empty = defaults.
@@ -105,15 +112,14 @@ PLURNK_SERVICE_EXEC_POLL_TURNS=8
 # signal-ignoring child. plurnk-execs refuses to bake this number; the consumer owns it.
 PLURNK_SERVICE_EXEC_KILL_GRACE_MS=2000
 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 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 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
+# {§provider-recovery} A recoverable provider failure (network failure, rate limit, deadline,
+# interrupted resource) never ends a loop. After the provider's own retries the turn records the
+# failure, waits with exponential backoff, and re-issues the same call for up to RECOVERY ms
+# (0 parks at once); past that the loop parks like a `## SEND0 [202]` wait and resumes on the
+# next prompt or wake. BACKOFF is the first delay (ms); it doubles per failure, capped at twelve
+# times itself.
+PLURNK_SERVICE_PROVIDER_RECOVERY=900000
+PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF=5000
 
 # --- Engine rails ---
 # Maximum characters retained from caught runtime diagnostics in a model-facing
@@ -143,11 +149,29 @@ PLURNK_SERVICE_REQUIEM_RETRY_MAX_TOKENS=32768
 # denies it service-wide, un-re-enableable (the sandbox/benchmark lockout).
 PLURNK_SERVICE_GIT_ALLOWED=1
 # PLURNK_SERVICE_GIT_AUTO — automatic project-repository membership. =1 includes the Git
-# repository containing project_root; =0 leaves `pick` as the only membership source.
+# repository containing project_root; =0 leaves member definitions as the only membership source.
 PLURNK_SERVICE_GIT_AUTO=1
+# PLURNK_SERVICE_BRANCH_DELEGATION — branch-tagged WORK/FORK ({§worker-branch-batch}). =0 refuses a
+# WORK/FORK signal up front as 501 branch-delegation-disabled: the form is off the model-facing
+# surface until it is specified and witnessed end to end (#396). =1 enables the serialized
+# branch batches for development and their witnesses.
+PLURNK_SERVICE_BRANCH_DELEGATION=0
 # Maximum stdout/stderr payload accepted from one native Git subprocess.
 PLURNK_SERVICE_GIT_OUTPUT_MAX_BYTES=67108864
 
+# --- Membership ({§membership-baseline}) ---
+# PLURNK_SERVICE_MEMBERS_MODEL_SCOPE — the ceiling a MODEL's `## EXEC0 [members] (add)` is admitted
+# against, in the file-creation lattice none < root < namespace: `none` refuses every model
+# definition (the model widens visibility only through `git add`); `root` admits globs inside the
+# project root; `namespace` admits `../` too. A workspace narrows it with settings.membersModelScope.
+# The operator's own definitions are PLURNK_MEMBERS_<ALIAS>=<glob> (`!glob` excludes) and
+# PLURNK_MEMBERS_ENABLED=[…] in the operator env.
+PLURNK_SERVICE_MEMBERS_MODEL_SCOPE=none
+# Maximum bytes admitted into one materialized workspace-file snapshot (1..100 MiB,
+# matching the storage ceiling). A larger member remains addressable, but READ/EDIT
+# return its durable 413 size result.
+PLURNK_SERVICE_FILE_MATERIALIZE_MAX_BYTES=104857600
+
 # Ordinary bounded OPEN-body projection. READ/FIND results and PLAN working
 # memory render complete; prompt initialization uses its separate budget share.
 # Every remaining log body renders at most these independent line and character
@@ -224,9 +248,9 @@ PLURNK_SERVICE_SKILLS_REGISTRY_URL=https://skills.sh
 # section. Unset = the seeded $XDG_CONFIG_HOME/plurnk/AGENTS.md; a path = that file;
 # EXPLICITLY empty = policy off.
 # PLURNK_SERVICE_POLICY=
-# PLURNK_SERVICE_REQUIREMENTS — Recap source override (relative to the package root).
-# Unset = the packaged requirements.md.
-# PLURNK_SERVICE_REQUIREMENTS=
+# PLURNK_SERVICE_RECAP — Recap source override (relative to the package root).
+# Unset = the packaged recap.md; empty content omits the Recap section.
+# PLURNK_SERVICE_RECAP=
 
 # --- Semantic search (~query chunking) ---
 # Project Semantics tiles each vector-eligible entry into <=window chunks so a large
@@ -241,9 +265,9 @@ PLURNK_SERVICE_SEMANTIC_CHUNK_TOKENS=
 # Overlap fraction [0,1): trailing context re-covered at each chunk boundary so a
 # concept split across a cut still matches in both. ~0.15 is a standard RAG default.
 PLURNK_SERVICE_SEMANTIC_CHUNK_OVERLAP=0.15
-# Optional maximum UTF-8 body size eligible for vectors. Oversized entries remain
-# readable, graph-derived, and FTS-indexed. 0 = unlimited (the shipped default).
-PLURNK_SERVICE_MAX_EMBED_SIZE=0
+# Maximum UTF-8 body size eligible for vectors. Oversized entries remain readable,
+# graph-derived, and FTS-indexed. 0 explicitly opts into unlimited vector eligibility.
+PLURNK_SERVICE_MAX_EMBED_SIZE=262144
 # =1 forces the FTS-only path even with the embeddings package installed — the ~query
 # degrades to keyword ranking and no vectors are derived (no MiniLM pool spun up). For
 # hosts/runs that don't want vector search; the Mock bootstrap and constrained benchmarks set it.

package/INSTALL.md

@@ -23,7 +23,7 @@ edit`, `config defaults`, and `config check` to inspect and maintain the one
 environment cascade. A pre-XDG `~/.plurnk` is never read implicitly; stop the
 old daemon and run `plurnk-service paths migrate` once.
 
-The default service includes local embeddings. An explicitly disabled or unavailable embedder makes `~query` fall back to FTS keyword ranking. Set `PLURNK_MIMETYPES_EMBED_BASE_URL` to use a remote OpenAI-compatible embedding endpoint instead.
+The default service embedding artifact includes its local model and the exact counters required by supported hosted profiles. An explicitly disabled or unavailable embedder makes `~query` fall back to FTS keyword ranking. Set `PLURNK_EMBEDDING_MODEL` to a standard provider/model route or declared model alias to use a hosted or operator-run embedding endpoint instead; provider endpoints and credentials use the same provider configuration as generation. A custom profile whose counter is not built in may add the optional `@plurnk/plurnk-mimetypes-tokenizers` catalog.
 
 ## The cascade (where a value actually comes from)
 
@@ -107,7 +107,7 @@ These are relationships *between* flags. Set them as a unit.
 - **Local GPU (llama-server).** `PLURNK_MODEL_local="openai/<name>"`, `OPENAI_BASE_URL=http://127.0.0.1:<port>`, `PLURNK_MODEL=local`, `PLURNK_PROVIDERS_GBNF_local=plurnk.qwen.gbnf` for Qwen's template-prefilled `<think>` protocol (or `plurnk.gemma.gbnf` when Gemma generates a complete Harmony channel). The provider detects llama-server, verifies its GBNF transport, and derives input capacity from the detected window and configured output envelope. Add `PLURNK_PROVIDERS_LLAMA_SERVER_local=1` only when the endpoint cannot be fingerprinted reliably.
 - **Cloud, bring-your-own-key.** `PLURNK_MODEL_cloud="openrouter/<model>"`, `OPENROUTER_API_KEY=…`, `PLURNK_MODEL=cloud`. No local GBNF or `LLAMA_SERVER` pin.
 - **plurnk.ai endpoint.** `PLURNK_MODEL_plurnk="plurnk/plurnk"`, `PLURNK_API_KEY=…`, `PLURNK_MODEL=plurnk`.
-- **Headless / CI / constrained container.** A CPU-only box should NOT disable semantic search — it should point derivation at a real embedder: `PLURNK_MIMETYPES_EMBED_BASE_URL` (any OpenAI-compatible `/v1/embeddings` — a host GPU turns a CPU-hours corpus grind into seconds). Weak hardware is the target workload, not a reason to shed capability; `PLURNK_SERVICE_EMBED_DISABLE=1` exists for test lanes that deterministically assert non-semantic behavior, nothing else. Consider `PLURNK_SERVICE_MAX_TURNS=<n>` as a cost cap, `PLURNK_SERVICE_GIT_ALLOWED=0` to lock out git in a sandbox.
+- **Headless / CI / constrained container.** A CPU-only box should NOT disable semantic search — it should select a hosted embedder with `PLURNK_EMBEDDING_MODEL=<provider>/<model>` or an embedding alias. The route inherits the standard provider endpoint and credential contract; a local OpenAI-compatible GPU endpoint uses the same alias and `PLURNK_BASEURL_<alias>` convention as generation. Weak hardware is the target workload, not a reason to shed capability; `PLURNK_SERVICE_EMBED_DISABLE=1` exists for test lanes that deterministically assert non-semantic behavior, nothing else. Consider `PLURNK_SERVICE_MAX_TURNS=<n>` as a cost cap, `PLURNK_SERVICE_GIT_ALLOWED=0` to lock out git in a sandbox.
 
 ## Flag sections (breakdown of the service's `.env.defaults`)
 
@@ -118,7 +118,7 @@ Each mirrors a `# --- section ---` in the floor; consult the floor for exact def
 - **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`.
 - **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).
+- **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), `_RECAP` (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
   suffix that wins over the bare fallback.
@@ -128,7 +128,7 @@ Each mirrors a `# --- section ---` in the floor; consult the floor for exact def
   `PLURNK_SERVICE_PROMPT_PROJECTION` assigns the automatic prompt-body share
   of that provider-derived curation gauge.
 - **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).
+- **Semantic search** — `PLURNK_SERVICE_SEMANTIC_CHUNK_TOKENS`/`_CHUNK_OVERLAP` (service-side chunking), `PLURNK_SERVICE_EMBED_DISABLE` (FTS-only), `PLURNK_EMBEDDING_MODEL` (optional provider route/alias), and `PLURNK_EMBEDDING_WORKERS` (the local embedder pool — mimetypes-owned).
 - **Schemes: http** — `PLURNK_SCHEMES_HTTP_FETCH_TIMEOUT`, `_TTL_MS`, optional `# PLURNK_SCHEMES_HTTP_MATERIALIZER=` (a materializer plugin id).
 - **Execs** — `PLURNK_EXECS_<runtime>=0` disables a runtime; web discovery is an MCP attachment (`PLURNK_MCP_<server>`), not an executor.
 - **Hooks** — `PLURNK_HOOKS_COMMAND` plus JSON `PLURNK_HOOKS_ARGS` invokes one exact no-shell command for the core events selected by `PLURNK_HOOKS_EVENTS`; see `@plurnk/plurnk-hooks/README.md`.

package/README.md

@@ -65,11 +65,11 @@ The daemon can emit OpenTelemetry traces and low-cardinality metrics through the
 
 ## Semantic search
 
-The default service installation includes `@plurnk/plurnk-mimetypes-embeddings`, so `FIND`'s `~query` uses embedding cosine ranking without a separate package install. `PLURNK_SERVICE_EMBED_DISABLE=1` explicitly selects FTS keyword ranking; a missing required artifact is a broken installation and refuses startup. A remote OpenAI-compatible embedder can replace the included local path; see [`INSTALL.md`](./INSTALL.md).
+The default service installation includes `@plurnk/plurnk-mimetypes-embeddings`, whose local model and built-in hosted profiles carry their own exact counters, so `FIND`'s `~query` uses embedding cosine ranking without a separate package install. `PLURNK_SERVICE_EMBED_DISABLE=1` explicitly selects FTS keyword ranking; a missing required embedding artifact is a broken installation and refuses startup. A standard provider route can replace the included local model through the same provider configuration used for generation; custom profiles may add the optional general tokenizer catalog. See [`INSTALL.md`](./INSTALL.md).
 
 ## The file sandbox
 
-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}).
+Plurnk sees what Git tracks or a `members` definition includes. 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