@plurnk/plurnk-grammar 0.65.0 → 0.68.0

package/plurnk.md

@@ -1,6 +1,6 @@
 # Plurnk System Grammar
 
-YOU MUST ONLY use the Extended HEREDOC Plurnk Operations (FIND|READ|EDIT|COPY|MOVE|OPEN|FOLD|KILL|EXEC|SEND).
+YOU MUST ONLY use the Extended HEREDOC Plurnk Operations (PLAN|FIND|READ|EDIT|COPY|MOVE|OPEN|FOLD|KILL|EXEC|SEND).
 
 ## Syntax
 
@@ -12,6 +12,7 @@ Slots between `<<OPsuffix` and `:body:` are all optional. `:body:` fences are re
 
 | OP   | `[signal]`  | `(target)` | `<Line> / <Result>` | body             |
 |------|-------------|------------|---------------------|------------------|
+| PLAN | -           | -          | -                   | plan / reasoning |
 | FIND | filter tags | required   | results `N,M`       | matcher          |
 | READ | filter tags | required   | lines `N,M`         | matcher          |
 | EDIT | tags        | required   | lines `N,M`         | content          |
@@ -26,7 +27,6 @@ Slots between `<<OPsuffix` and `:body:` are all optional. `:body:` fences are re
 Operations emit their status and/or results on the subsequent turn.
 READ output prefixes every line with line numbers and a hard tab, `N:	`. The prefix is not part of the source.
 EDIT is only for entries. Do not attempt to edit log items.
-SEND broadcasts to uri when a path is included and messages the user when no path is included.
 EXEC defaults to `sh`; override with an optional executor (`sqlite`, `node`, etc.).
 
 ## Context
@@ -148,8 +148,10 @@ chmod +x ./example.sh
 
 ## Imperatives
 
+YOU MUST begin the turn with <<PLAN:...:PLAN
 YOU MUST ONLY use EXEC commands for actions that can't be performed with Extended HEREDOC Plurnk Operations.
-YOU MUST ONLY communicate with SEND, not with free text between operations.
+YOU MUST NOT emit free text between operations.
+YOU SHOULD NOT leak internal resource information when SENDing user messages.
 YOU MUST document all relevant questions and uncertainties into taxonomized, tagged, and topical unknown entries.
 YOU MUST ONLY populate known entries with source entry information, never with model training.
 YOU SHOULD manage your own context to maximize signal, as irrelevant tokens degrade reasoning.

package/dist/schema/Agent.json

@@ -1,18 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/Agent.json",
-    "title": "Agent",
-    "description": "Top-level singleton. Owns the default scheme registry and the active provider declaration. Sessions, runs, and below derive from their own tables (queried by FK to the singleton agent).",
-    "type": "object",
-    "required": ["version", "provider", "scheme_registry"],
-    "additionalProperties": false,
-    "properties": {
-        "version": { "type": "integer", "minimum": 0 },
-        "provider": { "$ref": "https://schemas.plurnk.dev/v0/ProviderDeclaration.json" },
-        "scheme_registry": {
-            "type": "array",
-            "items": { "$ref": "https://schemas.plurnk.dev/v0/SchemeRegistration.json" },
-            "description": "Agent-wide default scheme registrations. The v0 inventory ships with `plurnk`, `known`, `unknown`; everything else is plugin-registered."
-        }
-    }
-}

package/dist/schema/Entry.json

@@ -1,51 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/Entry.json",
-    "title": "Entry",
-    "description": "The unit of canonical state at agent or session scope. Pure state — no interaction forensics. Identity is `(scope, scheme, pathname)`; `session_id` discriminates session-scoped rows. Content lives in one or more named channels (e.g. `body`, `stdout`/`stderr` for exec, `body`/`headers` for https). The scheme registry declares each scheme's default channel.",
-    "type": "object",
-    "required": [
-        "id", "version", "scope", "session_id",
-        "scheme", "username", "password", "hostname", "port", "pathname", "params",
-        "channels",
-        "attributes", "tags"
-    ],
-    "additionalProperties": false,
-    "properties": {
-        "id": { "type": "integer", "minimum": 1 },
-        "version": { "type": "integer", "minimum": 0 },
-        "scope": { "enum": ["agent", "session"] },
-        "session_id": { "type": ["integer", "null"], "minimum": 1 },
-        "scheme": { "type": ["string", "null"], "minLength": 1 },
-        "username": { "type": ["string", "null"] },
-        "password": { "type": ["string", "null"] },
-        "hostname": { "type": ["string", "null"] },
-        "port": { "type": ["integer", "null"], "minimum": 0, "maximum": 65535 },
-        "pathname": { "type": "string" },
-        "params": {
-            "oneOf": [
-                { "$ref": "https://schemas.plurnk.dev/v0/Params.json" },
-                { "type": "null" }
-            ]
-        },
-        "channels": {
-            "type": "object",
-            "description": "Named channels on this entry. Keys are channel names (lowercase identifiers); values are ChannelContent. Must be non-empty. The scheme registry declares which channel is the default for unspecified ops.",
-            "minProperties": 1,
-            "propertyNames": { "pattern": "^[a-z][a-z0-9_-]*$" },
-            "additionalProperties": { "$ref": "https://schemas.plurnk.dev/v0/ChannelContent.json" }
-        },
-        "attributes": { "type": "object" },
-        "tags": { "type": "array", "items": { "type": "string" } }
-    },
-    "allOf": [
-        {
-            "if": { "properties": { "scope": { "const": "session" } } },
-            "then": { "properties": { "session_id": { "type": "integer" } } }
-        },
-        {
-            "if": { "properties": { "scope": { "const": "agent" } } },
-            "then": { "properties": { "session_id": { "type": "null" } } }
-        }
-    ]
-}

package/dist/schema/LogEntry.json

@@ -1,118 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/LogEntry.json",
-    "title": "LogEntry",
-    "description": "An immutable, append-only event log row. Structured as the parsed AST of one executed plurnk statement plus turn-coordinate context plus the response. Addressable via log://<loop>/<turn>/<action>.",
-    "type": "object",
-    "required": [
-        "id", "version",
-        "run_id", "loop_id", "turn_id", "sequence",
-        "at", "origin",
-        "op", "suffix", "signal",
-        "scheme", "username", "password", "hostname", "port", "pathname", "params", "fragment",
-        "lineMarker",
-        "tx", "mimetype_tx",
-        "rx", "mimetype_rx", "status_rx",
-        "state", "outcome",
-        "tokens"
-    ],
-    "additionalProperties": false,
-    "properties": {
-        "id": { "type": "integer", "minimum": 1 },
-        "version": { "type": "integer", "minimum": 0 },
-        "run_id": { "type": "integer", "minimum": 1 },
-        "loop_id": { "type": "integer", "minimum": 1 },
-        "turn_id": { "type": "integer", "minimum": 1 },
-        "sequence": { "type": "integer", "minimum": 1, "description": "1-based within the turn; resets at each new turn." },
-        "at": { "type": "string", "format": "date-time" },
-        "origin": { "enum": ["model", "client", "system", "plugin"] },
-        "op": { "enum": ["FIND", "READ", "EDIT", "COPY", "MOVE", "OPEN", "FOLD", "SEND", "EXEC", "KILL", "PLAN"] },
-        "suffix": { "type": "string" },
-        "signal": {
-            "oneOf": [
-                { "type": "array", "items": { "type": "string" } },
-                { "type": "number" },
-                { "type": "string" },
-                { "type": "null" }
-            ]
-        },
-        "scheme": { "type": ["string", "null"], "minLength": 1 },
-        "username": { "type": ["string", "null"] },
-        "password": { "type": ["string", "null"] },
-        "hostname": { "type": ["string", "null"] },
-        "port": { "type": ["integer", "null"], "minimum": 0, "maximum": 65535 },
-        "pathname": { "type": ["string", "null"] },
-        "params": {
-            "oneOf": [
-                { "$ref": "https://schemas.plurnk.dev/v0/Params.json" },
-                { "type": "null" }
-            ]
-        },
-        "fragment": {
-            "type": ["string", "null"],
-            "description": "Channel selector at request time. Names the channel the op targeted; null when the op used the scheme's default channel."
-        },
-        "lineMarker": {
-            "oneOf": [
-                { "$ref": "https://schemas.plurnk.dev/v0/LineMarker.json" },
-                { "type": "null" }
-            ]
-        },
-        "tx": { "type": "string", "description": "Raw request payload. For origin=model: the literal plurnk DSL substring of assistant.content. For origin=system/client/plugin: whatever the originator emitted, with `mimetype_tx` declaring the structure." },
-        "mimetype_tx": { "type": "string", "minLength": 1, "description": "Mimetype of `tx`. Typically `text/vnd.plurnk` for model-origin rows; arbitrary per-origin for system/client/plugin." },
-        "rx": { "type": "string", "description": "Raw response payload bytes/string." },
-        "mimetype_rx": { "type": "string", "minLength": 1 },
-        "status_rx": { "type": "integer", "minimum": 100, "maximum": 599 },
-        "state": {
-            "enum": ["proposed", "resolved", "failed", "cancelled"],
-            "description": "Lifecycle position; orthogonal to status_rx. status_rx is the HTTP-aligned outcome of the network call; state is where the entry sits in the proposal lifecycle. Side-effecting ops that route through a proposal flow transition proposed → {resolved | failed | cancelled}; non-proposing ops settle at 'resolved' on first write."
-        },
-        "outcome": {
-            "type": ["string", "null"],
-            "description": "Short reason string when state ∈ {failed, cancelled}; null otherwise. Common values: rejected, loop_aborted, timeout, policy_veto, apply_failed, write_failed. Open vocabulary — schemes mint their own as needed."
-        },
-        "tokens": { "type": "integer", "minimum": 0 }
-    },
-    "allOf": [
-        {
-            "if": { "properties": { "op": { "const": "SEND" } } },
-            "then": {
-                "properties": {
-                    "signal": { "type": ["number", "null"] },
-                    "lineMarker": { "type": "null" }
-                }
-            }
-        },
-        {
-            "if": { "properties": { "op": { "const": "EXEC" } } },
-            "then": {
-                "properties": {
-                    "signal": { "type": ["string", "null"] },
-                    "lineMarker": { "type": "null" }
-                }
-            }
-        },
-        {
-            "if": { "properties": { "op": { "const": "KILL" } } },
-            "then": {
-                "properties": {
-                    "signal": { "type": ["number", "null"] },
-                    "lineMarker": { "type": "null" }
-                }
-            }
-        },
-        {
-            "if": { "properties": { "op": { "enum": ["FIND", "READ", "EDIT", "COPY", "MOVE", "OPEN", "FOLD", "PLAN"] } } },
-            "then": {
-                "properties": {
-                    "signal": {
-                        "oneOf": [
-                            { "type": "array", "items": { "type": "string" } },
-                            { "type": "null" }
-                        ]
-                    }
-                }
-            }
-        }
-    ]
-}

package/dist/schema/Loop.json

@@ -1,20 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/Loop.json",
-    "title": "Loop",
-    "description": "An iteration within a run. The persisted status domain is a superset of the model-emittable terminals (the model emits 102/200/202/499; the engine also imposes 413/429/500/508 via direct write, and 100 marks a created-but-unstarted loop). The loop's prompt is replayed on every turn within it; turn.packet.user.prompt is a copy.",
-    "type": "object",
-    "required": ["id", "version", "run_id", "sequence", "status", "prompt"],
-    "additionalProperties": false,
-    "properties": {
-        "id": { "type": "integer", "minimum": 1 },
-        "version": { "type": "integer", "minimum": 0 },
-        "run_id": { "type": "integer", "minimum": 1 },
-        "sequence": { "type": "integer", "minimum": 1, "description": "1-based within the run." },
-        "status": {
-            "enum": [100, 102, 200, 413, 429, 499, 500, 508],
-            "description": "Persisted loop status. Model-emittable: 100 = created (not yet started); 102 = continuing; 200 = terminal success; 499 = terminal give-up/cancellation. Engine-imposed (never a model SEND): 413 = budget overflow; 429 = max turns; 500 = failed (strike-out); 508 = loop detected (cycle)."
-        },
-        "prompt": { "type": "string", "description": "The original user prompt for this loop, replayed on every turn." }
-    }
-}

package/dist/schema/Packet.json

@@ -1,72 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/Packet.json",
-    "title": "Packet",
-    "description": "One turn's full exchange with the provider: { system, user, assistant, assistantRaw }. system aggregates durable + accumulating context (definition, persona, in-scope log rows). user carries the per-turn ephemera. assistant is the provider-normalized output. assistantRaw is opaque.",
-    "type": "object",
-    "required": ["tokens", "system", "user", "assistant", "assistantRaw"],
-    "additionalProperties": false,
-    "properties": {
-        "tokens": {
-            "type": "integer",
-            "minimum": 0,
-            "description": "Total packet tokens — sum of section subtotals."
-        },
-        "system": {
-            "type": "object",
-            "required": ["tokens", "system_definition", "persona", "log"],
-            "additionalProperties": false,
-            "properties": {
-                "tokens": { "type": "integer", "minimum": 0 },
-                "system_definition": { "type": "string", "description": "text/markdown — plurnk grammar + scheme registry refs." },
-                "persona": { "type": "string", "description": "text/markdown — identity / mission." },
-                "log": {
-                    "type": "array",
-                    "items": { "$ref": "https://schemas.plurnk.dev/v0/LogEntry.json" }
-                }
-            }
-        },
-        "user": {
-            "type": "object",
-            "required": ["tokens", "prompt", "telemetry", "system_requirements"],
-            "additionalProperties": false,
-            "properties": {
-                "tokens": { "type": "integer", "minimum": 0 },
-                "prompt": { "type": "string", "description": "Copy of loop.prompt — never null on a continuation turn." },
-                "telemetry": {
-                    "type": "object",
-                    "description": "Per-turn instrumentation surfaced to the model. `budget` is renderer-provided markdown describing remaining context / cost / etc. `events` carries the cross-ecosystem error/telemetry stream (parser errors, scheme dispatch failures, engine rail signals, provider faults) — consumers route on each event's `source` + `kind` discriminator.",
-                    "required": ["budget", "events"],
-                    "additionalProperties": false,
-                    "properties": {
-                        "budget": { "type": "string", "description": "text/markdown — budget surface (token/cost/etc. left to spend). Empty string when nothing to surface." },
-                        "events": {
-                            "type": "array",
-                            "items": { "$ref": "https://schemas.plurnk.dev/v0/TelemetryEvent.json" },
-                            "description": "TelemetryEvent[]. Empty array when nothing to surface."
-                        }
-                    }
-                },
-                "system_requirements": { "type": "string", "description": "text/markdown — per-turn rules." }
-            }
-        },
-        "assistant": {
-            "type": "object",
-            "required": ["content", "ops", "reasoning"],
-            "additionalProperties": true,
-            "properties": {
-                "content": { "type": "string", "description": "Raw DSL string emitted by the model." },
-                "ops": {
-                    "type": "array",
-                    "items": { "$ref": "https://schemas.plurnk.dev/v0/PlurnkStatement.json" },
-                    "description": "Parsed PlurnkStatement[] derived from `content`."
-                },
-                "reasoning": {
-                    "type": ["string", "null"],
-                    "description": "text/plain — provider-exposed CoT when present, null otherwise."
-                }
-            }
-        },
-        "assistantRaw": true
-    }
-}

package/dist/schema/Run.json

@@ -1,26 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/Run.json",
-    "title": "Run",
-    "description": "A stretch of work within a session. Forkable via parent_run_id. Owns per-run logs.",
-    "type": "object",
-    "required": ["id", "version", "session_id", "name", "created_at", "parent_run_id", "cost_pico"],
-    "additionalProperties": false,
-    "properties": {
-        "id": { "type": "integer", "minimum": 1 },
-        "version": { "type": "integer", "minimum": 0 },
-        "session_id": { "type": "integer", "minimum": 1 },
-        "name": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Unique within the session. Auto-populated default form `run-{unixtime}` until renamed. Clients display this; cross-table references use `id` so renames don't cascade-break."
-        },
-        "created_at": { "type": "string", "format": "date-time" },
-        "parent_run_id": {
-            "type": ["integer", "null"],
-            "minimum": 1,
-            "description": "FK to parent run when this is a fork; null for the trunk run."
-        },
-        "cost_pico": { "type": "integer", "minimum": 0, "description": "Cumulative cost across this run's turns, in pico-units of the active provider's currency." }
-    }
-}

package/dist/schema/Session.json

@@ -1,20 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/Session.json",
-    "title": "Session",
-    "description": "A durable user-named workspace. Never ends except by explicit removal. Shares session-scoped entries and any scheme-registry additions across all its runs.",
-    "type": "object",
-    "required": ["id", "version", "name", "created_at", "cost_pico", "scheme_registry_additions"],
-    "additionalProperties": false,
-    "properties": {
-        "id": { "type": "integer", "minimum": 1 },
-        "version": { "type": "integer", "minimum": 0 },
-        "name": { "type": "string", "minLength": 1, "description": "Unique within the agent. Auto-populated default form `session-{unixtime}` until renamed. Clients display this; cross-table references use `id` so renames don't cascade-break." },
-        "created_at": { "type": "string", "format": "date-time" },
-        "cost_pico": { "type": "integer", "minimum": 0, "description": "Cumulative cost across this session's runs." },
-        "scheme_registry_additions": {
-            "type": "array",
-            "items": { "$ref": "https://schemas.plurnk.dev/v0/SchemeRegistration.json" }
-        }
-    }
-}

package/dist/schema/Turn.json

@@ -1,39 +0,0 @@
-{
-    "$schema": "https://json-schema.org/draft/2020-12/schema",
-    "$id": "https://schemas.plurnk.dev/v0/Turn.json",
-    "title": "Turn",
-    "description": "The leaf of the envelope hierarchy. One model-provider exchange. Persists the full packet plus provider-returned usage and the turn-level status.",
-    "type": "object",
-    "required": ["id", "version", "loop_id", "sequence", "timestamp", "status", "usage", "finish_reason", "model", "packet"],
-    "additionalProperties": false,
-    "properties": {
-        "id": { "type": "integer", "minimum": 1 },
-        "version": { "type": "integer", "minimum": 0 },
-        "loop_id": { "type": "integer", "minimum": 1 },
-        "sequence": { "type": "integer", "minimum": 1, "description": "1-based within the loop; resets at each new loop." },
-        "timestamp": { "type": "string", "format": "date-time" },
-        "status": { "type": "integer", "minimum": 100, "maximum": 599 },
-        "usage": {
-            "type": "object",
-            "description": "Provider-returned token counts and computed cost.",
-            "required": ["prompt", "completion", "cached", "cost_pico"],
-            "additionalProperties": false,
-            "properties": {
-                "prompt": { "type": "integer", "minimum": 0 },
-                "completion": { "type": "integer", "minimum": 0 },
-                "cached": { "type": "integer", "minimum": 0 },
-                "cost_pico": { "type": "integer", "minimum": 0, "description": "Per-turn cost in pico-units of the active provider's currency." }
-            }
-        },
-        "finish_reason": {
-            "type": ["string", "null"],
-            "description": "Provider-reported completion-state token (`stop` | `length` | `tool_calls` | `content_filter` | provider-specific). Null when not reported. Distinct from `status` (HTTP-aligned turn outcome); `finish_reason` describes how the model stopped, `status` describes how the turn resolved."
-        },
-        "model": {
-            "type": "string",
-            "minLength": 1,
-            "description": "Wire-reported model identifier. May differ from `agent.provider.model` for routing-relay providers (OpenRouter, etc.); the verification surface for served-vs-requested alignment."
-        },
-        "packet": { "$ref": "https://schemas.plurnk.dev/v0/Packet.json" }
-    }
-}