@plurnk/plurnk-grammar 0.2.1 → 0.6.0

package/bin/plurnk.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { readFileSync } from "node:fs";
 import { parseArgs } from "node:util";
-import { PlurnkParser } from "../src/index.ts";
+import { PlurnkParser } from "../dist/src/index.js";
 
 const USAGE = `Usage:
   plurnk [file]      Parse plurnk source from a file (or stdin if omitted or '-')

package/{schema → dist/schema}/LogEntry.json

@@ -58,7 +58,7 @@
             ]
         },
         "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." },
+        "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 },

package/{schema → dist/schema}/Packet.json

@@ -32,21 +32,33 @@
         },
         "user": {
             "type": "object",
-            "required": ["tokens", "prompt", "turn", "system_requirements"],
+            "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." },
-                "turn": { "type": "string", "description": "text/markdown — dynamically generated tables for budget/status/counts." },
+                "telemetry": {
+                    "type": "object",
+                    "description": "Per-turn instrumentation surfaced to the model. `budget` is renderer-provided markdown describing remaining context / cost / etc. `errors` carries actionless failures (parse errors and similar) that the model should confront on this turn. Inner shapes intentionally open at v0; consumers populate as needs solidify.",
+                    "required": ["budget", "errors"],
+                    "additionalProperties": false,
+                    "properties": {
+                        "budget": { "type": "string", "description": "text/markdown — budget surface (token/cost/etc. left to spend). Empty string when nothing to surface." },
+                        "errors": {
+                            "type": "array",
+                            "items": { "type": "object" },
+                            "description": "TelemetryError[] — element shape TBD. Empty array when no errors to surface."
+                        }
+                    }
+                },
                 "system_requirements": { "type": "string", "description": "text/markdown — per-turn rules." }
             }
         },
         "assistant": {
             "type": "object",
-            "required": ["tokens", "content", "ops", "reasoning"],
+            "required": ["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",

package/{schema → dist/schema}/ProviderDeclaration.json

@@ -7,9 +7,9 @@
     "required": ["provider", "family", "model", "contextSize", "currency"],
     "additionalProperties": false,
     "properties": {
-        "provider": { "type": "string", "minLength": 1, "description": "API vendor identifier (e.g. \"anthropic\", \"openai\", \"google\", \"local\")." },
-        "family": { "type": "string", "minLength": 1, "description": "Model family (e.g. \"claude\", \"gpt\", \"gemini\", \"llama\")." },
-        "model": { "type": "string", "minLength": 1, "description": "Specific model id (e.g. \"claude-opus-4-7\")." },
+        "provider": { "type": "string", "minLength": 1, "description": "API vendor identifier (e.g. \"local\", \"openrouter\", \"anthropic\", \"openai\")." },
+        "family": { "type": "string", "minLength": 1, "description": "Model family (e.g. \"gemma\", \"llama\", \"qwen\", \"claude\", \"gpt\", \"gemini\")." },
+        "model": { "type": "string", "minLength": 1, "description": "Specific model id (e.g. \"gemma3-12b\")." },
         "contextSize": { "type": "integer", "minimum": 1, "description": "Total context window in tokens." },
         "currency": { "type": "string", "pattern": "^[A-Z]{3}$", "description": "ISO 4217 code; the unit `cost_pico` is denominated in." }
     }

package/{schema → dist/schema}/Run.json

@@ -4,12 +4,17 @@
     "title": "Run",
     "description": "A stretch of work within a session. Forkable via parent_run_id. Owns per-run logs and visibility state.",
     "type": "object",
-    "required": ["id", "version", "session_id", "created_at", "parent_run_id", "cost_pico"],
+    "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"],

package/{schema → dist/schema}/Session.json

@@ -9,7 +9,7 @@
     "properties": {
         "id": { "type": "integer", "minimum": 1 },
         "version": { "type": "integer", "minimum": 0 },
-        "name": { "type": "string", "minLength": 1, "description": "Unique within the agent. Default form: `{modelAlias}-{unixtime}` until renamed." },
+        "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": {

package/{schema → dist/schema}/Turn.json

@@ -4,7 +4,7 @@
     "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", "packet"],
+    "required": ["id", "version", "loop_id", "sequence", "timestamp", "status", "usage", "finish_reason", "model", "packet"],
     "additionalProperties": false,
     "properties": {
         "id": { "type": "integer", "minimum": 1 },
@@ -25,6 +25,15 @@
                 "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" }
     }
 }

package/dist/src/AstBuilder.d.ts

@@ -0,0 +1,19 @@
+import type { ParsedPath, PlurnkStatement, Position } from "./types.ts";
+import type { StatementContext } from "./generated/plurnkParser.ts";
+declare module "xpath" {
+    function parse(expression: string): unknown;
+}
+export default class AstBuilder {
+    #private;
+    static build(ctx: StatementContext): PlurnkStatement;
+    /**
+     * Parse a path string into a ParsedPath, mirroring how the AST visitor
+     * decomposes path slots inside HEREDOC statements. Public for consumers
+     * (RPC layers, scheme handlers) that need to honor the grammar's
+     * authority-vs-opaque cleavage without round-tripping through a fake
+     * HEREDOC. Returns null when `raw` is empty. Throws PlurnkParseError
+     * when `raw` starts with `scheme://` but WHATWG URL rejects it.
+     */
+    static parsePath(raw: string, pos?: Position): ParsedPath | null;
+}
+//# sourceMappingURL=AstBuilder.d.ts.map

package/dist/src/AstBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AstBuilder.d.ts","sourceRoot":"","sources":["../../src/AstBuilder.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EASR,UAAU,EAEV,eAAe,EACf,QAAQ,EAKX,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAYR,gBAAgB,EAEnB,MAAM,6BAA6B,CAAC;AAWrC,OAAO,QAAQ,OAAO,CAAC;IACnB,SAAgB,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;CACtD;AAQD,MAAM,CAAC,OAAO,OAAO,UAAU;;IAa3B,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,gBAAgB,GAAG,eAAe;IA6NpD;;;;;;;OAOG;IACH,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,GAAE,QAAiC,GAAG,UAAU,GAAG,IAAI;CA6H3F"}