@plurnk/plurnk-grammar 0.1.1 → 0.2.1

package/README.md

@@ -8,13 +8,13 @@ Parser for the Plurnk protocol — a HEREDOC-style DSL for LLM agents.
 npm install @plurnk/plurnk-grammar
 ```
 
-Requires Node ≥ 23.6 (native TypeScript support).
+Requires Node ≥ 25 (native TypeScript support).
 
 ## use
 
 ```ts
-import { parse } from "plurnk-grammar";
-const result = parse(input);
+import { PlurnkParser } from "plurnk-grammar";
+const result = PlurnkParser.parse(input);
 // result.items: Array<{kind:"statement"|"error"|"text", ...}>
 // result.unparsedTail?: { from, reason }
 ```

package/bin/plurnk.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { parse } from "../src/index.ts";
+import { PlurnkParser } from "../src/index.ts";
 
 const USAGE = `Usage:
   plurnk [file]      Parse plurnk source from a file (or stdin if omitted or '-')
@@ -30,7 +30,7 @@ const input = !target || target === "-"
     ? readFileSync(0, "utf8")
     : readFileSync(target, "utf8");
 
-const result = parse(input);
+const result = PlurnkParser.parse(input);
 
 const serialized = JSON.stringify(
     result,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plurnk/plurnk-grammar",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "ANTLR4 grammar for the Plurnk LLM agent protocol",
   "type": "module",
   "license": "MIT",
@@ -8,7 +8,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=23.6"
+    "node": ">=25"
   },
   "exports": {
     ".": "./src/index.ts",
@@ -21,11 +21,13 @@
     "bin/plurnk.js",
     "src/*.ts",
     "src/generated/*.ts",
-    "SPEC.md",
+    "schema/*.json",
     "plurnk.md"
   ],
   "scripts": {
     "build:grammar": "antlr-ng -D language=TypeScript -o src/generated --generate-visitor true --generate-listener false plurnkLexer.g4 plurnkParser.g4 && node scriptify/fix-generated-imports.ts",
+    "build:types": "node scriptify/generate-types.ts",
+    "build": "npm run build:grammar && npm run build:types",
     "antlr:tokens": "testrig src/generated/plurnk document --tokens",
     "antlr:trace": "testrig src/generated/plurnk document --trace",
     "antlr:parse": "testrig src/generated/plurnk document --tree",
@@ -34,9 +36,11 @@
     "test:intg": "node --test test/integration/*.test.ts",
     "test:demo": "node --test test/demo/*.test.ts",
     "test:all": "npm run test:lint && npm run test:unit && npm run test:intg && npm run test:demo",
-    "prepublishOnly": "npm run build:grammar && npm run test:all"
+    "prepare": "npm run build",
+    "prepublishOnly": "npm run build && npm run test:all"
   },
   "dependencies": {
+    "@cfworker/json-schema": "^4.1.1",
     "antlr4ng": "^3.0.0",
     "jsonpath-plus": "^10.4.0",
     "xpath": "^0.0.34"
@@ -44,6 +48,7 @@
   "devDependencies": {
     "@types/node": "^25.8.0",
     "antlr-ng": "^1.0.10",
+    "json-schema-to-typescript": "^15.0.4",
     "typescript": "^6.0.3"
   }
 }

package/plurnk.md

@@ -8,7 +8,7 @@ YOU MUST ONLY use the HEREDOC-inspired Plurnk Operations (FIND|READ|EDIT|COPY|MO
 <<OPsuffix[signal]?(path)?<L>?:body?:OPsuffix
 ```
 
-Slot order is fixed. Slots between `<<OPsuffix` and `:body:` are all optional. `:body:` fences are required (use `::` when body is empty). Close tag's `OPsuffix` must character-match the open.
+Slots between `<<OPsuffix` and `:body:` are all optional. `:body:` fences are required (use `::` when body is empty). Close tag's `OPsuffix` must character-match the open. Emit slots in the canonical order shown; the grammar tolerates other orderings.
 
 ## Operations
 
@@ -21,8 +21,8 @@ Slot order is fixed. Slots between `<<OPsuffix` and `:body:` are all optional. `
 | MOVE | apply tags    | required | lines `N-M`      | destination URI          |
 | SHOW | filter tags   | required | results `N-M`    | matcher                  |
 | HIDE | filter tags   | required | results `N-M`    | matcher                  |
-| SEND | HTTP status   | optional | —                | message (JSON for data)  |
-| EXEC | Runtime Tag   | required | —                | command or code          |
+| SEND | HTTP status   | recipient | —               | message (JSON for data)  |
+| EXEC | Runtime Tag   | cwd       | —               | command or code          |
 
 SEND signal is a single integer. EXEC signal is a single Runtime Tag (`sh`, `node`, `python`, etc.). All other signals are CSV.
 
@@ -54,7 +54,7 @@ Internal schemes:
 - `known://` — knowledgebase entries.
 - `skill://` — available skill entries.
 - `log://<loop>/<turn>/<action>/...` — event log.
-- `stream://` — live data streams.
+- `exec://` — actions and external interactions; each entry carries the request (TX) and response (RX).
 
 ## Context
 

package/schema/Agent.json

@@ -0,0 +1,18 @@
+{
+    "$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/schema/ChannelContent.json

@@ -0,0 +1,14 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ChannelContent.json",
+    "title": "ChannelContent",
+    "description": "One named stream of content on an entry. Channels carry distinct, parallel views of an entry (e.g. `stdout` and `stderr` on `exec://`; `body` and `headers` on `https://`; `body` and `symbols` on a code file). Each channel has its own content bytes, mimetype, and token count.",
+    "type": "object",
+    "required": ["content", "mimetype", "tokens"],
+    "additionalProperties": false,
+    "properties": {
+        "content": { "type": "string", "description": "Raw content bytes/string for this channel. Binary content awaits a future encoding pass (see AGENTS.md)." },
+        "mimetype": { "type": "string", "minLength": 1 },
+        "tokens": { "type": "integer", "minimum": 0, "description": "Token count of `content` under the active model's tokenizer." }
+    }
+}

package/schema/Entry.json

@@ -0,0 +1,51 @@
+{
+    "$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/schema/LineMarker.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/LineMarker.json",
+    "title": "LineMarker",
+    "description": "A parsed `<L>` slot. `first` is a signed integer with sentinel meanings (0 = prepend anchor, -1 = append anchor). `last` is the second position in a range marker `<N-M>`, or null for a single-position marker `<N>`.",
+    "type": "object",
+    "required": ["first", "last"],
+    "additionalProperties": false,
+    "properties": {
+        "first": { "type": "integer" },
+        "last": { "type": ["integer", "null"] }
+    }
+}

package/schema/LogEntry.json

@@ -0,0 +1,100 @@
+{
+    "$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", "action_index",
+        "at", "origin",
+        "op", "suffix", "signal",
+        "target_scheme", "target_username", "target_password", "target_hostname", "target_port", "target_pathname", "target_params", "target_fragment",
+        "lineMarker",
+        "tx", "mimetype_tx",
+        "rx", "mimetype_rx", "status_rx",
+        "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 },
+        "action_index": { "type": "integer", "minimum": 0 },
+        "at": { "type": "string", "format": "date-time" },
+        "origin": { "enum": ["model", "client", "system", "plugin"] },
+        "op": { "enum": ["FIND", "READ", "EDIT", "COPY", "MOVE", "SHOW", "HIDE", "SEND", "EXEC"] },
+        "suffix": { "type": "string" },
+        "signal": {
+            "oneOf": [
+                { "type": "array", "items": { "type": "string" } },
+                { "type": "number" },
+                { "type": "string" },
+                { "type": "null" }
+            ]
+        },
+        "target_scheme": { "type": ["string", "null"], "minLength": 1 },
+        "target_username": { "type": ["string", "null"] },
+        "target_password": { "type": ["string", "null"] },
+        "target_hostname": { "type": ["string", "null"] },
+        "target_port": { "type": ["integer", "null"], "minimum": 0, "maximum": 65535 },
+        "target_pathname": { "type": ["string", "null"] },
+        "target_params": {
+            "oneOf": [
+                { "$ref": "https://schemas.plurnk.dev/v0/Params.json" },
+                { "type": "null" }
+            ]
+        },
+        "target_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/x-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 },
+        "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": { "enum": ["FIND", "READ", "EDIT", "COPY", "MOVE", "SHOW", "HIDE"] } } },
+            "then": {
+                "properties": {
+                    "signal": {
+                        "oneOf": [
+                            { "type": "array", "items": { "type": "string" } },
+                            { "type": "null" }
+                        ]
+                    }
+                }
+            }
+        }
+    ]
+}

package/schema/Loop.json

@@ -0,0 +1,20 @@
+{
+    "$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. Bounded by status: 102 (continuing, more turns expected), 200 (terminal success), 499 (terminal cancellation). 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": [102, 200, 499],
+            "description": "102 = continuing; 200 = terminal success; 499 = terminal cancellation."
+        },
+        "prompt": { "type": "string", "description": "The original user prompt for this loop, replayed on every turn." }
+    }
+}

package/schema/MatcherBody.json

@@ -0,0 +1,60 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/MatcherBody.json",
+    "title": "MatcherBody",
+    "description": "Parsed body of a FIND/READ/SHOW/HIDE statement, discriminated on `dialect`. The dialect is determined by the body's leading characters (`//` xpath, `/` regex, `$` jsonpath, else glob). The regex variant carries pattern/flags split out of the `/pattern/flags` literal; the compiled `RegExp` object on the in-memory AST is a runtime ergonomic only and is not part of the persisted/wire contract.",
+    "oneOf": [
+        { "$ref": "#/$defs/XPathBody" },
+        { "$ref": "#/$defs/RegexBody" },
+        { "$ref": "#/$defs/JsonPathBody" },
+        { "$ref": "#/$defs/GlobBody" }
+    ],
+    "$defs": {
+        "XPathBody": {
+            "title": "XPathBody",
+            "description": "XPath 1.0 expression. Validated at parse time via the xpath library.",
+            "type": "object",
+            "required": ["dialect", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "xpath" },
+                "raw": { "type": "string", "minLength": 2 }
+            }
+        },
+        "RegexBody": {
+            "title": "RegexBody",
+            "description": "JavaScript regex literal `/pattern/flags`. Pattern and flags are split out for direct use. `raw` preserves the literal form for round-tripping.",
+            "type": "object",
+            "required": ["dialect", "raw", "pattern", "flags"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "regex" },
+                "raw": { "type": "string", "minLength": 2 },
+                "pattern": { "type": "string" },
+                "flags": { "type": "string" }
+            }
+        },
+        "JsonPathBody": {
+            "title": "JsonPathBody",
+            "description": "JSONPath expression. Validated at parse time via jsonpath-plus.",
+            "type": "object",
+            "required": ["dialect", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "jsonpath" },
+                "raw": { "type": "string", "minLength": 1 }
+            }
+        },
+        "GlobBody": {
+            "title": "GlobBody",
+            "description": "Pattern with no dialect prefix; treated as a glob/literal match.",
+            "type": "object",
+            "required": ["dialect", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "dialect": { "const": "glob" },
+                "raw": { "type": "string" }
+            }
+        }
+    }
+}

package/schema/Packet.json

@@ -0,0 +1,64 @@
+{
+    "$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, indexed entries, 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", "index", "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." },
+                "index": {
+                    "type": "array",
+                    "items": { "$ref": "https://schemas.plurnk.dev/v0/Entry.json" }
+                },
+                "log": {
+                    "type": "array",
+                    "items": { "$ref": "https://schemas.plurnk.dev/v0/LogEntry.json" }
+                }
+            }
+        },
+        "user": {
+            "type": "object",
+            "required": ["tokens", "prompt", "turn", "system_requirements"],
+            "additionalProperties": false,
+            "properties": {
+                "tokens": { "type": "integer", "minimum": 0 },
+                "prompt": { "type": "string", "description": "Copy of loop.prompt — never null on a continuation turn." },
+                "turn": { "type": "string", "description": "text/markdown — dynamically generated tables for budget/status/counts." },
+                "system_requirements": { "type": "string", "description": "text/markdown — per-turn rules." }
+            }
+        },
+        "assistant": {
+            "type": "object",
+            "required": ["tokens", "content", "ops", "reasoning"],
+            "additionalProperties": true,
+            "properties": {
+                "tokens": { "type": "integer", "minimum": 0 },
+                "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/schema/Params.json

@@ -0,0 +1,13 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/Params.json",
+    "title": "Params",
+    "description": "URL query parameters parsed into a JSON object. Single-value keys map to strings; multi-value keys (repeated in the original query string) map to arrays of strings. Empty object when the URL has no query string; nullable usages wrap this schema in a oneOf with null.",
+    "type": "object",
+    "additionalProperties": {
+        "oneOf": [
+            { "type": "string" },
+            { "type": "array", "items": { "type": "string" } }
+        ]
+    }
+}

package/schema/ParsedPath.json

@@ -0,0 +1,51 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://schemas.plurnk.dev/v0/ParsedPath.json",
+    "title": "ParsedPath",
+    "description": "A parsed path slot from a plurnk statement. Discriminated on `kind`: either a bare local path (no scheme) or a fully decomposed URL.",
+    "oneOf": [
+        { "$ref": "#/$defs/LocalPath" },
+        { "$ref": "#/$defs/UrlPath" }
+    ],
+    "$defs": {
+        "LocalPath": {
+            "title": "LocalPath",
+            "description": "A bare local path with no `scheme://` prefix. The raw string is stored verbatim; resolution is the runtime's job.",
+            "type": "object",
+            "required": ["kind", "raw"],
+            "additionalProperties": false,
+            "properties": {
+                "kind": { "const": "local" },
+                "raw": { "type": "string" }
+            }
+        },
+        "UrlPath": {
+            "title": "UrlPath",
+            "description": "A path with a `scheme://` prefix, fully decomposed via WHATWG URL.",
+            "type": "object",
+            "required": [
+                "kind", "raw", "scheme",
+                "username", "password",
+                "hostname", "port",
+                "pathname", "params", "fragment"
+            ],
+            "additionalProperties": false,
+            "properties": {
+                "kind": { "const": "url" },
+                "raw": { "type": "string" },
+                "scheme": { "type": "string", "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": { "$ref": "https://schemas.plurnk.dev/v0/Params.json" },
+                "fragment": { "type": ["string", "null"] }
+            }
+        }
+    }
+}