@plurnk/plurnk-service 1.0.0

package/.env.defaults

@@ -0,0 +1,208 @@
+# ⚠ REFERENCE — this is @plurnk/plurnk-service's shipped .env.defaults: the operative floor
+# for its knobs and the source of the derived --<knob> CLI flags (INSTALL.md is the agent-facing
+# breakdown). ~/.plurnk/.env.defaults is the ASSEMBLED catalog (every installed package's file),
+# machine-owned and regenerated each boot — do NOT edit either. Put YOUR config in ~/.plurnk/.env
+# (yours, seeded once, never touched) or ./.env.
+#
+# THE STANDARD (every plurnk package, third-party included): ship a `.env.defaults` at your
+# package root declaring YOUR knobs (prefix = your package's name); the file IS the documentation.
+# The daemon assembles every installed member's file into one floor. ONE LAW: a key claimed by
+# two packages crashes boot naming both. Reader declares: every knob your code reads appears in
+# your file — the floor guarantees it set, so code carries no inline fallback.
+#
+# Cascade (low → high precedence — last writer wins):
+#   assembled .env.defaults floor  (this file + every installed member's, uniqueness-checked)
+#   < ~/.plurnk/.env               (your home config — seeded once, yours to keep)
+#   < ./.env                       (per-project, current directory)
+#   < --env-file=… / --config=…
+#   < shell environment
+#   < --<knob> CLI flags           (the 1:1 mirror: --service-max-turns <-> PLURNK_SERVICE_MAX_TURNS)
+# Feature-flag bools use `=== "1"` exactly, never `=== "true"`. `~/` expands to your home.
+
+# --- Storage ---
+PLURNK_SERVICE_DB_PATH=~/.plurnk/plurnk.db
+
+# --- Sqlite tuning (curated knobs passed through to sqlrite; optional) ---
+# sqlrite already sets the safe posture (WAL + synchronous=NORMAL + busy_timeout=5000ms).
+# These are operator overrides — integers; unset = sqlrite/sqlite default. Uncomment to tune.
+# busy_timeout (ms): how long a writer waits on a lock before SQLITE_BUSY. 0 = immediate.
+# PLURNK_SERVICE_SQLITE_TIMEOUT=5000
+# cache_size: positive = pages, negative = KiB of memory. Bigger = fewer disk reads on a hot db.
+# PLURNK_SERVICE_SQLITE_CACHE_SIZE=-16000
+# mmap_size: bytes of memory-mapped I/O (read perf on large file-backed dbs). 0 disables.
+# PLURNK_SERVICE_SQLITE_MMAP_SIZE=268435456
+# max_page_count: hard db-size ceiling in PAGES — a write past it errors (disk-fill guard).
+# PLURNK_SERVICE_SQLITE_MAX_PAGE_COUNT=524288
+
+# --- Daemon transport ---
+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
+
+# --- Loop control ---
+# 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
+# per-call loop.run({maxTurns}) cannot exceed (min wins).
+PLURNK_SERVICE_MAX_TURNS=-1
+# Per-emission op cap (runaway-loop guard). A client may tighten it per session via
+# session.create settings.maxCommands (min wins); never raise it past this (#232).
+PLURNK_SERVICE_MAX_COMMANDS=99
+# Proposal resolution bound (ms). Empty = a stopped world waits for its human indefinitely;
+# set to auto-cancel unattended (resolves cancel, outcome=timeout).
+PLURNK_SERVICE_PROPOSAL_TIMEOUT_MS=
+# Turn-hold runtimes: while a listed runtime's stream is in flight the cycle pauses (no next
+# turn) until it concludes. Bounded by _HOLD_MS, fail-open at the cap. Empty = no holds.
+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
+# Teardown reap grace: when a loop/run tears down a background exec, the spawn gets a polite
+# signal first (SIGHUP, or the model's KILL[code]); a stream that IGNORES it is hard-killed
+# (SIGKILL, to the whole process group) this many ms later — so the reap can't wedge on a
+# 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 session.create settings.questions) to enable its sessions;
+# uncomment =0 to DENY servicewide (a ceiling the client cannot override). Enabled sessions
+# get the questions.md teaching injected automatically (the same conditional-doc mechanism as
+# the EXEC plugin docs) — an un-enabled session 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
+
+# --- Engine rails ---
+PLURNK_SERVICE_MAX_STRIKES=3
+PLURNK_SERVICE_MIN_CYCLES=3
+PLURNK_SERVICE_MAX_CYCLE_PERIOD=4
+
+# --- Schemes ---
+# (Workspace root for file ops is per-session — supplied at
+# session.create({projectRoot}) or never (headless is forever);
+# stored on sessions.project_root. No env-level default.)
+
+# --- Git integration ---
+# PLURNK_SERVICE_GIT_ALLOWED — hard ceiling for git membership + integration (repo telemetry,
+# EXEC[git]). =1 permits it (then declared repos + per-session config decide; a client
+# may deny its own session via session.create settings.git:false, #232); =0 flatly
+# denies it service-wide, un-re-enableable (the sandbox/benchmark lockout).
+PLURNK_SERVICE_GIT_ALLOWED=1
+# PLURNK_SERVICE_GIT_AUTO — default repo declaration. =1 auto-declares an implicit `repo` at
+# project_root (no-op when it isn't a git tree); =0 declares nothing — clients add
+# repos explicitly via the `repo` overlay. SPEC §membership forest.
+PLURNK_SERVICE_GIT_AUTO=1
+
+# --- Reference docs (auto-READ at turn 1) ---
+# PLURNK_SERVICE_MD_<ALIAS>=<path> materializes <path>'s markdown as a plurnk://<ALIAS>.md
+# entry the model READs at turn 0 — an idiomatic way to inject standing context
+# (an ordinary entry + READ op, not a bespoke packet section). ~ expands to home;
+# relative paths resolve against the package root. A client may add its own docs
+# per session via session.create settings.mdDocs (content, not a path); those UNION
+# with these env docs, keyed by alias — the client wins a collision (#231).
+# Commented out = no docs by default. (The operating policy is NOT a doc: readSystemPolicy
+# already renders ~/.plurnk/AGENTS.md as the ## Plurnk Service Policy section — pointing a
+# PLURNK_SERVICE_MD_* alias at it injects the same file twice.)
+# Turn-0 catalog preview, FIND-served (foisted as FIND(<scheme>:///**) per scheme) so a run
+# opens oriented, not blank. The model's OWN surface — known/unknown (memory), run (scratch),
+# plurnk (docs) — always foists FULL when the preview is on, never truncated: a partial view of
+# the model's own memory reads as withheld. This knob's first-N cap applies ONLY to the FILE list
+# (FIND(file:///**)), the one catalog that's external and arbitrarily large: -1 = the whole tree
+# (everything full); N = the first N files (memory still full); 0 = preview off entirely (the model
+# FINDs on demand). Servicewide default; a client overrides per session via session.create
+# settings.filesItems (#231).
+PLURNK_SERVICE_FILES_ITEMS=-1
+
+# Session-tier ceiling on CONCURRENT active runs (a run with a non-terminal loop)
+# — the fork-bomb / destabilization brake. -1 = no cap (default); only concurrency
+# is bounded, never lifetime, since sessions persist for months. A spawn/fork past
+# the ceiling fails hard (508 — no queue, no retry); the acting run counts itself.
+PLURNK_SERVICE_SESSION_RUNS_MAX_ACTIVE=-1
+
+# --- The window partition (§tokenomics-window-partition) — PER ALIAS (#352) ---
+# The window splits WITHOUT remainder: promptBudget = min(CTX, real window) − REASONING −
+# ASSISTANT − SAFETY is what the service may send; REASONING+ASSISTANT is the generation
+# envelope (max_tokens on every call — no decode is unbounded); SAFETY covers chat-template
+# overhead. The prompt ceiling is DERIVED, never set directly.
+#
+# Each knob resolves PER ALIAS: PLURNK_SERVICE_<KNOB>_<alias> wins over the bare fallback.
+# The BARE defaults are CLOUD-GENEROUS — a large envelope the backend self-clamps to its true
+# output limit (cloud backends accept 65536, silently clamp an absurd ask; no models-API exposes
+# a max-output field, so "send generous, let the backend clamp" is the honest cloud posture).
+# This makes connecting a cloud reasoner a zero-config on-ramp: a DeepSeek-V4 that burns ~16k on
+# reasoning alone gets the headroom to finish its DSL instead of dying at finish=length (#351).
+PLURNK_SERVICE_CTX=163840
+PLURNK_SERVICE_REASONING=16384
+PLURNK_SERVICE_ASSISTANT=49152
+PLURNK_SERVICE_SAFETY=1024
+#
+# LOCAL aliases (llama-server) MUST keep a MEASURED envelope: llama-server honors n_predict to
+# the context wall, and an unbounded decode wall-runs into 30k+ junk tokens (providers#10 — the
+# reason the cap doctrine exists). The tinkerer with a graphics card UNCOMMENTS a block keyed to
+# their alias and their model's real n_ctx (example alias name 'myalias'; a local model
+# run under the bare cloud-generous defaults fails HARD at build with a remedy naming these knobs):
+# PLURNK_SERVICE_CTX_myalias=78848
+# PLURNK_SERVICE_REASONING_myalias=4096
+# PLURNK_SERVICE_ASSISTANT_myalias=8192
+# PLURNK_SERVICE_SAFETY_myalias=1024
+# COUPLING (F7): per-request numeric reasoning budgets are IGNORED by llama-server — a local
+# thinking model's serving box MUST clamp via --reasoning-budget = its PLURNK_SERVICE_REASONING_<alias>,
+# or the reserve is fiction. The service warns at boot. A local alias whose partition contradicts
+# its real window fails HARD at build time, naming the per-alias knobs to set.
+
+# PLURNK_SERVICE_VERSION_POLL_TTL — how long (ms) discover caches its npm-registry version poll
+# (service + client `latest`) before a background refresh. Best-effort; the poll never
+# blocks discover, and offline/registry-down omits `latest`. ~hourly is plenty. #235
+PLURNK_SERVICE_VERSION_POLL_TTL=3600000
+# Grammar-constrained sampling: SELECTS the GBNF variant the provider constrains every
+# generate() to, so capable backends can only sample valid plurnk DSL. A bare name
+# (plurnk.gbnf) is a variant shipped by @plurnk/plurnk-grammar; a path is your own; =0
+# (or empty) disables.
+#
+
+
+# --- Plugins (third-party trust) ---
+# (PLURNK_PLUGINS_TRUSTED_ONLY moved to @plurnk/plurnk-plugins — reader-declares: the
+# trust rule's one implementation lives there and so does its knob.)
+
+# PLURNK_SERVICE_DOCS_EXCLUDE — comma list of scheme/exec names dropped from BOTH the teaching oneliner
+# and the materialized pull-doc on load. The self-evident (plurnk/file) + retired (exec) names the
+# model needs no doc for. Empty → exclude nothing. Unknown names are inert (a filter, not a contract).
+PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
+
+# PLURNK_SERVICE_PACKET_INJECT — an operator markdown file injected as a section right after the teaching
+# (the cached prefix). Read per-turn (live edits); a set-but-unreadable path fails the turn HARD.
+# `~/` expands to home. Unset → no section. The pressure valve for "improve the packet" without a fork.
+# PLURNK_SERVICE_PACKET_INJECT="~/injection.md"
+
+# PLURNK_SERVICE_POLICY — the operating-policy markdown, rendered as the ## Plurnk Service Policy
+# section. Unset = the seeded ~/.plurnk/AGENTS.md; a path = that file; EXPLICITLY empty = policy off.
+# 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=
+
+# --- Semantic search (~query chunking) ---
+# Project Semantics tiles each entry into <=window chunks so a large body is fully
+# searchable, not truncated. ACTIVE only when the installed embedder reports its
+# tokenizer; otherwise one whole-entry chunk (today's behavior). Both knobs are read
+# only when chunking is active.
+# 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
+# granularity); it is clamped to the window either way.
+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
+# =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 fast test lane sets it in .env.test.
+PLURNK_SERVICE_EMBED_DISABLE=0

package/INSTALL.md

@@ -0,0 +1,69 @@
+# Configuring plurnk-service
+
+Agent guide. Read this, then generate a `~/.plurnk/.env` fit to the user's box and intent. `.env.defaults` is the terse machine floor — the authoritative flag list and defaults (the ASSEMBLED catalog of every installed package's file lands at `~/.plurnk/.env.defaults`); this is its reasoning layer. Every claimed coupling below is enforced by a `test/intg` check, so it is current with the installed version.
+
+## Install
+
+```
+npm install -g @plurnk/plurnk-service
+plurnk-service start          # `migrate` first if the DB is uninitialized
+```
+
+First run creates `~/.plurnk/`: `.env` (yours, seeded once with a model picker — **edit this**), `AGENTS.md` (the operating policy, yours), `.env.defaults` + `INSTALL.md` (package-owned references, **refreshed every boot** — never edit them). No model ships active; a fresh daemon runs until `PLURNK_MODEL` is set.
+
+Optional vector search: `npm i @plurnk/plurnk-mimetypes-embeddings` (heavy native deps). Absent → `~query` degrades to FTS keyword ranking.
+
+## The cascade (where a value actually comes from)
+
+Lowest precedence first; the last writer wins:
+
+1. **the assembled `.env.defaults` floor** — every installed package's shipped file, one owner per key (a collision crashes boot naming both), evolves with the installed versions.
+2. **`~/.plurnk/.env.defaults`** — the readable assembled legend, regenerated each boot (a reference, not a place to edit).
+3. **`~/.plurnk/.env`** — the user's home config, seeded once, theirs to keep. **Write generated config here.**
+4. **`./.env`** — per-project, current working directory.
+5. **`--env-file=<path>` / `--config=<path>`** — explicit layers.
+6. **shell environment** — beats every file.
+7. **`--<flag>` CLI args** — top layer, overrides all.
+
+CLI flags are the **1:1 mirror** of the env vars: strip `PLURNK_`, lowercase, `_`→`-`. `PLURNK_SERVICE_MAX_TURNS` ↔ `--service-max-turns`; `PLURNK_MODEL` ↔ `--model`. The flag surface and `--help` are generated from the service's `.env.defaults`, so a var and its flag never diverge. Feature-flag bools are `=== "1"` exactly (never `"true"`); `~/` expands to home.
+
+## The prefix law (who owns a flag)
+
+The prefix is the **owning package**: `PLURNK_SERVICE_*` (this daemon), `PLURNK_PROVIDERS_*`, `PLURNK_MIMETYPES_*`, `PLURNK_EXECS_*`, `PLURNK_SCHEMES_HTTP_*`, `PLURNK_AGUI_*` (the AG-UI module's own knobs), `PLURNK_CLIENT_*` (the CLI). **Bare `PLURNK_*` is reserved** for the front-door + cross-package set no single package owns: `PLURNK_MODEL[_*]`, `PLURNK_BASEURL_*`, `PLURNK_HOST`/`PLURNK_PORT` (the connection rendezvous), and `PLURNK_PLUGINS_TRUSTED_ONLY` (the cross-family plugin gate). Vendor keys (`OPENAI_API_KEY`, `FIREWORKS_API_KEY`…) are vendor conventions — untouched.
+
+A bare flag is a signal: more than one component depends on it. A prefixed one is single-owner. When a flag is `REQUIRED`, an unset or old-named value **fails the boot loudly** naming the var — never a silent default.
+
+## Couplings (the edges an agent gets wrong)
+
+These are relationships *between* flags. Set them as a unit.
+
+- **The window partition is exact.** `promptBudget = min(PLURNK_SERVICE_CTX, real window) − REASONING − ASSISTANT − SAFETY`; `REASONING + ASSISTANT` is the per-call `max_tokens`. Shipped invariant: any window ≥ 77Ki partitions to **exactly 65536** prompt tokens (`78848 − 4096 − 8192 − 1024`). Reserves exceeding the window fail the boot. *(Pinned: `Engine.budget` / `shipped-defaults`.)*
+- **Reasoning capacity is one number in three places.** `PLURNK_SERVICE_REASONING` (the partition's reserve) **must equal** `PLURNK_PROVIDERS_THINKING_CAPACITY` (the provider's thinking cap) **must equal** the serving box's `--reasoning-budget` launch flag. llama-server ignores per-request numeric budgets, so only the launch flag clamps it; a mismatch makes the reserve fiction. The daemon warns at boot when thinking is on. *(Pinned: `shipped-defaults` asserts the first equality.)*
+- **Grammar rails ship on, gated on the provider's claim (#336).** A backend that doesn't enforce grammars drops it cleanly — the daemon boots with a notice, unconstrained on that alias. A backend that CLAIMS enforcement (`constrainsOutput`) is **verified end-to-end at boot** and fails hard if it returns unconstrained output. Daemon-global — not alias-scoped (one backend per daemon). For a known llama-server alias, pin `PLURNK_PROVIDERS_LLAMA_SERVER_<alias>=1` — it transports the grammar deterministically instead of probing `/v1/models` (a probe race once silently disabled the rails). *(Pinned: `grammar-enforcement-verify`.)*
+- **A think-trained model must think somewhere.** `PLURNK_PROVIDERS_THINKING=off` reroutes a reasoning model's thought into the grammar's legal free zone as prose. Keep it `on` with a capacity; providers auto-clamp thinking on in-band grammar backends, so one setting is right everywhere.
+
+## 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_LLAMA_SERVER_local=1`, thinking `on`/`4096` **with the box launched `--reasoning-budget 4096`**. Full rails, exact tokenization.
+- **Cloud, bring-your-own-key.** `PLURNK_MODEL_cloud="openrouter/<model>"`, `OPENROUTER_API_KEY=…`, `PLURNK_MODEL=cloud`. No `LLAMA_SERVER` pin (not llama-server); a `response_format`-grammar backend auto-clamps thinking to none.
+- **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.
+
+## Flag sections (breakdown of the service's `.env.defaults`)
+
+Each mirrors a `# --- section ---` in the floor; consult the floor for exact defaults.
+
+- **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`, `_MIN_CYCLES`, `_MAX_CYCLE_PERIOD`, `_RPC_TIMEOUT`, `_LOOP_TIMEOUT`, `_PROPOSAL_TIMEOUT_MS`, `_EXEC_WAIT_MS`, `_EXEC_KILL_GRACE_MS`, `_SESSION_RUNS_MAX_ACTIVE`. Guardrails; the shipped values are sane.
+- **Git** — `PLURNK_SERVICE_GIT_ALLOWED` (0 = hard sandbox lockout), `_GIT_AUTO`.
+- **Packet / reference docs** — `PLURNK_SERVICE_FILES_ITEMS` (turn-1 file catalog cap), `_PROMPT_PREVIEW_CHARS`, `_DOCS_EXCLUDE`, `_PACKET_INJECT` (operator markdown section), `_POLICY`/`_PROJECT`/`_REQUIREMENTS` (policy + footer overrides; unset = the seeded/packaged defaults), `_MD_<alias>` (inject a markdown doc as a turn-0 entry).
+- **Providers** — `PLURNK_PROVIDERS_THINKING`/`_THINKING_CAPACITY`, `_TEMPERATURE`, `_REPEAT_PENALTY`, `_FETCH_TIMEOUT`, `_RETRY_ATTEMPTS`/`_RETRY_DELAY`, `_PROBE_ATTEMPTS`/`_PROBE_DELAY`, `_GBNF` (grammar variant), `_LLAMA_SERVER_<alias>`, `_CONTEXT_SIZE`, `_GBNF_DEBUG`. Alias-scopable: any knob takes a `_<alias>` suffix that wins over the bare fallback.
+- **The window partition** — `PLURNK_SERVICE_CTX`/`_REASONING`/`_ASSISTANT`/`_SAFETY` (see Couplings).
+- **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).
+- **Schemes: http** — `PLURNK_SCHEMES_HTTP_FETCH_TIMEOUT`/`_SALVAGE_MIN_BODY_CHARS`/`_IDLE_TIMEOUT` (required on the HTML render path), optional Playwright/Chromium knobs.
+- **Execs** — `PLURNK_EXECS_<runtime>=0` disables a runtime; `PLURNK_EXECS_MCP_<server>` bridges an MCP server; `PLURNK_EXECS_SEARCH_SEARXNG_URL` enables web search (unset = search off).
+
+The client's own knobs live under `PLURNK_CLIENT_*` (`--session`, `--run`, `--yolo`, `--json`…) — see `plurnk --help`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 plurnk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# plurnk-service
+
+LLM agent runtime engine. Consumes [plurnk-grammar](https://github.com/plurnk/plurnk-grammar); exposes WebSocket JSON-RPC. User-facing CLI: [plurnk](https://github.com/plurnk/plurnk). Provider-agnostic, MIT — no vendor or model lock-in.
+
+## What an agent can do
+
+Grammar ops: `PLAN` reason · `READ`/`EDIT` files · `FIND` search · `EXEC` run shell/code · `SEND` message or conclude · `COPY`/`MOVE`/`KILL` manage · `OPEN`/`FOLD` curate its own context.
+
+Over schemes: `file://` project files · `exec://` command output · `http(s)://` web fetch · `run://` sibling agent runs (spawn / fork / message) · `known://` scratch · `log://` own history.
+
+## Loop model
+
+Session = the shared world (one filesystem + membership overlay). Run = one agent's private log. Loop = one `prompt → ops → SEND[terminal]` cycle; every turn leads with `PLAN`. Runs fork and message each other — many clients, many runs, one session.
+
+## Integration (WebSocket JSON-RPC)
+
+Methods: `session.*` (create / attach / constrain / list…) · `loop.run` / `loop.inject` / `loop.resolve` · `op.*` (read / edit / find / exec / send…) · `log.read` · `run.fork`. Streams: `log/entry` → … → `loop/terminated`, plus `loop/proposal`, `telemetry/event`. Full live catalog: the `discover` RPC.
+
+```
+ws connect → session.create({ projectRoot }) → loop.run({ prompt })
+           → read log/entry notifications until loop/terminated
+```
+
+The human CLI over this surface is [plurnk](https://github.com/plurnk/plurnk).
+
+## Run
+
+```
+npm install -g @plurnk/plurnk-service
+plurnk-service start      # daemon (`migrate` initializes the DB)
+```
+
+Config + state live in `~/.plurnk/` (created on first run): put your config in `~/.plurnk/.env` (yours, seeded once); the DB defaults to `~/.plurnk/plurnk.db`. Provider-agnostic — point `PLURNK_MODEL` at any vendor. **[`INSTALL.md`](./INSTALL.md) is the config guide** — the cascade, the prefix taxonomy, the coupling matrix, and profiles for common deployments; `.env.defaults` is the terse machine floor it breaks down (per-package, assembled at boot). Also exports `{ Engine, Daemon, SchemeRegistry }` for in-process embedding.
+
+## Contract & siblings
+
+- [`SPEC.md`](./SPEC.md) — canonical specification. One `§<tag>` namespace; anchors `{§<tag>}` bind 1:1 to `test/intg/spec-anchors.test.ts`.
+- [plurnk-providers](https://github.com/plurnk/plurnk-providers) §provider · [plurnk-schemes](https://github.com/plurnk/plurnk-schemes) §scheme-surface · [plurnk-mimetypes](https://github.com/plurnk/plurnk-mimetypes) §mimetype-surface · [plurnk-execs](https://github.com/plurnk/plurnk-execs) §bundled-set.
+
+## Semantic search
+
+`FIND`'s `~query` ranks semantically via an optional embedder peer, `@plurnk/plurnk-mimetypes-embeddings` (heavy native deps; not installed by default). Absent → `~query` falls back to FTS keyword ranking and `start` prints an `embedder inactive` notice. Enable vector search: `npm i @plurnk/plurnk-mimetypes-embeddings`.
+
+## Tests
+
+`test:lint`, `test:unit`, `test:intg`, `test:live`, `test:demo`; off-hot-path `test:installation`.