@plurnk/plurnk-service 1.18.0 → 1.19.0

package/.env.defaults

@@ -6,13 +6,12 @@
 # ./.env > user .env > package defaults. Later explicit env files win.
 # Service flags mirror these names: PLURNK_SERVICE_MAX_TURNS → --service-max-turns.
 
-# --- Storage and listener ---
+# --- Storage ---
 # Database path; empty = $XDG_DATA_HOME/plurnk/plurnk.db (~/.local/share by default).
+# Module operational state: $XDG_STATE_HOME/plurnk (~/.local/state/plurnk by default).
 PLURNK_SERVICE_DB_PATH=
-# AG-UI listener bind address.
-PLURNK_HOST=127.0.0.1
-# AG-UI listener TCP port, shared by all client interfaces.
-PLURNK_PORT=1066
+# 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.
@@ -31,11 +30,27 @@ PLURNK_SERVICE_SQLITE_READERS=0
 # CapabilityPolicy JSON: deny removes matching demands; only admits only matches.
 # Workspace, Worker, and loop policies may narrow this ceiling, never widen it.
 PLURNK_SERVICE_CAPABILITIES={}
+# What a loop does with a proposal when its creator did not say: review holds it for a
+# client's answer; accept applies it and reject refuses it inside the loop.
+PLURNK_SERVICE_PROPOSALS=review
+# Whether anyone is attending a loop when its creator did not say: 1 = someone can answer;
+# 0 = unattended, so no human-in-the-loop surface is offered and a wait nobody could end concludes.
+PLURNK_SERVICE_ATTENDED=1
+# What an unattended loop does with a proposal when its creator did not say: accept | reject.
+# Nobody is present to review, so review is not a choice here. Rejecting is the honest default: an
+# effect nobody approved does not run. A harness that means to run unattended states accept.
+PLURNK_SERVICE_UNATTENDED_PROPOSALS=reject
 # New filesystem files: none | root | namespace (also outside root). Existing-member writes unchanged.
 PLURNK_SERVICE_FILE_CREATE_SCOPE=root
 # Model-added membership: none | root | namespace. Workspaces may narrow it.
-# Operator definitions use PLURNK_MEMBERS_<alias>=<glob> and PLURNK_MEMBERS_ENABLED=["alias"].
 PLURNK_SERVICE_MEMBERS_MODEL_SCOPE=namespace
+# Operator members definitions enabled by default, JSON array of aliases; [] = none.
+PLURNK_MEMBERS_ENABLED=[]
+# A definition is PLURNK_MEMBERS_<alias>=<glob>; a leading ! excludes.
+# PLURNK_MEMBERS_docs=docs/**
+# PLURNK_MEMBERS_no_locks=!**/*.lock
+# Matched paths a members definition lists as its sample; the rest are counted.
+PLURNK_SERVICE_MEMBERS_SAMPLE=20
 # Git membership, status, and branch integration: 1 = permitted; 0 = denied service-wide.
 PLURNK_SERVICE_GIT_ALLOWED=1
 # Include the repository containing project_root as members: 1 = yes; 0 = explicit members only.
@@ -64,6 +79,8 @@ PLURNK_SERVICE_STOP_TIMEOUT_MS=30000
 PLURNK_SERVICE_PROVIDER_RECOVERY=900000
 # First recovery delay, ms; doubles on failure, capped at 12 times this value.
 PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF=5000
+# Ceiling of that doubling delay, ms.
+PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF_MAX=60000
 # Consecutive turn-contract strike threshold.
 PLURNK_SERVICE_MAX_STRIKES=3
 # Completed responses allowed to produce an admissible turn against the same packet.
@@ -90,12 +107,19 @@ PLURNK_SERVICE_EXEC_HOLD_MS=300000
 PLURNK_SERVICE_EXEC_CONCURRENCY=12
 # Live input delivery deadline, positive ms, including queued writes; expiry retires input, not the process.
 PLURNK_SERVICE_EXEC_INPUT_TIMEOUT_MS=10000
-# Effect overrides, comma-separated effect:policy (host/read/pure → propose/auto).
-# Empty = host proposes, read/pure auto-run.
-PLURNK_SERVICE_EFFECT_POLICY=
+# Deadline for one runtime's availability probe at boot, positive ms; expiry reports it unavailable.
+PLURNK_SERVICE_EXEC_PROBE_TIMEOUT_MS=3000
+# What an operation that runs code or changes the world does: propose = it needs a settlement;
+# auto = it runs ungated. This covers a subprocess and an outbound POST, PUT or DELETE alike.
+PLURNK_SERVICE_EFFECT_HOST=propose
+# The same for an operation that only observes external state.
+PLURNK_SERVICE_EFFECT_READ=auto
+# The same for an operation with no observable effect.
+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
-# Initial parked-EXEC poll delay, seconds; explicit <,P> wins and <,0> disables polling.
+# Initial parked-EXEC observation delay, seconds. The cadence is the daemon's; a fence states
+# only how long its run may live ({§exec-lifetime}).
 PLURNK_SERVICE_EXEC_POLL_SEC=60
 # Backoff steps: delay doubles to BASE * 2^(TURNS-1), then stays capped.
 PLURNK_SERVICE_EXEC_POLL_TURNS=8
@@ -113,10 +137,11 @@ PLURNK_SERVICE_EXEC_ENV_EXCLUDE=
 PLURNK_SERVICE_EXEC_KILL_GRACE_MS=2000
 
 # --- Context and receipts ---
-# Maximum lines in automatic text previews and markerless READs. Explicit scopes stay exact.
-PLURNK_SERVICE_PREVIEW_LINES=16
+# First page of every markerless retrieval, in the projection's own units: lines of text,
+# bytes of a byte view, results of a FIND. Explicit scopes stay exact.
+PLURNK_SERVICE_PREVIEW_LINES=100
 # Independent bound on the same previews, Unicode code points; CRLF counts as one separator.
-PLURNK_SERVICE_PREVIEW_CHARS=2560
+PLURNK_SERVICE_PREVIEW_CHARS=16000
 # Turn0 reasoning READ: -1 = complete; 0 = omit; N = first N lines. Later reads are model-chosen.
 # Alias override: PLURNK_REASONING_VIEW_LINES_<alias>. Source retention/streaming are unchanged.
 PLURNK_REASONING_VIEW_LINES=-1
@@ -127,6 +152,24 @@ PLURNK_SERVICE_PROMPT_PROJECTION=25%
 PLURNK_SERVICE_LINE_ANCHOR_CONTEXT_LINES=2
 # Surrounding and changed lines shown at each EDIT boundary; overlapping windows coalesce.
 PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=4
+# Removed lines a pure deletion's receipt carries so it can be undone; a longer span is cut and counted.
+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
+# Share of the packet ceiling at which the model is told to curate its log.
+PLURNK_SERVICE_BUDGET_PRESSURE=80%
+# Largest log items listed with that instruction.
+PLURNK_SERVICE_BUDGET_LARGEST_ITEMS=5
+# Code points of an entry's prose summary the catalog shows whole.
+PLURNK_SERVICE_CATALOG_SUMMARY_CHARS=256
+# Log entries one client read returns when it names no limit.
+PLURNK_SERVICE_LOG_READ_PAGE=100
+# Ceiling of one client log read, whatever limit it names.
+PLURNK_SERVICE_LOG_READ_MAX=1000
+# Root-conversation prompts one listing returns when it names no limit.
+PLURNK_SERVICE_PROMPTS_PAGE=100
+# Models one catalog page lists when the query names no limit.
+PLURNK_SERVICE_MODEL_CATALOG_PAGE=50
 # Turn-0 surveys: -1 = ordinary first pages; N > 0 caps file-map rows; 0 = off.
 # Workspace settings.filesItems overrides this default; other surveys keep ordinary pages.
 PLURNK_SERVICE_FILES_ITEMS=-1
@@ -139,6 +182,12 @@ PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 PLURNK_SERVICE_SKILLS_CLI="npx --yes skills"
 # Skills search registry (GET /api/search?q=...); empty = registry search disabled.
 PLURNK_SERVICE_SKILLS_REGISTRY_URL=https://skills.sh
+# Results one registry search asks for.
+PLURNK_SERVICE_SKILLS_REGISTRY_LIMIT=20
+# Deadline for one registry search, positive ms.
+PLURNK_SERVICE_SKILLS_REGISTRY_TIMEOUT_MS=30000
+# Deadline for one skills CLI run, positive ms.
+PLURNK_SERVICE_SKILLS_CLI_TIMEOUT_MS=120000
 # Extra Markdown after language teaching, reread each turn; unreadable explicit paths fail.
 # PLURNK_SERVICE_PACKET_INJECT="~/injection.md"
 # Policy Markdown: unset = $XDG_CONFIG_HOME/plurnk/AGENTS.md; empty = off; otherwise that path.
@@ -149,6 +198,9 @@ PLURNK_SERVICE_SKILLS_REGISTRY_URL=https://skills.sh
 # --- Search indexing ---
 # Comma-separated globs excluded from derivation, not READ. No slash = basename; slash = pathname.
 PLURNK_SERVICE_SEARCH_EXCLUDE=*.min.*,*.map,package-lock.json,npm-shrinkwrap.json,packages.lock.json,yarn.lock,pnpm-lock.yaml,bun.lockb,Cargo.lock,poetry.lock,uv.lock,Pipfile.lock,Gemfile.lock,composer.lock,go.sum,flake.lock,gradle.lockfile,*/dist/*,dist/*,*/build/*,build/*,*/.next/*,.next/*,*/node_modules/*,node_modules/*,*/vendor/*,vendor/*,*/coverage/*,coverage/*,*/.vuepress/*,.vuepress/*,*/.nuxt/*,.nuxt/*
+# Bodies larger than this many bytes are not parsed or full-text indexed (READ is unaffected);
+# empty = unbounded.
+PLURNK_SERVICE_SEARCH_MAX_BYTES=
 # Concurrent parser derivations: empty = sqrt(available cores); -1 = all cores; positive N = exact cap.
 PLURNK_SERVICE_DERIVE_CONCURRENCY=
 # Maximum symbol/reference rows per indexing SQLite statement.
@@ -176,5 +228,16 @@ PLURNK_SERVICE_RETAIN_RESPONSE_MS=-1
 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}).
+PLURNK_SERVICE_COLLECT_CONTENTS=1
 # Retention cadence while the daemon runs, ms; 0 = at shutdown only.
 PLURNK_SERVICE_RETENTION_INTERVAL_MS=3600000
+# SQLite auto-vacuum mode the daemon keeps its file in ({§db-space-reclamation}): incremental =
+# retention passes return free pages to the OS; none = the file only grows, and freed pages are
+# reused. A change takes effect at the next start through one VACUUM, which rewrites the whole
+# file (needs free disk about the file's size and blocks the daemon for its duration).
+PLURNK_SERVICE_AUTO_VACUUM=incremental
+# Free space, bytes, below which a retention pass leaves free pages for SQLite to reuse instead
+# of returning them; 0 = return every free page each pass.
+PLURNK_SERVICE_RECLAIM_MIN_FREE_BYTES=0

package/README.md

@@ -18,7 +18,7 @@ The exact model-facing language and operation set are owned by
 
 ## Lifecycle model
 
-Workspace = the shared world (one filesystem + membership overlay). Worker = one actor and its history over that world. Loop = one queued-to-terminal unit of work within a worker; each loop contains turns, and each model turn ends with a TASK inventory that determines its workflow outcome. Workers fork and message each other — many clients, many workers, one workspace.
+Workspace = the shared world (one filesystem + membership overlay). Worker = one actor and its history over that world. Loop = one queued-to-terminal unit of work within a worker. Turns continue until messages are answered, results observed, and held work settled; WAIT yields while work remains. NOTE retains working memory independently of lifecycle. Workers fork and message each other — many clients, many workers, one workspace.
 
 ## Integration
 
@@ -53,6 +53,8 @@ configuration guide.** A legacy mixed `~/.plurnk` is moved only by the explicit
 The 1.x package retains its frozen root library barrel for SemVer compatibility;
 it is not the client boundary and gains no new APIs. Programmatic forensic use
 imports `@plurnk/plurnk-service/digest`.
+The digest replaces its selected output directory; keep that directory separate
+from its input database. Overlapping input/output paths are refused.
 
 ## Contract & siblings
 
@@ -71,9 +73,9 @@ The daemon can emit OpenTelemetry traces and low-cardinality metrics through the
 
 `FIND`'s `~query` uses native SQLite FTS5: words, quoted phrases, prefixes, Boolean expressions, and proximity queries, ranked by BM25. It searches the same readable content as READ, returns source coordinates, and uses ordinary integer result paging. No inference endpoint, model artifact, or extra search package is required.
 
-## The file sandbox
+## What the model can see
 
-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. An execution 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. This is a membership list, not a perimeter: an execution deliberately reaches past it, so its proposal policy — not the file surface — is where consent is asked. Details: SPEC {§scheme-address} ({§fs-namespace} through {§fs-world-state}).
 
 ## Tests