@plurnk/plurnk-service 1.28.0 → 2.0.0

package/.env.defaults

@@ -163,10 +163,13 @@ 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
+# rest stays readable at reasoning://. Unset/empty = the shared page, PLURNK_SERVICE_PREVIEW_LINES.
+# PLURNK_SERVICE_REASONING_TRAILING_LINES=40
 # 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.
@@ -183,19 +186,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.
@@ -216,12 +211,6 @@ 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

package/INSTALL.md

@@ -42,6 +42,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 +96,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 +104,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 +177,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 +193,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
 ```
 
@@ -50,9 +50,12 @@ 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.
 
-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 +70,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