@plurnk/plurnk-service 1.16.5 → 1.18.0

package/docs/env.md

@@ -0,0 +1,55 @@
+# env
+
+Every command you run receives a composed environment, never the host's. The
+ambient names are what the operator's ceiling admits; your own entries sit above
+them, and both are yours to shape. `list` shows exactly what your next command
+will see, each value with its origin.
+
+## Your entries
+
+`add` sets one variable for every command you run from now on. The name is the
+alias, `{ "value": "…" }` the definition, used verbatim: no interpolation, no
+escapes. It persists until you `remove` it. This is a registry, not a prefix —
+`CARGO_TARGET_DIR=/tmp/x cargo build` sets a value for one command; `add` sets
+it for all of them.
+
+`disable` withdraws a name from your commands while keeping the entry listed;
+`enable` restores it. For an ambient name that is how `CI=1` goes away for you
+alone, without the operator changing anything. `remove` forgets your own entry;
+an ambient name of the same alias reappears, disabled, so removal never quietly
+changes what your next command sees.
+
+Your entries are yours: another worker's commands do not see them. A worker
+you spawn starts with a copy of them — `list` shows those as inherited from
+you — and its changes never reach yours.
+
+## For one command, or for one child
+
+The heading's `[metadata]` takes `env`. On a command fence it is that run's
+environment, over your entries, and it is gone when the run ends:
+
+````sh [{"env": {"RUST_LOG": "debug"}}]
+cargo test
+````
+
+On `WORK` and `FORK` it is the child's starting environment: the child gets a
+copy of your entries first, then each name here becomes its own, so you hand
+down your registry and override what one child needs in the same line:
+
+````WORK (worker://builder) [{"env": {"CARGO_TARGET_DIR": "/tmp/builder"}}]
+Build the crate and report the warnings.
+````
+
+## Names you cannot set
+
+`PLURNK_*` and provider credential names are plurnk's own and never reach a
+command, so `add` refuses them and tells you why.
+
+## Finding a name
+
+`discover` is this installation's configuration catalog: every knob an installed
+package declares, with the declaring package as its provenance and its own
+comment as the summary. It is not a permissions list — you may set any name —
+it tells you which names have a consumer, and it is how you learn the name of a
+value only the operator can supply. Refer to such a value by its name; you never
+need to see it.

package/docs/members.md

@@ -0,0 +1,83 @@
+# members
+
+Membership is the only door to the project's files. A project file is exactly
+one of three things to this workspace: **tracked by git**, **added** by a
+definition, or **invisible**. Nothing is a member because it exists on disk or
+because git happens not to ignore it. What you can `READ`, `FIND`, and `EDIT`
+is `(tracked ∪ include) − exclude`, and the catalog at turn 0 shows exactly
+that set.
+
+## What makes a file visible
+
+| A file is a member because | How it got there |
+| --- | --- |
+| git tracks it | it was committed or staged (`git ls-files`), refreshed every turn |
+| a definition includes it | an enabled `members` definition — a gitignore-style glob such as `docs/**` |
+| plurnk created it | a file your accepted `EDIT`, `COPY`, or `MOVE` wrote gets an exact creation record; it is a member without any `git add` |
+
+An exclusion (`!glob`) wins over every inclusion. A model definition never
+includes a path the repository ignores.
+
+## What you may change here
+
+Your `add` is admitted against the operator's ceiling
+`PLURNK_SERVICE_MEMBERS_MODEL_SCOPE`, narrowed by the workspace:
+
+| Scope | A model definition may include |
+| --- | --- |
+| `none` | nothing — every `add` from the model is refused `403 model-scope` |
+| `root` | paths inside the project root |
+| `namespace` (shipped default) | those plus canonical `../` paths outside the root |
+
+The scope refuses an `add` you author from a turn; a client's `/members add`
+and the operator's `PLURNK_MEMBERS_<ALIAS>=<glob>` definitions are not bound
+by it. `discover` always works: a path answers why it is or is not visible; a
+glob previews what `add` would resolve to.
+
+## When a file you need is not a member
+
+Ask first: `members (discover)` with `{"query": "build/report.json"}`
+says `tracked`, `included by …`, `a creation record`, `excluded by …`,
+`ignored`, `untracked`, or `absent`.
+
+- **Untracked and you are allowed to add** (`root` or `namespace`): add a
+  definition and it is a member from the next turn.
+
+  ````members (add) <!-- include the generated reports -->
+  {"alias": "reports", "definition": {"glob": "build/*.json"}}
+  ````
+
+- **Untracked and the scope is `none`** (an operator narrowed it): the refusal
+  names the recovery, and it is not a trick — make git track the file. Staging
+  is enough; no commit is needed, and membership refreshes at your next turn.
+
+  ````sh <!-- git tracks it, so it becomes a member -->
+  git add build/report.json
+  ````
+
+  Or ask the user to add it (`/members add`) or to raise the scope. Do not
+  loop on `add`; the scope will not change mid-turn.
+
+- **Ignored by the repository**: no model definition can include it, and
+  `git add` refuses it too. Only a client or operator definition covers an
+  ignored path; say so and ask.
+
+- **Excluded by `!glob`**: an exclusion is deliberate; ask the user before
+  working around it.
+
+## Files you create
+
+An `EDIT` to a path that does not exist creates it when the file-creation
+scope admits it (`PLURNK_SERVICE_FILE_CREATE_SCOPE`, shipped `root`: inside
+the project root only). The new file is a member immediately through its
+creation record — you never need `git add` for your own creations. Deleting
+it (`KILL`) retires the record.
+
+## Definitions belong to the workspace
+
+`list` shows every definition with its origin (`service` from the operator's
+environment, `workspace` from an `add`) and whether it is enabled. `enable` and
+`disable` flip one shared alias; `remove` deletes a workspace-added definition
+(service definitions can only be disabled). Changes apply to every worker.
+Each enabled definition is projected as
+`worker:///_plurnk/members/<alias>.md` showing what its glob resolved to.

package/docs/skills.md

@@ -0,0 +1,50 @@
+# skills
+
+An Agent Skill is a directory holding a `SKILL.md` (standard `name` and
+`description` frontmatter, then instructions) and optionally references,
+scripts, and assets beside it. Skills are how a project or a user hands you
+procedures and tools without pasting them into every conversation. Enabled
+skills appear in the turn-0 catalog as `skill://<name>/SKILL.md`; nothing is
+injected until you `READ` it.
+
+## Where skills come from
+
+| Scope | Root | Who put it there |
+| --- | --- | --- |
+| `project` | `<project root>/.agents/skills/<name>/` | the repository (often committed) |
+| `global` | `~/.agents/skills/<name>/` | the user, for every project |
+| `service` | a tree the service itself provides | plurnk (for example the `plurnk` skill: its own configuration and model reference) |
+
+A `project` skill shadows a `global` one of the same name, which shadows a
+`service` one. Every installed skill is a service-origin definition, enabled
+by default; a disabled skill is invisible to you but still listed for the
+client.
+
+## Read before you install
+
+The instructions are the skill: `READ (skill://<name>/SKILL.md)` for the
+procedure, `FIND (skill://<name>/**)` for its files, and
+`runtime (skill://<name>/scripts/<program>)` to run one of its scripts
+under the ordinary proposal policy. Skill resources are read-only; you do not
+`EDIT` an installed skill.
+
+Reach for `discover` when the task names a capability no enabled skill
+provides: `{"query": "..."}` searches the standard registry and returns one
+candidate per hit with its exact `owner/repo` source; `{"source": "owner/repo"}`
+lists the skills one package contains. Discovery never installs anything.
+
+## Installing
+
+`add` installs a skill through the standard installer and enables it:
+
+````skills (add) <!-- from a discover candidate -->
+{"alias": "sql-formatter", "definition": {"name": "sql-formatter", "scope": "project", "source": "example/skills"}}
+````
+
+The alias must equal the skill's `name`; `source` is required unless the
+directory already exists; `scope: "project"` needs a project root and writes
+under `.agents/skills`. Installation is a host effect, so it proposes and runs
+only on acceptance. A skill that fails to install or has invalid frontmatter is
+listed `unavailable` with its exact Problem — one bad skill never disables the
+family. `remove` uninstalls the workspace-added skill; service skills can only
+be disabled.

package/migrations/001_workspaces.sql

@@ -0,0 +1,53 @@
+-- MIGRATE: 1 workspaces
+-- Chapter 1 of the schema baseline ({§db-schema-baseline}): The workspace: identity, module state, membership constraints.
+-- Version numbers order the chapters on a fresh database; they are not history. A shape
+-- change edits the chapter in place; existing development databases are recreated.
+
+-- workspaces
+-- project_root: workspace pointer. NULL = headless (no disk side-effects);
+-- non-null = absolute path to the client's source tree, supplied at
+-- workspace.create or workspace.set_root.
+CREATE TABLE IF NOT EXISTS workspaces (
+    id                        INTEGER NOT NULL PRIMARY KEY,
+    version                   INTEGER NOT NULL DEFAULT 0 CHECK (version >= 0),
+    name                      TEXT    NOT NULL UNIQUE CHECK (length(name) > 0),
+    created_at                TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    project_root              TEXT,
+    -- {§operator-config} validated client workspace settings; each field composes
+    -- with operator configuration at its owning use site.
+    settings                  TEXT    NOT NULL DEFAULT '{}' CHECK (json_valid(settings))
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS workspaces_created_at ON workspaces (created_at);
+
+-- {§module-workspace-state}: one provider-validated snapshot per workspace.
+CREATE TABLE IF NOT EXISTS workspace_module_state (
+    workspace_id      INTEGER NOT NULL,
+    namespace_owner  TEXT    NOT NULL CHECK (length(namespace_owner) > 0),
+    state             TEXT    NOT NULL CHECK (json_valid(state)),
+    updated_at        TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    PRIMARY KEY (workspace_id, namespace_owner),
+    FOREIGN KEY (workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE
+) STRICT;
+
+-- workspace_constraints
+-- SPEC {§membership} constraint overlay — explicit policy and the inspectable
+-- exact pick produced by accepted file creation share one representation.
+-- Per (workspace, effect, glob/target): `pick` (members git misses, resolved by a
+-- targeted client-dictated scan), `hide` (drop git-tracked matches), `view` (member
+-- for read; File.edit rejects the write). git-absent, `pick` rows are the sole substrate
+-- source. Composed at membership resolution; node:path.matchesGlob.
+CREATE TABLE IF NOT EXISTS workspace_constraints (
+    workspace_id INTEGER NOT NULL,
+    -- include admits files git misses; exclude removes members — the members family's lexicon
+    -- ({§members-projection}). An inclusion is a pattern scan; a creation record is one exact path.
+    effect     TEXT    NOT NULL CHECK (effect IN ('include', 'exclude')),
+    glob       TEXT    NOT NULL,
+    -- create: the exact record of a file Plurnk wrote ({§fs-create-record}); members: a
+    -- human-authored definition projected by the members family; model: a definition the model
+    -- proposed under the members scope — never admitted past the repository's ignore rules.
+    source     TEXT    NOT NULL CHECK (source IN ('create', 'members', 'model')),
+    CHECK (source IN ('members', 'model') OR effect = 'include'),
+    PRIMARY KEY (workspace_id, effect, glob),
+    FOREIGN KEY (workspace_id) REFERENCES workspaces(id) ON DELETE CASCADE
+) STRICT, WITHOUT ROWID;

package/migrations/002_workers.sql

@@ -0,0 +1,198 @@
+-- MIGRATE: 2 workers
+-- Chapter 2 of the schema baseline ({§db-schema-baseline}): Workers over a workspace, their model routes, and the ambient event feed their siblings observe.
+-- Version numbers order the chapters on a fresh database; they are not history. A shape
+-- change edits the chapter in place; existing development databases are recreated.
+
+-- model_routes — the immutable resolved model route ({§worker-model-selection}). One row per
+-- complete resolved tuple; append-only. Alias is provenance plus a tuning scope,
+-- not route identity, and is absent on a direct provider/model selection.
+CREATE TABLE IF NOT EXISTS model_routes (
+    id         INTEGER NOT NULL PRIMARY KEY,
+    alias      TEXT             CHECK (alias IS NULL OR length(alias) > 0),
+    provider   TEXT    NOT NULL CHECK (length(provider) > 0),
+    model      TEXT    NOT NULL CHECK (length(model) > 0),
+    base_url   TEXT             CHECK (base_url IS NULL OR length(base_url) > 0),
+    created_at TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+) STRICT;
+
+CREATE UNIQUE INDEX IF NOT EXISTS model_routes_identity
+ON model_routes (coalesce(alias, ''), provider, model, coalesce(base_url, ''));
+
+-- workers
+CREATE TABLE IF NOT EXISTS workers (
+    id              INTEGER NOT NULL PRIMARY KEY,
+    version         INTEGER NOT NULL DEFAULT 0 CHECK (version >= 0),
+    workspace_id    INTEGER NOT NULL,
+    -- {§loop-wake-identity}: completion events, not packet/log curation state.
+    wake_revision   INTEGER NOT NULL DEFAULT 0 CHECK (wake_revision >= 0),
+    name            TEXT    NOT NULL CHECK (length(name) > 0),
+    created_at      TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    -- {§worker-provider-identity}: provider affinity must not collide when
+    -- independent databases reuse local integer ids.
+    provider_identity TEXT NOT NULL DEFAULT (lower(hex(randomblob(16))))
+        CHECK (length(provider_identity) = 32 AND provider_identity NOT GLOB '*[^0-9a-f]*'),
+    -- {§worker-model-selection}: the worker's durable resolved model, NULL for non-model
+    -- workers or a deliberately modelless unresolved worker. spawn_model_route_id is the
+    -- persistent spawn override; NULL means "use my model."
+    model_route_id       INTEGER          REFERENCES model_routes(id),
+    spawn_model_route_id INTEGER          REFERENCES model_routes(id),
+    -- {§worker-reasoning-policy}: nullable only while the worker has no model;
+    -- once selected, model and reasoning policy form one durable generation policy.
+    reasoning_policy TEXT CHECK (reasoning_policy IS NULL OR length(reasoning_policy) > 0),
+    -- {§worker-reasoning-source}: whether reasoning_policy was chosen (worker.reasoning.set)
+    -- or seeded from the alias configuration; a default never masquerades as a choice.
+    reasoning_source TEXT NOT NULL DEFAULT 'default' CHECK (reasoning_source IN ('default', 'explicit')),
+    -- workers fork via parent_worker_id; workspaces carry no parent — {§machine-processes-no-fork-workspace}
+    parent_worker_id INTEGER          CHECK (parent_worker_id IS NULL OR parent_worker_id != id),
+    origin          TEXT    NOT NULL DEFAULT 'client' CHECK (origin IN ('model', 'client', '_plurnk')),
+    -- {§methods-model-worker}: durable identity for the workspace's stable
+    -- default conversation; separate from its literal name.
+    default_conversation INTEGER NOT NULL DEFAULT 0 CHECK (default_conversation IN (0, 1)),
+    -- {§worker-causal-admission}: cancellation retires unread arrivals without rewriting history.
+    cancelled_through_sequence INTEGER NOT NULL DEFAULT 0 CHECK (cancelled_through_sequence >= 0),
+    -- The Problem the latest cancellation delivered to this worker's live loops; writing it is
+    -- the cancellation ({§worker-cancel-trigger}). NULL until the worker's scope is first cancelled.
+    cancellation TEXT CHECK (cancellation IS NULL OR (json_valid(cancellation) AND json_extract(cancellation, '$.status') = 499)),
+    -- {§env-delta-log-pull}: monotonic observation progress, not a private world snapshot.
+    -- Creation captures the workspace high-water; a fork instead copies its
+    -- parent's cursor and records the closed event boundary of its snapshot.
+    ambient_event_cursor INTEGER      CHECK (ambient_event_cursor IS NULL OR ambient_event_cursor >= 0),
+    fork_event_boundary INTEGER       CHECK (fork_event_boundary IS NULL OR fork_event_boundary >= 0),
+    CHECK (fork_event_boundary IS NULL OR parent_worker_id IS NOT NULL),
+    CHECK (default_conversation = 0 OR (origin = 'model' AND parent_worker_id IS NULL)),
+    CHECK ((model_route_id IS NULL) = (reasoning_policy IS NULL)),
+    FOREIGN KEY (workspace_id)    REFERENCES workspaces(id) ON DELETE CASCADE,
+    FOREIGN KEY (parent_worker_id) REFERENCES workers(id)     ON DELETE CASCADE
+) STRICT;
+
+CREATE        INDEX IF NOT EXISTS workers_workspace_id_created_at ON workers (workspace_id, created_at);
+
+CREATE        INDEX IF NOT EXISTS workers_parent_worker_id         ON workers (parent_worker_id);
+
+CREATE UNIQUE INDEX IF NOT EXISTS workers_provider_identity         ON workers (provider_identity);
+
+CREATE UNIQUE INDEX IF NOT EXISTS workers_workspace_default_conversation
+    ON workers (workspace_id) WHERE default_conversation = 1;
+
+-- {§worker-scheme-spawn}: a retained name cannot be rebound to another actor.
+CREATE UNIQUE INDEX IF NOT EXISTS workers_workspace_name          ON workers (workspace_id, name);
+
+-- {§db-fk-indexes} Foreign-key check paths: without these, updating or replacing a route scans every worker.
+CREATE INDEX IF NOT EXISTS workers_model_route_id       ON workers (model_route_id)       WHERE model_route_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS workers_spawn_model_route_id ON workers (spawn_model_route_id) WHERE spawn_model_route_id IS NOT NULL;
+
+CREATE TRIGGER IF NOT EXISTS workers_provider_identity_immutable
+BEFORE UPDATE OF provider_identity ON workers
+WHEN NEW.provider_identity != OLD.provider_identity
+BEGIN
+    SELECT RAISE(ABORT, 'workers.provider_identity is immutable');
+END;
+
+CREATE TRIGGER IF NOT EXISTS workers_fork_event_boundary_immutable
+BEFORE UPDATE OF fork_event_boundary ON workers
+WHEN NEW.fork_event_boundary IS NOT OLD.fork_event_boundary
+BEGIN
+    SELECT RAISE(ABORT, 'workers.fork_event_boundary is immutable');
+END;
+
+-- {§env-delta-log-pull}: one append-only occurrence journal gives every
+-- producer a shared monotonic order. Audience is structural: direct parent,
+-- explicit workspace broadcast, or their union. The event snapshots exactly
+-- what an observer row needs because source-log curation cannot erase history.
+-- source_record_id is forensic identity for the originating log/loop row, not a
+-- foreign key: model log curation must not erase an already-recorded occurrence.
+CREATE TABLE IF NOT EXISTS ambient_events (
+    id                      INTEGER NOT NULL PRIMARY KEY,
+    workspace_id            INTEGER NOT NULL,
+    producer_worker_id      INTEGER NOT NULL,
+    target_parent_worker_id INTEGER,
+    workspace_broadcast     INTEGER NOT NULL DEFAULT 0 CHECK (workspace_broadcast IN (0, 1)),
+    kind                    TEXT    NOT NULL CHECK (kind IN ('activity', 'loop_termination')),
+    source_record_id        INTEGER NOT NULL CHECK (source_record_id >= 1),
+    at                      TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    source                  TEXT,
+    op                      TEXT    NOT NULL,
+    signal                  TEXT             CHECK (signal IS NULL OR json_valid(signal)),
+    scheme                  TEXT,
+    username                TEXT,
+    password                TEXT,
+    hostname                TEXT,
+    port                    INTEGER          CHECK (port IS NULL OR (port BETWEEN 0 AND 65535)),
+    pathname                TEXT,
+    query                   TEXT,
+    fragment                TEXT,
+    line_marker             TEXT             CHECK (line_marker IS NULL OR json_valid(line_marker)),
+    tx                      TEXT    NOT NULL,
+    mimetype_tx             TEXT    NOT NULL CHECK (length(mimetype_tx) > 0),
+    rx                      TEXT    NOT NULL,
+    mimetype_rx             TEXT    NOT NULL CHECK (length(mimetype_rx) > 0),
+    status_rx               INTEGER NOT NULL CHECK (status_rx BETWEEN 100 AND 599),
+    state                   TEXT    NOT NULL CHECK (state IN ('resolved', 'failed', 'cancelled')),
+    outcome                 TEXT,
+    attrs                   TEXT    NOT NULL DEFAULT '{}' CHECK (json_valid(attrs)),
+    terminated_by           TEXT             CHECK (terminated_by IS NULL OR terminated_by = 'cancel'),
+    CHECK (target_parent_worker_id IS NOT NULL OR workspace_broadcast = 1),
+    CHECK (
+        (kind = 'activity' AND terminated_by IS NULL)
+        OR
+        (kind = 'loop_termination'
+            AND op = 'SEND'
+            -- {§env-delta-child-termination}: a message from the concluded child;
+            -- `source` names the actor and its READ address (#567, operator 2026-09-07).
+            AND scheme IS NULL
+            AND pathname IS NULL
+            AND json_valid(rx)
+            AND json_type(rx) = 'object'
+            AND json_type(rx, '$.status') = 'integer'
+            AND json_extract(rx, '$.status') = status_rx)
+    ),
+    FOREIGN KEY (workspace_id)            REFERENCES workspaces(id) ON DELETE CASCADE,
+    FOREIGN KEY (producer_worker_id)      REFERENCES workers(id)    ON DELETE CASCADE,
+    FOREIGN KEY (target_parent_worker_id) REFERENCES workers(id)    ON DELETE CASCADE
+) STRICT;
+
+CREATE INDEX IF NOT EXISTS ambient_events_workspace_id_id
+    ON ambient_events (workspace_id, id);
+
+-- {§db-index-owners} Producer deletion's foreign-key check walks its events by producer; no registry statement selects by it.
+CREATE INDEX IF NOT EXISTS ambient_events_producer_kind_id
+    ON ambient_events (producer_worker_id, kind, id);
+
+CREATE INDEX IF NOT EXISTS ambient_events_parent_id
+    ON ambient_events (target_parent_worker_id, id)
+    WHERE target_parent_worker_id IS NOT NULL;
+
+CREATE UNIQUE INDEX IF NOT EXISTS ambient_events_source_identity
+    ON ambient_events (producer_worker_id, kind, source_record_id);
+
+CREATE TRIGGER IF NOT EXISTS ambient_events_structural_audience
+BEFORE INSERT ON ambient_events
+WHEN NOT EXISTS (
+    SELECT 1
+    FROM workers producer
+    WHERE producer.id = NEW.producer_worker_id
+      AND producer.workspace_id = NEW.workspace_id
+      AND (
+          NEW.target_parent_worker_id IS NULL
+          OR NEW.target_parent_worker_id = producer.parent_worker_id
+      )
+)
+BEGIN
+    SELECT RAISE(ABORT, 'ambient event audience must be the producer direct parent in the same workspace');
+END;
+
+-- {§module-workspace-state}: the same provider-validated snapshot, owned by a WORKER rather
+-- than a workspace. A family declares which scope its definitions belong to; `env` is the first
+-- worker-scoped one, because an environment is context (how this worker works) rather than
+-- capability (what exists in this workspace). A sibling table rather than a nullable column on
+-- workspace_module_state: the foreign key is real, so a worker's definitions die with it, and
+-- every identity component stays NOT NULL ({§entry-identity-no-null}).
+CREATE TABLE IF NOT EXISTS worker_module_state (
+    worker_id        INTEGER NOT NULL,
+    namespace_owner  TEXT    NOT NULL CHECK (length(namespace_owner) > 0),
+    state            TEXT    NOT NULL CHECK (json_valid(state)),
+    updated_at       TEXT    NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+    PRIMARY KEY (worker_id, namespace_owner),
+    FOREIGN KEY (worker_id) REFERENCES workers(id) ON DELETE CASCADE
+) STRICT;