@plurnk/plurnk-grammar 0.74.0 → 0.74.6

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 -24
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.6",
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,21 +87,14 @@ 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
- YOU MUST NOT emit free text between operations.
100
92
  YOU SHOULD NOT leak internal resource information when SENDing user messages.
101
93
  YOU MUST document all relevant questions and uncertainties into taxonomized, tagged, and topical unknown entries.
102
94
  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.
95
+ YOU SHOULD manage your own context with OPEN, FOLD, and KILL to maximize signal, as irrelevant tokens degrade reasoning.
104
96
  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`
107
-
108
- 102: submit a continuing turn with status code 102: <<SEND[102]:Forking a research run, optimizing log relevance.:SEND
109
- 200: submit a final turn with status code 200: <<SEND[200]:Paris:SEND
110
- 202: submit a waiting/idle loop with status code 202: <<SEND[202]:Parked until the capital-checker reports.:SEND
111
- 499: submit a failed loop with status code 499: <<SEND[499]:Aborted: Unrecoverable internal error:SEND
97
+ YOU MUST terminate the turn by SENDing a message to the user with the proper status code (102, 200, 202, or 499).
112
98
 
113
99
  ## Examples
114
100
 
@@ -116,10 +102,10 @@ YOU MUST terminate the turn by SENDing a status code containing the results, ans
116
102
  <<READ(lang/??.json):$.greeting:READ
117
103
  <<READ(plurnk://docs/sh.md):$.Environment:READ
118
104
  <<READ(README.md)://h2/text():READ
119
- <<READ(plurnk:///manifest.json):$[?(@.channels.stderr)]:READ
105
+ <<READ(known:///users.json):$[?(@.role=="admin")]:READ
120
106
  <<READ(log:///1/2/3):$[*].matched.codename:READ
121
107
  <<READ(node:///3/1/2#stdout)<1,40>::READ
122
- <<READ(/etc/hosts)<2>::READ
108
+ <<READ(../../../../etc/hosts)<2>::READ
123
109
  <<READ(https://en.wikipedia.org/wiki/Paris)<426,465>::READ
124
110
  <<EDIT[philosophy,existentialism](known:///philosophy/existentialism/meaning.md):The meaning of life is 42:EDIT
125
111
  <<EDIT[france,geography](unknown:///countries/france/capital.md):What is the capital of France?:EDIT
@@ -131,14 +117,15 @@ YOU MUST terminate the turn by SENDing a status code containing the results, ans
131
117
  :EDIT
132
118
 
133
119
  <<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
120
  <<EDIT(known:///countries/france/capital.md)<-1>:[Wikipedia: Paris](https://en.wikipedia.org/wiki/Paris):EDIT
136
121
  <<EDIT(known:///countries/france/capital.md)<1,-1>::EDIT
137
122
  <<EDIT(known:///users.json)<0>:{"name":"Eve"}:EDIT
138
123
  <<COPY[archive,2026-05-14](known:///draft.md):known:///archive/2026-05-14/draft.md:COPY
139
124
  <<MOVE[final](known:///draft/answer.md):known:///final/answer.md:MOVE
125
+ <<KILL(known:///draft.md)::KILL
140
126
  <<KILL(obsolete/file.md)::KILL
141
- <<KILL[9](sh:///3/1/2)::KILL
127
+ <<KILL(sh:///3/1/2)::KILL
128
+ <<KILL[9](sh:///3/1/3)::KILL
142
129
  <<EDIT(run://capital-checker):Find the capital of France.:EDIT
143
130
  <<COPY(run://.):Re-derive the capital from a primary source.:COPY
144
131
  <<OPEN(log:///**/get)<1,10>::OPEN