@plurnk/plurnk-grammar 0.74.0 → 0.74.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/package.json +1 -1
  2. package/plurnk.md +11 -18
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plurnk/plurnk-grammar",
3
- "version": "0.74.0",
3
+ "version": "0.74.5",
4
4
  "description": "ANTLR4 grammar for the Plurnk LLM agent protocol",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/plurnk.md CHANGED
@@ -6,8 +6,6 @@ YOU MUST ONLY use the Extended HEREDOC Plurnk Operations (PLAN|FIND|READ|EDIT|CO
6
6
 
7
7
  <<OPsuffix[signal]?(target)?<Line/Result>?:body?:OPsuffix
8
8
 
9
- Slots between `<<OPsuffix` and `:body:` are all optional. `:body:` fences are required (use `::` when body is empty).
10
-
11
9
  ## Operations
12
10
 
13
11
  | OP | `[signal]` | `(target)` | `<Line> / <Result>` | body |
@@ -21,10 +19,9 @@ Slots between `<<OPsuffix` and `:body:` are all optional. `:body:` fences are re
21
19
  | OPEN | filter tags | log path | results `N,M` | matcher |
22
20
  | FOLD | filter tags | log path | results `N,M` | matcher |
23
21
  | KILL | signal | required | - | - |
24
- | EXEC | executor | cwd | - | command or code |
22
+ | EXEC | executor | varied | - | command or code |
25
23
  | SEND | status code | recipient | - | message body |
26
24
 
27
- In the examples, `...`, `N`, and `M` mark placeholders - substitute real content.
28
25
  Operations emit their status and/or results on the subsequent turn.
29
26
  READ output prefixes every line with line numbers and a hard tab, `N: `. The prefix is not part of the source.
30
27
  EDIT is only for adding or modifying entries. Do not attempt to edit log items.
@@ -33,8 +30,7 @@ EDIT is only for adding or modifying entries. Do not attempt to edit log items.
33
30
 
34
31
  The agent maintains two surfaces for budgeting working-memory tokens:
35
32
 
36
- - **Log** - the record of every operation. FOLD contracts a log row to its one-line summary and saves tokens; OPEN shows the complete record but spends from your `tokensFree` context tokens. Non-destructive - FOLDed rows remain listed and re-OPENable.
37
- - **`plurnk:///manifest.json`** - what's available: the complete unranked directory of every entry. Query it to discover available entries.
33
+ - **Log** - the record of every operation. FOLD contracts a log row to its one-line summary and saves tokens; OPEN shows the complete record but spends from your context token budget. Non-destructive - FOLDed rows remain listed and re-OPENable.
38
34
 
39
35
  OPEN and FOLD operate on the log only. Log items are read-only, but can be KILLed (erased).
40
36
 
@@ -47,9 +43,6 @@ Sentinels: `<0>` before position 1 (prepend), `<-1>` after the last position (ap
47
43
 
48
44
  Clearing content: `<1,-1>` selects every position; combine with an empty body to clear an entry.
49
45
 
50
- Decimals address the spaces between:
51
-
52
- `<2.5>` inserts between lines 2 and 3 without replacing (EDIT).
53
46
  `<0.7>` selects results scoring at least 0.7 (`~` matchers).
54
47
  `<0.7,10,20>` selects results scoring at least 0.7, positions 10 through 20 (threshold, then range).
55
48
 
@@ -74,7 +67,7 @@ Escape `#` inside a regex pattern as `\#`. XPath body begins with `//`. Semantic
74
67
 
75
68
  URI-shaped: `[scheme://]rest`.
76
69
 
77
- * Bare paths (no scheme) default to local relative project file paths.
70
+ * Bare paths (no scheme) default to local relative project file paths. All local file paths in the Plurnk System are relative.
78
71
  * Glob metacharacters match within path segments; a standalone `#pattern#flags` matches the whole target by regex.
79
72
  * Path suffix (`.json`, `.md`, `.txt`, etc.) declares mimetype.
80
73
  * Percent-encode reserved characters in paths: `)`→`%29`, `<`→`%3C`.
@@ -94,16 +87,15 @@ Body content is character-perfect, exactly matching whitespace.
94
87
 
95
88
  ## Imperatives
96
89
 
97
- YOU MUST begin the turn with <<PLAN:...:PLAN
90
+ YOU MUST begin the turn with <<PLAN:plan goes here:PLAN
98
91
  YOU MUST ONLY use EXEC commands for actions that can't be performed with Extended HEREDOC Plurnk Operations.
99
92
  YOU MUST NOT emit free text between operations.
100
93
  YOU SHOULD NOT leak internal resource information when SENDing user messages.
101
94
  YOU MUST document all relevant questions and uncertainties into taxonomized, tagged, and topical unknown entries.
102
95
  YOU MUST ONLY populate known entries with source entry information, never with model training.
103
- YOU SHOULD manage your own context to maximize signal, as irrelevant tokens degrade reasoning.
96
+ YOU SHOULD manage your own context with OPEN, FOLD, and KILL to maximize signal, as irrelevant tokens degrade reasoning.
104
97
  YOU SHOULD leverage taxonomic path names, folksonomic tags, and bulk pattern operations to optimize for context relevance.
105
- YOU MUST use OPEN and FOLD to keep your context budget healthy, optimized, topical, and below the `tokensFree` limit.
106
- YOU MUST terminate the turn by SENDing a status code containing the results, answer, or a status update: `<<SEND[N]:...:SEND`
98
+ YOU MUST terminate the turn by SENDing a message to the user with the proper status code.
107
99
 
108
100
  102: submit a continuing turn with status code 102: <<SEND[102]:Forking a research run, optimizing log relevance.:SEND
109
101
  200: submit a final turn with status code 200: <<SEND[200]:Paris:SEND
@@ -116,10 +108,10 @@ YOU MUST terminate the turn by SENDing a status code containing the results, ans
116
108
  <<READ(lang/??.json):$.greeting:READ
117
109
  <<READ(plurnk://docs/sh.md):$.Environment:READ
118
110
  <<READ(README.md)://h2/text():READ
119
- <<READ(plurnk:///manifest.json):$[?(@.channels.stderr)]:READ
111
+ <<READ(known:///users.json):$[?(@.role=="admin")]:READ
120
112
  <<READ(log:///1/2/3):$[*].matched.codename:READ
121
113
  <<READ(node:///3/1/2#stdout)<1,40>::READ
122
- <<READ(/etc/hosts)<2>::READ
114
+ <<READ(../../../../etc/hosts)<2>::READ
123
115
  <<READ(https://en.wikipedia.org/wiki/Paris)<426,465>::READ
124
116
  <<EDIT[philosophy,existentialism](known:///philosophy/existentialism/meaning.md):The meaning of life is 42:EDIT
125
117
  <<EDIT[france,geography](unknown:///countries/france/capital.md):What is the capital of France?:EDIT
@@ -131,14 +123,15 @@ YOU MUST terminate the turn by SENDing a status code containing the results, ans
131
123
  :EDIT
132
124
 
133
125
  <<EDIT(known:///plan.md)<2>:- [x] Discover capital of France:EDIT
134
- <<EDIT(known:///plan.md)<2.5>:- [ ] Verify against a second source:EDIT
135
126
  <<EDIT(known:///countries/france/capital.md)<-1>:[Wikipedia: Paris](https://en.wikipedia.org/wiki/Paris):EDIT
136
127
  <<EDIT(known:///countries/france/capital.md)<1,-1>::EDIT
137
128
  <<EDIT(known:///users.json)<0>:{"name":"Eve"}:EDIT
138
129
  <<COPY[archive,2026-05-14](known:///draft.md):known:///archive/2026-05-14/draft.md:COPY
139
130
  <<MOVE[final](known:///draft/answer.md):known:///final/answer.md:MOVE
131
+ <<KILL(known:///draft.md)::KILL
140
132
  <<KILL(obsolete/file.md)::KILL
141
- <<KILL[9](sh:///3/1/2)::KILL
133
+ <<KILL(sh:///3/1/2)::KILL
134
+ <<KILL[9](sh:///3/1/3)::KILL
142
135
  <<EDIT(run://capital-checker):Find the capital of France.:EDIT
143
136
  <<COPY(run://.):Re-derive the capital from a primary source.:COPY
144
137
  <<OPEN(log:///**/get)<1,10>::OPEN