@plurnk/plurnk-service 1.4.0 → 1.6.0

package/.env.defaults

@@ -42,6 +42,9 @@ PLURNK_HOST=127.0.0.1
 PLURNK_PORT=3044
 
 # --- Loop control ---
+# Optional default child-provider alias. Unset = each WORK/FORK child inherits
+# its spawning loop's provider. Clients may override this per top-level loop.
+# PLURNK_MODEL_CHILD=fast
 # Operator turn ceiling. -1 (default) = no cap (loops end via SEND, budget,
 # strikes, or cycle detection). A positive value is an inviolable hard cap a
 # CoreSeam runLoop({maxTurns}) request cannot exceed (min wins).
@@ -51,6 +54,8 @@ PLURNK_SERVICE_MAX_TURNS=-1
 # 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
+# Live & demo test harness story timeout (ms) — 10 minutes (600000ms).
+PLURNK_SERVICE_LIVE_TIMEOUT=600000
 # 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.
@@ -61,12 +66,11 @@ PLURNK_SERVICE_PROPOSAL_TIMEOUT_MS=
 # that effect class.
 PLURNK_SERVICE_EXEC_HOLD=search,images,videos,news,map,music,it,science,social,downloadable
 PLURNK_SERVICE_EXEC_HOLD_MS=300000
-# Post-EXEC breath: after a turn fires a non-inline EXEC whose spawn is still in
-# flight at the turn boundary, wait this many ms before assembling the next packet
-# so a fast exec's output can land in it instead of a turn later. A fixed grace
-# beat, NOT a wait-for-completion (slow execs proceed + surface via the wake path).
-# 0 = off (the model sees fast-exec output a turn late, as today).
-PLURNK_SERVICE_EXEC_WAIT_MS=1000
+# Optimistic worker settlement: before model dispatch, allow newly started
+# streams or a completion wake with live siblings this many ms to quiesce.
+# Settlement ends immediately at quiescence and never extends its first
+# deadline; survivors follow the monitored lifecycle. 0 = off.
+PLURNK_SERVICE_OPTIMISTIC_WAIT_MS=5000
 # Exec poll backoff (#521, {§exec-poll}): a parked exec with NO explicit `<,P>` cadence is no longer
 # park-blind-forever — the loop wakes on an exponential backoff so the model regains a turn to read
 # partial output and re-park a slow long-runner or KILL a stuck one. Wake N fires at BASE·2^min(N,TURNS-1)
@@ -93,7 +97,7 @@ PLURNK_SERVICE_LOOP_TIMEOUT=86400000
 # Maximum characters retained from caught runtime diagnostics in a model-facing
 # Problem detail. Complete errors remain in daemon diagnostics.
 PLURNK_SERVICE_ERROR_DETAIL_LIMIT=512
-PLURNK_SERVICE_MAX_STRIKES=3
+PLURNK_SERVICE_MAX_STRIKES=6
 # Completed responses that do not form a valid PLAN...SEND turn are retried
 # beneath the same engine turn and against the identical packet.
 PLURNK_SERVICE_EMISSION_ATTEMPTS=3
@@ -127,12 +131,16 @@ PLURNK_SERVICE_GIT_ISO=0
 # optional in-process reader does not use this bound.
 PLURNK_SERVICE_GIT_OUTPUT_MAX_BYTES=67108864
 
-# Universal OPEN-body preview bounds. Only model-origin READ/FIND results render
-# complete; every other log body renders at most this many lines and characters.
-# A truncated body carries the log URI for a deliberate full READ. Separate
-# bounds prevent both multiline floods and single-line bombs.
+# 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
+# bounds. A truncated body carries its canonical log URI.
 PLURNK_SERVICE_PREVIEW_LINES=16
-PLURNK_SERVICE_PREVIEW_CHARS=1280
+PLURNK_SERVICE_PREVIEW_CHARS=2560
+
+# Number of complete neighboring lines hashed on each side of a model-facing
+# line anchor. 0 authenticates only the addressed line.
+PLURNK_SERVICE_LINE_ANCHOR_CONTEXT_LINES=2
 
 # --- Reference docs (auto-READ at turn 0) ---
 # PLURNK_SERVICE_MD_<ALIAS>=<path> materializes <path>'s markdown as a
@@ -148,9 +156,9 @@ PLURNK_SERVICE_PREVIEW_CHARS=1280
 # Turn-0 catalog preview so a run opens oriented, not blank. Folder-capable schemes use
 # FIND(<scheme>:///*): direct entries plus exact dir/** summaries carrying each subtree's
 # recursive item and token counts. Curated kernel docs remain recursive, demonstrating both
-# navigation forms. -1 = complete shallow maps; N = first N file-map rows (other schemes remain
-# complete); 0 = preview off. Service-wide default; a client overrides per workspace through
-# workspace.create settings.filesItems (#231).
+# navigation forms. -1 = each ordinary FIND's markerless first page; N = an explicit first-N
+# project-file page (other schemes remain markerless); 0 = preview off. Service-wide default;
+# a client overrides per workspace through workspace.create settings.filesItems (#231).
 PLURNK_SERVICE_FILES_ITEMS=-1
 
 # Number of full SHA-256 revision characters rendered on each model-facing
@@ -162,8 +170,8 @@ PLURNK_SERVICE_EDIT_RECEIPT_REVISION_CHARS=8
 # The durable batch retains complete commit ids; this is display-only.
 PLURNK_SERVICE_BRANCH_RECEIPT_REVISION_CHARS=8
 
-# Number of neighboring lines (or top-level JSON items) rendered on each side
-# of an EDIT's resulting range. The model can READ for arbitrary final content.
+# Number of surrounding and landed lines shown at each boundary of an EDIT
+# result. Overlapping windows coalesce; the model can READ omitted content.
 PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=2
 
 # Workspace-tier ceiling on CONCURRENT active runs (a run with a non-terminal loop)
@@ -173,16 +181,21 @@ PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=2
 PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=-1
 
 # --- Prompt budget and packing safety — PER ALIAS (#352) ---
-# Providers report physical context and response capacity. Core's natural prompt budget is the
-# remaining physical input room after the response envelope and SAFETY margin.
+# Providers report the effective total context envelope and generation capacity. Core's natural
+# prompt gauge is the remaining input room after the generation envelope and SAFETY margin.
 #
-# PROMPT_BUDGET is optional virtual pressure: it makes the model-facing gauge and grinder enforce
-# a smaller input budget without changing provider context or generation settings. Unset uses the
-# natural physical prompt budget; a set value can only tighten it. Both core knobs resolve per
+# PROMPT_BUDGET is optional virtual pressure: it tightens the model-facing gauge and grinder
+# without changing hard context admission or generation settings. Unset uses the natural prompt
+# gauge; a set value can only tighten it. Both core knobs resolve per
 # alias: _<alias> wins over bare.
 # The retired PLURNK_SERVICE_{CONTEXT_WINDOW,REASONING,COMPLETION} names FAIL HARD at boot naming
 # their successors — a stale .env never silently loses its envelope.
 # PLURNK_SERVICE_PROMPT_BUDGET=128000
+# Maximum aggregate share of the stable model-facing prompt gauge used by
+# automatic OPEN prompt bodies. The complete prompt remains stored and
+# READ/FIND-addressable; this controls projection, not prompt admission.
+# Alias-scoped overrides follow the ordinary _<alias> convention.
+PLURNK_SERVICE_PROMPT_PROJECTION=25%
 PLURNK_SERVICE_SAFETY=1024
 #
 # LOCAL aliases (llama-server): the window is PROBED and the reserves DERIVE from it in the
@@ -212,8 +225,8 @@ PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 # PLURNK_SERVICE_POLICY=
 # PLURNK_SERVICE_PROJECT — a per-project policy markdown (relative to projectRoot). Unset = <root>/AGENTS.md.
 # PLURNK_SERVICE_PROJECT=
-# PLURNK_SERVICE_REQUIREMENTS — override the requirements.md recency-footer path (relative to the package
-# root). Unset = the packaged requirements.md.
+# PLURNK_SERVICE_REQUIREMENTS — Recap source override (relative to the package root).
+# Unset = the packaged requirements.md.
 # PLURNK_SERVICE_REQUIREMENTS=
 
 # --- Semantic search (~query chunking) ---
@@ -221,9 +234,6 @@ PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 # body is fully searchable, not truncated. Chunking requires the embedder's exact
 # counter or an exact fallback tokenizer; an estimate refuses semantic derivation.
 # The chunk knobs are read only when an embedder declares its input window.
-# Ranked results returned by a markerless `FIND(...):~query:FIND`. A positive
-# integer `<K>` overrides this count; a decimal marker selects by similarity.
-PLURNK_SERVICE_SEMANTIC_TOP_K=10
 # Chunk budget in TOKENS. EMPTY (the default) = the installed embedder's reported
 # window — NO model-specific number is assumed, so it scales to whatever embedder you
 # install. Set a positive value ONLY to cap below the window (e.g. to sweep
@@ -246,10 +256,6 @@ 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
 # Comma-separated file pathname patterns omitted from search derivations. Content remains directly
 # readable. Patterns without `/` match the basename; patterns with `/` match the full pathname.
 # Uses body-matcher glob syntax; the first match is the observable exclusion reason. Empty = none.

package/INSTALL.md

@@ -40,11 +40,14 @@ When a value is required, an unset or retired name fails boot naming the violate
 
 These are relationships *between* flags. Set them as a unit.
 
-- **Provider capacity and PLURNK pressure are separate.** Providers report
-  physical context and response capacity. Core derives the natural input
-  budget from those facts. Optional `PLURNK_SERVICE_PROMPT_BUDGET_<alias>`
+- **Hard capacity and PLURNK pressure are separate.** Providers report the
+  effective total context envelope and generation capacity. Core derives the
+  natural prompt gauge from those facts. Optional `PLURNK_SERVICE_PROMPT_BUDGET_<alias>`
   only tightens the model-facing gauge and grinder; it is never sent to the
-  provider and never changes generation settings.
+  provider and never changes hard admission or generation settings.
+  `PLURNK_SERVICE_PROMPT_PROJECTION_<alias>` assigns a stable percentage of
+  that gauge to automatic prompt bodies; it never limits stored prompt size
+  ({§prompt-projection}).
 - **Reasoning capacity is request-scoped on llama-server.**
   `PLURNK_PROVIDERS_REASONING_RESERVE_<alias>` is the adaptive cumulative
   response allowance. An explicit `PLURNK_PROVIDERS_REASONING_BUDGET_<alias>`
@@ -63,7 +66,7 @@ These are relationships *between* flags. Set them as a unit.
 
 ## Profiles (examples, not a decision tree — adapt to the real box)
 
-- **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.gbnf`. The provider detects llama-server, verifies its GBNF transport, and derives a request-scoped reasoning allowance from the detected window. Add `PLURNK_PROVIDERS_LLAMA_SERVER_local=1` only when the endpoint cannot be fingerprinted reliably.
+- **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 a request-scoped reasoning allowance from the detected window. 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.
@@ -74,21 +77,23 @@ Each mirrors a `# --- section ---` in the floor; consult the floor for exact def
 
 - **Storage** — `PLURNK_SERVICE_DB_PATH`, and the optional `PLURNK_SERVICE_SQLITE_*` passthroughs (sqlrite already sets a safe WAL posture; tune only for a hot/large DB).
 - **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 aliases** — bare `PLURNK_MODEL` selects the active provider; `PLURNK_MODEL_<alias>` defines one; `PLURNK_BASEURL_<alias>` overrides its endpoint. The front door — keep these bare and short.
-- **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`, `_EXEC_WAIT_MS`, `_EXEC_POLL_SEC`/`_TURNS`, `_EXEC_KILL_GRACE_MS`, `_WORKSPACE_WORKERS_MAX_ACTIVE`.
+- **Model aliases** — bare `PLURNK_MODEL` selects the active provider; `PLURNK_MODEL_<alias>` defines one; `PLURNK_BASEURL_<alias>` overrides its endpoint. Optional `PLURNK_MODEL_CHILD=<alias>` selects WORK/FORK descendants; unset inherits the spawning loop's provider. The front door — keep these bare and short.
+- **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`.
-- **Packet / reference docs** — `PLURNK_SERVICE_FILES_ITEMS` (turn-0 shallow file-map cap), `_PREVIEW_LINES`/`_PREVIEW_CHARS`, `_EDIT_RECEIPT_REVISION_CHARS`/`_CONTEXT_LINES`, `_BRANCH_RECEIPT_REVISION_CHARS`, `_DOCS_EXCLUDE`, `_PACKET_INJECT` (operator markdown section), `_POLICY`/`_PROJECT`/`_REQUIREMENTS` (policy + footer overrides), `_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), `_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
   suffix that wins over the bare fallback.
 - **Provider capacity and prompt budget** —
   `PLURNK_PROVIDERS_CONTEXT_WINDOW`/`_REASONING_RESERVE`/`_COMPLETION_RESERVE`
   describe provider capacity. `PLURNK_SERVICE_PROMPT_BUDGET` applies optional
-  virtual pressure; `PLURNK_SERVICE_SAFETY` is the packing margin.
+  virtual pressure; `PLURNK_SERVICE_PROMPT_PROJECTION` assigns the automatic
+  prompt-body share; `PLURNK_SERVICE_SAFETY` is the packing margin.
 - **Plugins** — bare `PLURNK_PLUGINS_TRUSTED_ONLY` (0/unset = load all installed; a value = `@plurnk/*` plus an allowlist).
-- **Semantic search** — `PLURNK_SERVICE_SEMANTIC_TOP_K` (markerless result count), `_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.
+- **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`, `_TTL_MS`, optional `# TAVILY_API_KEY=`, and `PLURNK_SCHEMES_HTTP_TAVILY_DEPTH`/`_TAVILY_TIMEOUT_MS`.
 - **Execs** - `PLURNK_EXECS_<runtime>=0` disables a runtime; `PLURNK_EXECS_SEARCH_SEARXNG_URL` enables web search (unset = search off).
+- **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`.
 - **Observability** — standard `OTEL_*` env ({§observability-boundary}):
   `OTEL_TRACES_EXPORTER`/`OTEL_METRICS_EXPORTER` (`otlp` or `console`; unset
   keeps the signal off), `OTEL_SERVICE_NAME` (default `plurnk-service`),

package/README.md

@@ -47,6 +47,7 @@ imports `@plurnk/plurnk-service/digest`.
 - `@plurnk/plurnk-schemes` — addressable resource contract.
 - `@plurnk/plurnk-mimetypes` — content handling contract.
 - `@plurnk/plurnk-execs` — executable capability contract.
+- `@plurnk/plurnk-hooks` — selected lifecycle events delivered to exact commands.
 
 ## Observability