@plurnk/plurnk-service 3.0.0 → 3.2.0

package/.env.defaults

@@ -20,8 +20,11 @@ PLURNK_SERVICE_SHARE_FOLDER=
 # The listener's address, PLURNK_HOST and PLURNK_PORT, is shared with every client and so is
 # declared by @plurnk/plurnk-contracts; --host and --port still spell it for one invocation.
 
-# --- SQLite (optional sqlrite overrides) ---
-# Lock wait, ms; 0 = immediate failure. sqlrite defaults to 5000, WAL, synchronous=NORMAL.
+# --- SQLite ---
+# WAL durability ({§db-durability}): FULL syncs every commit; NORMAL may lose recent commits
+# on power loss; OFF may corrupt the database; EXTRA equals FULL in WAL. Applied before migration.
+PLURNK_SERVICE_SQLITE_SYNCHRONOUS=FULL
+# Lock wait, ms; 0 = immediate failure. Unset = sqlrite's default.
 # PLURNK_SERVICE_SQLITE_TIMEOUT=5000
 # Page cache: positive = pages; negative = KiB. Unset = SQLite default.
 # PLURNK_SERVICE_SQLITE_CACHE_SIZE=-16000
@@ -69,7 +72,7 @@ PLURNK_SERVICE_FILE_MATERIALIZE_MAX_BYTES=104857600
 # Opt-in model-call ceiling shared by the worker tree, including BARE and resumes; -1 = uncapped.
 # Runtime (_plurnk) ancestry supplies no ceiling. Clients may tighten the model tree's limit.
 PLURNK_SERVICE_MAX_TURNS=-1
-# Actions per emission; -1 = unlimited. Final disposition remains; excess actions report an error.
+# Resolved actions per emission, including glob targets; -1 = unlimited. WAIT remains exempt.
 PLURNK_SERVICE_MAX_COMMANDS=-1
 # Concurrent live workers per workspace; -1 = unlimited. Excess spawns return 508, not a queue.
 PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=-1
@@ -128,14 +131,14 @@ PLURNK_SERVICE_EFFECT_READ=auto
 PLURNK_SERVICE_EFFECT_PURE=auto
 # Brief settlement wait for new streams/completing siblings, ms; 0 = off; quiescence ends it early.
 PLURNK_SERVICE_OPTIMISTIC_WAIT_MS=5000
-# Maximum park before reassessing live work, positive seconds; WAIT <seconds> overrides one park.
+# Maximum park before reassessing live work, positive seconds; WAIT [seconds] overrides one park.
 PLURNK_SERVICE_WAIT_SEC=300
 # Ambient environment an EXEC subprocess may inherit from the host: exact names, or one
-# trailing-* prefix glob. This is a CEILING — a worker or a heading modifier narrows it,
-# nothing widens it. plurnk's own secrets (PLURNK_* and every provider credential name) are
-# stripped beneath it unconditionally and are not governed by this knob.
+# trailing-* prefix glob. This bounds inherited host values, not explicit non-reserved values.
+# PLURNK_* and provider credential names remain excluded regardless of these selectors.
+# Module-owned launches and explicit MCP bindings follow their own launch contract.
 # The shipped list is what a shell, git, node and python need to run at all. An operator
-# who wants a tool's credential reachable by model-written commands adds it by name.
+# who wants a non-reserved tool credential inherited by commands adds its name.
 PLURNK_SERVICE_EXEC_ENV_INHERIT=PATH,HOME,USER,LOGNAME,SHELL,PWD,TMPDIR,TERM,TZ,LANG,LC_*,PAGER,GIT_PAGER,NO_COLOR,CI
 # Names removed after INHERIT, same shapes; narrows without rewriting the list above.
 PLURNK_SERVICE_EXEC_ENV_EXCLUDE=
@@ -151,20 +154,29 @@ PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=4
 PLURNK_SERVICE_EDIT_RECEIPT_REMOVED_LINES=40
 # Paths named per class in the packet's git status; the rest are counted.
 PLURNK_SERVICE_GIT_STATUS_PATHS=8
-# Heaviest retained log rows the Context gauge names, as {path, tokens}; 0 names none.
+# Above this share of the budget, measured before adding either, the Context gauge names its largest rows
+# and a packet within its budget carries the budget_pressure notice ({§context-pressure-notice}).
+PLURNK_SERVICE_BUDGET_PRESSURE=80%
+# Heaviest retained log rows the pressured Context gauge names, as {path, tokens}; 0 names none.
 PLURNK_SERVICE_BUDGET_LARGEST_ITEMS=5
 # First page of everything that comes back unasked in size: a READ or FIND without a scope, a stream's
 # delivery, a peer worker's message, a receipt the model did not author ({§markerless-first-page}).
-# Lines of text, bytes of a byte view, results of a FIND; explicit scopes stay exact.
+# Lines of text, bytes of a byte view, results of a FIND; explicit scopes stay exact. 100 is a page for
+# the million-token windows hosted models have; a deployment with a small room tunes it down.
 PLURNK_SERVICE_PREVIEW_LINES=100
 # Independent bound on the same page, Unicode code points; CRLF counts as one separator.
 PLURNK_SERVICE_PREVIEW_CHARS=16000
+# Assistant replay ({§emission-history}): none, latest, or all eligible turns from this loop, each as the
+# NOTEs it wrote, in the model's voice; every other operation is omitted. The context wall may omit
+# the whole section; source evidence never changes.
+PLURNK_SERVICE_EMISSION_HISTORY=all
 # Optional reasoning memory ({§reasoning-row}): 1 adds the turn's preview before its emission or results,
 # only when room remains after all requested results and diagnostics. Otherwise omit it silently. 0 disables it.
-PLURNK_SERVICE_REASONING_ROWS=1
+PLURNK_SERVICE_REASONING_ROWS=0
 # The row's page ({§reasoning-row}): reasoning that fits it lands whole; longer reasoning lands as its last page,
 # this many lines within PLURNK_SERVICE_PREVIEW_CHARS, because a turn's conclusions and plan sit at its end; the
-# rest stays readable at reasoning://. Unset/empty = the shared page, PLURNK_SERVICE_PREVIEW_LINES.
+# rest stays readable at reasoning://. -1 returns the complete reasoning without either preview bound,
+# still only if it fits. Unset/empty = the shared page, PLURNK_SERVICE_PREVIEW_LINES; 0 is invalid.
 # PLURNK_SERVICE_REASONING_TRAILING_LINES=40
 # Code points of an entry's prose summary the catalog shows whole.
 PLURNK_SERVICE_CATALOG_SUMMARY_CHARS=256
@@ -193,6 +205,10 @@ PLURNK_SERVICE_ROOTS=project,plurnk,global
 # PLURNK_SERVICE_POLICY=
 # Recap file, relative to the package root; unset = packaged recap.md; empty file omits the section.
 # PLURNK_SERVICE_RECAP=
+# Recap lines, one per key: PLURNK_SERVICE_RECAP_LINE_<alias>=<line> ({§recap-lines}). Each opens with YOU MUST,
+# YOU MUST NOT, YOU MUST ONLY, YOU SHOULD, YOU SHOULD NOT or YOU MAY and renders as one callout, in alias order,
+# ahead of the Recap source. An empty value turns a shipped line off.
+# PLURNK_SERVICE_RECAP_LINE_<alias>=
 
 # --- Search indexing ---
 # Comma-separated globs excluded from derivation, not READ. No slash = basename; slash = pathname.
@@ -207,23 +223,24 @@ PLURNK_SERVICE_DERIVE_STORE_BATCH=1024
 # Progress heartbeat, ms; starts, failures, and completion are immediate; no-op passes stay silent.
 PLURNK_SERVICE_DERIVE_PROGRESS_HEARTBEAT_MS=15000
 
-# --- Retention: information is kept; transient data is collected ({§retention-policy}) ---
-# Packet compositions kept per loop, newest first; -1 = every packet, forever.
+# --- Retention: packet/response bodies and unreferenced content ({§retention-policy}) ---
+# Packet compositions kept per loop, newest first; -1 disables the count limit, not the age limit.
 PLURNK_SERVICE_RETAIN_PACKET_TURNS=-1
-# Packet compositions kept by age, ms since the turn completed; -1 = no age limit. Thirty days:
-# no worker reads its own packets back that late, and a daemon left running for months stops growing.
+# Packet compositions kept by age, ms since the turn completed; -1 disables the age limit.
 PLURNK_SERVICE_RETAIN_PACKET_MS=2592000000
-# Model response bodies kept per loop, newest first; -1 = every body, forever. The call's
-# evidence, admission and accounting always stay.
+# Calls with captured payloads kept per loop, newest first; -1 disables the count limit.
+# These controls do not retire messages, turn sources, operations, approval decisions or accounting.
 PLURNK_SERVICE_RETAIN_RESPONSE_TURNS=-1
-# Model response bodies kept by age, ms since the turn completed; -1 = no age limit. Thirty days, as above.
+# Call payloads kept by age, ms since the turn completed; -1 disables the age limit.
+# Covers normalized responses and all physical-request payloads, including failed retries.
+# Identities, status, usage and cost remain; retirement is timestamped on the logical call.
 PLURNK_SERVICE_RETAIN_RESPONSE_MS=2592000000
 # Collect packet items no turn's composition references (1), or keep them (0).
 PLURNK_SERVICE_COLLECT_PACKET_ITEMS=1
 # Collect derivations no channel, turn source, or log row cites (1), or keep them (0).
 PLURNK_SERVICE_COLLECT_DERIVATIONS=1
-# Collect stored bodies no channel holds and no derivation indexes (1), or keep them (0)
-# ({§content-store}).
+# Collect unreferenced text and native bodies (1), or keep them (0).
+# Retained messages, operations and packet attachments pin native bytes ({§native-content-lifetime}).
 PLURNK_SERVICE_COLLECT_CONTENTS=1
 # Retention cadence while the daemon runs, ms; 0 = at shutdown only.
 PLURNK_SERVICE_RETENTION_INTERVAL_MS=3600000

package/INSTALL.md

@@ -79,6 +79,25 @@ sidecars together. Copy the backup to a fresh working path, select that path wit
 `PLURNK_SERVICE_DB_PATH`, and start the same or a newer compatible service version.
 Do not overwrite a live database or pair a restored file with old sidecars.
 
+| Restored input | Startup behaviour |
+| --- | --- |
+| Database | Retained history, approval decisions, attachments and workspace/worker configuration return. Interrupted work is settled without replaying uncertain effects ({§worker-lifecycle-restart-recovery}). |
+| Project files and service configuration | Restore separately. Current files remain authoritative; startup reads the current configuration, not an earlier ambient environment captured in history. |
+| Schedules | Enabled definitions rearm from the present; missed occurrences are not replayed ({§schedule-residency}, {§schedule-first-arming}). |
+| Interactive MCP authorization | Reauthorize. Tokens and pending sign-ins are process-local, not part of the database backup ({§oauth-lifetime}). |
+
+Retention controls expire packet compositions and call payloads, including physical-request
+captures. Messages, turn sources, operation receipts, approval decisions and request accounting
+remain with their containing history ({§retention-policy}); referenced attachment bytes remain
+too ({§native-content-lifetime}). This is not content erasure. A share contains only what remains
+when it is taken.
+
+`PLURNK_SERVICE_SQLITE_SYNCHRONOUS` selects the database's WAL durability before migrations
+or startup writes. Its shipped setting is in `.env.defaults`. `FULL` synchronizes every commit
+to storage; selecting `NORMAL` explicitly trades power-loss durability for fewer synchronizations.
+The guarantees and storage assumptions are defined in {§db-durability}. Neither setting makes
+project-file writes transactional or replaces backups.
+
 ## Precedence
 
 Highest priority first ({§operator-config-precedence}):
@@ -101,13 +120,31 @@ Extension settings remain environment/configuration values; they do not extend t
 service CLI. Boolean flags use `1` and `0`. An empty value is not an unset value;
 the owning declaration specifies its meaning.
 
+## Manual and shell completions
+
+The installed package includes a generated manual and static completions. They
+require no running daemon. Find the global npm package at
+`$(npm root -g)/@plurnk/plurnk-service`; the paths below are relative to it.
+
+| Artifact | Use |
+| --- | --- |
+| `dist/man/plurnk-service.1` | Open with `man /path/to/plurnk-service.1`, or copy into a directory on `MANPATH` (commonly `~/.local/share/man/man1/`). |
+| `dist/completions/plurnk-service.bash` | Source from your Bash configuration. |
+| `dist/completions/_plurnk-service` | Copy into a directory on Zsh's `fpath` before `compinit`. |
+| `dist/completions/plurnk-service.fish` | Copy into `~/.config/fish/completions/`, or the corresponding `XDG_CONFIG_HOME` location. |
+
+Completion offers command names, long options and filenames. Configuration
+values remain in `plurnk-service config defaults`, not a separate static catalog.
+Package installation does not edit shell configuration or install these files
+outside the package.
+
 ## Choose the right scope
 
 | Change | Owner and effect |
 | --- | --- |
 | Startup defaults or installed extension configuration | The daemon's environment cascade. A remote client's shell does not change it. |
 | Model, reasoning, child model | Worker selections persist. Set them through client controls; changing a startup default does not retarget an existing Worker. |
-| MCPs, skills, outbound agents, schedules, membership | Workspace Functionality: list, discover, add, enable, disable, remove. Workers share the workspace's current selection. |
+| MCPs, skills, outbound agents, schedules, membership | Workspace Functionality: list, discover, add, replace, enable, disable, remove. Workers share the workspace's current selection. |
 | Command environment | `env` manages worker overrides or workspace defaults. It does not reconfigure the daemon; running processes keep their launch environment. |
 | External capabilities | Service policy is a ceiling; workspace policy can narrow it for every worker. Hiding a doc does not grant or revoke authority. |
 | Proposal review / YOLO | Decides who accepts or rejects an admitted operation. Automatic acceptance never overrides capability or resource permissions. |

package/README.md

@@ -5,6 +5,9 @@ operation dispatch. Its client surface is AG-UI over HTTP/SSE through
 `@plurnk/plurnk-agui`. The user-facing CLI lives in
 [plurnk](https://github.com/plurnk/plurnk).
 
+See [installation and configuration](INSTALL.md), including the packaged
+[manual and shell completions](INSTALL.md#manual-and-shell-completions).
+
 ## What an agent can do
 
 The exact model-facing language and operation set are owned by