@plurnk/plurnk-service 1.4.0 → 1.5.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)
@@ -127,12 +131,12 @@ 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 render their selected
+# operation result complete; every other 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
 
 # --- Reference docs (auto-READ at turn 0) ---
 # PLURNK_SERVICE_MD_<ALIAS>=<path> materializes <path>'s markdown as a
@@ -148,9 +152,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
@@ -212,8 +216,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 +225,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 +247,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

@@ -74,10 +74,10 @@ 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`, `_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.
@@ -86,9 +86,10 @@ Each mirrors a `# --- section ---` in the floor; consult the floor for exact def
   describe provider capacity. `PLURNK_SERVICE_PROMPT_BUDGET` applies optional
   virtual pressure; `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