@plurnk/plurnk-service 1.29.0 → 3.0.0

package/.env.defaults

@@ -35,18 +35,11 @@ PLURNK_SERVICE_SQLITE_READERS=0
 
 # --- Permissions and membership ---
 # CapabilityPolicy JSON: deny removes matching demands; only admits only matches.
-# Workspace, Worker, and loop policies may narrow this ceiling, never widen it.
+# Workspace policy 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.
+# Proposal settlement: review asks the worker's owner; accept or reject settles in core.
+# Review without a capable owner rejects. Disconnect alone never removes that capability.
 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.
@@ -57,6 +50,8 @@ PLURNK_MEMBERS_ENABLED=1
 # PLURNK_MEMBERS_docs=docs/**
 # PLURNK_MEMBERS_no_locks=!**/*.lock
 # PLURNK_MEMBERS_docs_ENABLED=0
+# Any alias: its glob, and its own _ENABLED control.
+# PLURNK_MEMBERS_<alias>=<glob>
 # 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.
@@ -71,11 +66,12 @@ PLURNK_SERVICE_FILE_MATERIALIZE_MAX_BYTES=104857600
 # --- Loop limits and recovery ---
 # Default child model: alias or provider/model. Unset = inherit the spawning loop's model.
 # PLURNK_MODEL_CHILD=fast
-# Model calls across the worker tree, including BARE and resumes; -1 = unlimited. Clients may tighten it.
+# 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.
 PLURNK_SERVICE_MAX_COMMANDS=-1
-# Concurrent nonterminal runs per workspace; -1 = unlimited. Excess spawns return 508, not a queue.
+# Concurrent live workers per workspace; -1 = unlimited. Excess spawns return 508, not a queue.
 PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=-1
 # Active execution allowance per task, positive ms; WAIT pauses it, wakes retain it. Exhaustion: 504.
 PLURNK_SERVICE_LOOP_TIMEOUT=86400000
@@ -83,8 +79,8 @@ PLURNK_SERVICE_LOOP_TIMEOUT=86400000
 PLURNK_SERVICE_LIVE_TIMEOUT=600000
 # End-to-end shutdown budget, positive ms; includes database and listener cleanup.
 PLURNK_SERVICE_STOP_TIMEOUT_MS=30000
-# Provider recovery window, ms; 0 = no reissue. Expiry parks attended loops until a prompt/wake;
-# unattended loops conclude and BARE returns the provider failure.
+# Provider recovery window, ms; 0 = no reissue. Expiry parks workers with a reviewer;
+# without one the loop concludes. BARE returns the provider failure.
 PLURNK_SERVICE_PROVIDER_RECOVERY=900000
 # First recovery delay, ms; doubles on failure up to PROVIDER_RECOVERY_BACKOFF_MAX below.
 PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF=5000
@@ -163,9 +159,8 @@ PLURNK_SERVICE_BUDGET_LARGEST_ITEMS=5
 PLURNK_SERVICE_PREVIEW_LINES=100
 # Independent bound on the same page, Unicode code points; CRLF counts as one separator.
 PLURNK_SERVICE_PREVIEW_CHARS=16000
-# The model's memory of its own thinking ({§reasoning-row}): 1 lands each model turn's reasoning as a row of its
-# own, immediately before the turn's emission row, whole, when the packet has room for it after everything else;
-# without room no row lands and nothing else changes. 0 lands nothing.
+# 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
 # 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
@@ -187,19 +182,11 @@ PLURNK_SERVICE_FILES_ITEMS=-1
 
 # --- Teaching and skills ---
 # Scheme names omitted from discoverable references, comma-separated; empty = none.
-# Executable docs instead follow tool enablement. Plugin trust lives in plurnk-meta's defaults.
+# Executable docs instead follow tool enablement. Extension trust lives in plurnk-meta's defaults.
 PLURNK_SERVICE_DOCS_EXCLUDE="plurnk,file,exec"
 # Skills, plugin and standalone MCP configuration roots, comma-separated, nearest first: project
 # (the workspace project's .agents), plurnk ($XDG_CONFIG_HOME/plurnk), global (~/.agents).
 PLURNK_SERVICE_ROOTS=project,plurnk,global
-# Agent Skills: whole source definitions override discovered skills by their exact standard name.
-# `_` in a key represents `-`; Unicode names work in .env or via `env 'KEY=value' command`.
-# PLURNK_SKILLS_code_review={"name":"code-review","source":"/srv/skills/code-review"}
-# Declared and discovered skills default enabled; per-name controls override this default.
-PLURNK_SKILLS_ENABLED=1
-# PLURNK_SKILLS_code_review_ENABLED=0
-# Deadline for one skills source fetch (git ls-remote, git clone, tar, unzip), positive ms.
-PLURNK_SERVICE_SKILLS_FETCH_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.
@@ -220,17 +207,11 @@ 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
 
-# --- Forensic interviews ---
-# Initial requiem output allowance, tokens; used only for requested out-of-band interviews.
-PLURNK_SERVICE_REQUIEM_MAX_TOKENS=16384
-# Retry allowance for empty length-limited testimony; must be at least the initial allowance.
-PLURNK_SERVICE_REQUIEM_RETRY_MAX_TOKENS=32768
-
 # --- Retention: information is kept; transient data is collected ({§retention-policy}) ---
 # Packet compositions kept per loop, newest first; -1 = every packet, forever.
 PLURNK_SERVICE_RETAIN_PACKET_TURNS=-1
 # Packet compositions kept by age, ms since the turn completed; -1 = no age limit. Thirty days:
-# no session reads its own packets back that late, and a daemon left running for months stops growing.
+# no worker reads its own packets back that late, and a daemon left running for months stops growing.
 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.

package/INSTALL.md

@@ -33,8 +33,9 @@ or enables the unit.
 | Plurnk-only MCP servers | `$XDG_CONFIG_HOME/plurnk/mcp.json` |
 
 Use `plurnk-service config` for paths and precedence, `config edit` to edit the
-user file, and `config check` to validate it. An old `~/.plurnk` is not read
-implicitly; `plurnk-service paths migrate` relocates it with the daemon stopped.
+user file, and `config check` to validate it. A `PLURNK_*` key that file sets and
+no installed package declares is named at startup and by `config check`, which
+still passes; `config defaults` lists every declared key.
 
 Invalid optional configuration stays visible without removing the repair environment.
 `config check` is strict; ordinary startup keeps unrelated capabilities and client
@@ -42,6 +43,42 @@ inspection available. Model providers are constructed and verified on selection
 first use, not on startup. An invalid default never selects a different model:
 choose a valid model in the client or correct the daemon's configuration.
 
+## Backup and restore
+
+The database holds worker history and workspace state. Its default path is in
+the table above; `PLURNK_SERVICE_DB_PATH` overrides it, and
+`PLURNK_SERVICE_STATE_ROOT` relocates the default. Back up the actual daemon's
+database, not a different client's default.
+
+Use SQLite's consistent-copy operation while the daemon is running **or** stopped
+({§share-snapshot}). Copying only a live `.db` can omit committed data still in
+its `-wal` file; copying those files separately is not a consistent snapshot.
+This example uses Node, already required by Plurnk, and the default XDG path.
+Choose a new destination for each backup:
+
+```sh
+(
+  umask 077
+  node --input-type=module -e '
+    import { DatabaseSync } from "node:sqlite";
+    const db = new DatabaseSync(process.argv[1], { readOnly: true });
+    try { db.prepare("VACUUM INTO ?").run(process.argv[2]); }
+    finally { db.close(); }
+  ' "${XDG_DATA_HOME:-$HOME/.local/share}/plurnk/plurnk.db" "$HOME/plurnk-backup.db"
+)
+```
+
+Keep backups private: they include prompts, reasoning, and recorded tool output.
+Back up project files, configuration, and extension-owned files separately; a
+database snapshot does not copy them. `plurnk-service share` produces diagnostic
+artifacts from a temporary snapshot and then removes that snapshot; it is not
+a substitute for this backup.
+
+To restore, stop the daemon and retain its old database and any `-wal`/`-shm`
+sidecars together. Copy the backup to a fresh working path, select that path with
+`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.
+
 ## Precedence
 
 Highest priority first ({§operator-config-precedence}):
@@ -60,7 +97,7 @@ variables reach its commands through the workspace environment (`/env import .en
 
 For a service-owned variable, strip `PLURNK_`, lowercase, and replace `_` with
 `-` to obtain its CLI flag: `PLURNK_SERVICE_MAX_TURNS` → `--service-max-turns`.
-Plugin settings remain environment/configuration values; they do not extend the
+Extension settings remain environment/configuration values; they do not extend the
 service CLI. Boolean flags use `1` and `0`. An empty value is not an unset value;
 the owning declaration specifies its meaning.
 
@@ -68,7 +105,7 @@ the owning declaration specifies its meaning.
 
 | Change | Owner and effect |
 | --- | --- |
-| Startup defaults or installed plugin configuration | The daemon's environment cascade. A remote client's shell does not change it. |
+| 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. |
 | Command environment | `env` manages worker overrides or workspace defaults. It does not reconfigure the daemon; running processes keep their launch environment. |
@@ -141,12 +178,13 @@ Configuration provenance names the definition's environment key, discovered
 `SKILL.md` path, or MCP JSON file and JSON Pointer, not a dotenv file or shadowed history. Local overrides are
 workspace-owned; removing one exposes its current inherited source again.
 
-## Native extensions
+## Extensions
 
-Standard [Agent Plugins](https://agent-plugins.org/specification) keep their portable
-skills and MCP servers and may add one native capability under `extensions.ai.plurnk`.
-That declaration uses the family's existing loader and lifetime. For daemon lifecycle
-hooks, declare a module:
+An extension is native Plurnk code of one kind, declared once: under `plurnk` in an npm
+package's `package.json`, or under `extensions.ai.plurnk` in a standard
+[Agent Plugin](https://agent-plugins.org/specification)'s `plugin.json`, beside the plugin's
+portable skills and MCP servers. Its kind's framework loads it with that kind's lifetime. A
+module joins the daemon lifecycle:
 
 ```json
 {
@@ -156,15 +194,28 @@ hooks, declare a module:
 }
 ```
 
-Daemon modules load at startup from installed npm packages and selected user roots:
+An npm package declares the same module in its own manifest, naming an export subpath so the
+package's export conditions select its entry:
+
+```json
+{
+  "name": "@example/plurnk-module",
+  "exports": { "./module": "./dist/module.js" },
+  "plurnk": { "kind": "module", "module": "./module" }
+}
+```
+
+Modules load at startup from installed npm packages and selected user roots:
 `$XDG_CONFIG_HOME/plurnk/plugins/` before `~/.agents/plugins/`, then npm. The manifest name
 identifies a plugin across those sources. Project plugins never load native code into the daemon.
-`PLURNK_SERVICE_ROOTS` selects the directory roots; `PLURNK_PLUGINS_TRUSTED_ONLY` governs native
-imports, using the npm package name when present or the plugin name otherwise.
-Other native families (executors, schemes, providers, mimetypes and HTTP materializers)
+`PLURNK_SERVICE_ROOTS` selects the directory roots; `PLURNK_EXTENSIONS_TRUSTED_ONLY` governs
+extension imports, using the npm package name when present or the plugin name otherwise.
+Other extension kinds (executors, schemes, providers, mimetypes and HTTP materializers)
 require npm installation and retain their own loading behavior.
 
-The module exports a lifecycle object or a no-argument factory. `setup` registers capabilities;
-`stop` drains producers; `close` releases registrations and observers. See {§module-lifecycle}.
-Native files and the optional configuration panel live under `ai.plurnk/`; its `.env.defaults`
-joins the ordinary floor. npm owns dependencies and delivery, not a second native declaration.
+A module exports a lifecycle object or a no-argument factory: `setup` registers what it
+contributes, `start` opens its ingress, `stop` drains its producers, and `close` releases its
+registrations and observers. Extension files and the optional configuration panel live under
+`ai.plurnk/`; its `.env.defaults` joins the ordinary floor. npm owns dependencies and delivery,
+not a second extension declaration. [Extending Plurnk](skill://plurnk/references/extensibility.md)
+covers every integration surface and links each kind's contract.

package/README.md

@@ -34,7 +34,7 @@ reports the choices shared by a worker's selected model and spawn override.
 
 ```sh
 npm install -g @plurnk/plurnk-service
-plurnk-service migrate    # apply the disposable schema baseline (its chapters, in order)
+plurnk-service migrate    # apply pending database upgrades, preserving existing data
 plurnk-service start      # daemon
 ```
 
@@ -47,12 +47,14 @@ Configuration follows XDG at `$XDG_CONFIG_HOME/plurnk` (normally
 `plurnk-service config defaults` for
 the complete installed option catalog and `plurnk-service config check` to
 validate without contacting a provider. **[`INSTALL.md`](./INSTALL.md) is the
-configuration guide.** A legacy mixed `~/.plurnk` is moved only by the explicit
-`plurnk-service paths migrate` command.
+configuration guide.**
 
-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`.
+Protect durable history with a [consistent database backup](./INSTALL.md#backup-and-restore).
+The `share` command exports diagnostic reports, not a restorable database.
+
+Clients use AG-UI; extension authors use the owning framework packages.
+Programmatic forensic use imports [`@plurnk/plurnk-digest`](../plurnk-digest/README.md)
+with the canonical reader from `@plurnk/plurnk-service/evidence`.
 The digest requires a new or empty output directory, separate from its input
 database. Existing output and overlapping input/output paths are refused.
 
@@ -67,7 +69,7 @@ database. Existing output and overlapping input/output paths are refused.
 
 ## Observability
 
-The daemon can emit OpenTelemetry traces and low-cardinality metrics through the standard `OTEL_*` environment ({§observability-boundary}): `OTEL_TRACES_EXPORTER` / `OTEL_METRICS_EXPORTER` select `otlp` or `console` per signal, `OTEL_SERVICE_NAME` names the service, and `OTEL_SDK_DISABLED` opts out. Unconfigured, the daemon never loads the SDK. The boundary observes lifecycle (workspace, loop, turn, provider, parse, dispatch, proposal, stream, digest) without ever recording prompts, reasoning, file bodies, URLs, secrets, or plugin payloads.
+The daemon can emit OpenTelemetry traces and low-cardinality metrics through the standard `OTEL_*` environment ({§observability-boundary}): `OTEL_TRACES_EXPORTER` / `OTEL_METRICS_EXPORTER` select `otlp` or `console` per signal, `OTEL_SERVICE_NAME` names the service, and `OTEL_SDK_DISABLED` opts out. Unconfigured, the daemon never loads the SDK. The boundary observes lifecycle (workspace, loop, turn, provider, parse, dispatch, proposal, stream, digest) without ever recording prompts, reasoning, file bodies, URLs, secrets, or extension payloads.
 
 ## Full-text search