@plurnk/plurnk-grammar 0.74.6 → 0.74.8

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 (3) hide show
  1. package/README.md +2 -2
  2. package/package.json +1 -1
  3. package/plurnk.md +64 -72
package/README.md CHANGED
@@ -130,8 +130,8 @@ Nesting: outer body may contain inner `<<OP:…:OP` statements; outer must use a
130
130
  18. Deliver the final answer
131
131
  <<SEND[200]:Paris:SEND
132
132
 
133
- 19. Search logs for timeout errors (case-insensitive regex body)
134
- <<FIND(log:///**/error):#timeout|deadline exceeded#i:FIND
133
+ 19. Search logs for budget-overflow errors (case-insensitive regex body)
134
+ <<FIND(log:///**/error):#budget overflow|budget exceeded#i:FIND
135
135
 
136
136
  20. Find entries whose content begins with "Paris" (glob body)
137
137
  <<FIND(known:///countries/**):Paris*:FIND
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@plurnk/plurnk-grammar",
3
- "version": "0.74.6",
3
+ "version": "0.74.8",
4
4
  "description": "ANTLR4 grammar for the Plurnk LLM agent protocol",
5
5
  "type": "module",
6
6
  "license": "MIT",
package/plurnk.md CHANGED
@@ -1,12 +1,18 @@
1
- # Plurnk System Grammar
1
+ # Plurnk System
2
2
 
3
- YOU MUST ONLY use the Extended HEREDOC Plurnk Operations (PLAN|FIND|READ|EDIT|COPY|MOVE|OPEN|FOLD|KILL|EXEC|SEND).
3
+ Plurnk is an internal agentic harness with a persistent, extended context and a powerful pattern matching toolkit. You fully control your log (short term memory) and knowledgebase (long term memory).
4
4
 
5
- ## Syntax
5
+ ## Plurnk System Grammar
6
+
7
+ YOU MUST ONLY use the Extended HEREDOC Plurnk Operations (PLAN|FIND|READ|EDIT|COPY|MOVE|OPEN|FOLD|EXEC|KILL|SEND).
8
+
9
+ ### Syntax
6
10
 
7
11
  <<OPsuffix[signal]?(target)?<Line/Result>?:body?:OPsuffix
8
12
 
9
- ## Operations
13
+ ### Operations
14
+
15
+ Operations do not emit their results on the current turn.
10
16
 
11
17
  | OP | `[signal]` | `(target)` | `<Line> / <Result>` | body |
12
18
  |------|-------------|------------|---------------------|------------------|
@@ -18,23 +24,18 @@ YOU MUST ONLY use the Extended HEREDOC Plurnk Operations (PLAN|FIND|READ|EDIT|CO
18
24
  | MOVE | apply tags | required | lines `N,M` | destination URI |
19
25
  | OPEN | filter tags | log path | results `N,M` | matcher |
20
26
  | FOLD | filter tags | log path | results `N,M` | matcher |
21
- | KILL | signal | required | - | - |
22
27
  | EXEC | executor | varied | - | command or code |
28
+ | KILL | signal | required | - | - |
23
29
  | SEND | status code | recipient | - | message body |
24
30
 
25
- Operations emit their status and/or results on the subsequent turn.
31
+ FIND returns rows of results, READ returns lines of content.
26
32
  READ output prefixes every line with line numbers and a hard tab, `N: `. The prefix is not part of the source.
27
33
  EDIT is only for adding or modifying entries. Do not attempt to edit log items.
34
+ OPEN expands (`+`) the log item body and costs tokens. FOLD hides (`-`) the log item body and saves tokens. Not all log items have a body (`*`).
35
+ EXEC produces streams on the next turn that you can then OPEN, FOLD, FIND, READ, or KILL.
36
+ KILL deletes entries, erases log items, and kills streams.
28
37
 
29
- ## Context
30
-
31
- The agent maintains two surfaces for budgeting working-memory tokens:
32
-
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.
34
-
35
- OPEN and FOLD operate on the log only. Log items are read-only, but can be KILLed (erased).
36
-
37
- ## `<Line> / <Result>`
38
+ ### `<Line> / <Result>`
38
39
 
39
40
  `<N>` selects position N.
40
41
  `<N,M>` selects the inclusive range N through M. N and M are signed numbers.
@@ -48,7 +49,9 @@ Clearing content: `<1,-1>` selects every position; combine with an empty body to
48
49
 
49
50
  On structured entries and items, `<Result>` addresses result index, not line number.
50
51
 
51
- ## Body matcher dispatch (FIND, READ, OPEN, FOLD)
52
+ ### Pattern Filtering (FIND, READ, OPEN, FOLD)
53
+
54
+ Plurnk System enables project-wide pattern matching and filtering, including structural and semantic dialects, of all entries.
52
55
 
53
56
  | leading prefix | dialect | form |
54
57
  |----------------|----------|-----------------------------------|
@@ -59,11 +62,11 @@ On structured entries and items, `<Result>` addresses result index, not line num
59
62
  | `@` | graph | `@<symbol`, `@>symbol`, `@symbol` |
60
63
  | otherwise | glob | `pattern` |
61
64
 
62
- `$` and `//` address any entry with derivable structure (Markdown, HTML, source, …), not just native JSON/XML; `@` walks the code graph likewise.
63
-
64
- Escape `#` inside a regex pattern as `\#`. XPath body begins with `//`. Semantic search narrows top-K via `<Result>` on the host statement.
65
+ `$` and `//` address any entry with derivable structure (Markdown, HTML, source, …), not just native JSON/XML.
66
+ `@` walks the code graph likewise.
67
+ Escape a literal `#` inside regex patterns with `\#`.
65
68
 
66
- ## Paths
69
+ ### Paths
67
70
 
68
71
  URI-shaped: `[scheme://]rest`.
69
72
 
@@ -73,15 +76,15 @@ URI-shaped: `[scheme://]rest`.
73
76
  * Percent-encode reserved characters in paths: `)`→`%29`, `<`→`%3C`.
74
77
  * Append `#channel` to select a channel (e.g. `#stdout`, `#stderr`); absent, the scheme's default channel is used.
75
78
 
76
- ## Suffix
79
+ ### Suffix
77
80
 
78
- When quoting plurnk operations in a body, YOU MUST use a matching single-digit suffix (`1`–`9`) or label (`[a-z]+`) on the opening and closing tags.
81
+ YOU MUST use a matching single-digit suffix (`1`–`9`) or label (`[a-z]+`) when opening and closing embedded operations.
79
82
 
80
83
  <<EDIT1(known:///demo):
81
84
  quoted: <<EDIT(known:///inner):hello:EDIT
82
85
  :EDIT1
83
86
 
84
- ## Body
87
+ ### Body
85
88
 
86
89
  Body content is character-perfect, exactly matching whitespace.
87
90
 
@@ -89,56 +92,45 @@ Body content is character-perfect, exactly matching whitespace.
89
92
 
90
93
  YOU MUST begin the turn with <<PLAN:plan goes here:PLAN
91
94
  YOU MUST ONLY use EXEC commands for actions that can't be performed with Extended HEREDOC Plurnk Operations.
92
- YOU SHOULD NOT leak internal resource information when SENDing user messages.
93
- YOU MUST document all relevant questions and uncertainties into taxonomized, tagged, and topical unknown entries.
94
- YOU MUST ONLY populate known entries with source entry information, never with model training.
95
- YOU SHOULD manage your own context with OPEN, FOLD, and KILL to maximize signal, as irrelevant tokens degrade reasoning.
96
- YOU SHOULD leverage taxonomic path names, folksonomic tags, and bulk pattern operations to optimize for context relevance.
95
+ YOU SHOULD document all relevant questions and uncertainties into taxonomized, tagged, and topical unknown:/// entries.
96
+ YOU SHOULD record findings into taxonomized, tagged known:/// entries, preferring source content over recall.
97
+ YOU MUST prune irrelevant log items with FOLD or KILL and curate your persistent knowledgebase (known/unknown) to maximize signal/token.
97
98
  YOU MUST terminate the turn by SENDing a message to the user with the proper status code (102, 200, 202, or 499).
98
99
 
99
100
  ## Examples
100
101
 
101
- <<FIND(config/**/*.xml)://user[@role='admin']:FIND
102
- <<READ(lang/??.json):$.greeting:READ
103
- <<READ(plurnk://docs/sh.md):$.Environment:READ
104
- <<READ(README.md)://h2/text():READ
105
- <<READ(known:///users.json):$[?(@.role=="admin")]:READ
106
- <<READ(log:///1/2/3):$[*].matched.codename:READ
107
- <<READ(node:///3/1/2#stdout)<1,40>::READ
108
- <<READ(../../../../etc/hosts)<2>::READ
109
- <<READ(https://en.wikipedia.org/wiki/Paris)<426,465>::READ
110
- <<EDIT[philosophy,existentialism](known:///philosophy/existentialism/meaning.md):The meaning of life is 42:EDIT
111
- <<EDIT[france,geography](unknown:///countries/france/capital.md):What is the capital of France?:EDIT
112
-
113
- <<EDIT[plan,france,task](known:///plan.md):
114
- - [ ] Decompose prompt into unknowns
115
- - [ ] Discover capital of France
116
- - [ ] Deliver
117
- :EDIT
118
-
119
- <<EDIT(known:///plan.md)<2>:- [x] Discover capital of France:EDIT
120
- <<EDIT(known:///countries/france/capital.md)<-1>:[Wikipedia: Paris](https://en.wikipedia.org/wiki/Paris):EDIT
121
- <<EDIT(known:///countries/france/capital.md)<1,-1>::EDIT
122
- <<EDIT(known:///users.json)<0>:{"name":"Eve"}:EDIT
123
- <<COPY[archive,2026-05-14](known:///draft.md):known:///archive/2026-05-14/draft.md:COPY
124
- <<MOVE[final](known:///draft/answer.md):known:///final/answer.md:MOVE
125
- <<KILL(known:///draft.md)::KILL
126
- <<KILL(obsolete/file.md)::KILL
127
- <<KILL(sh:///3/1/2)::KILL
128
- <<KILL[9](sh:///3/1/3)::KILL
129
- <<EDIT(run://capital-checker):Find the capital of France.:EDIT
130
- <<COPY(run://.):Re-derive the capital from a primary source.:COPY
131
- <<OPEN(log:///**/get)<1,10>::OPEN
132
- <<FIND(known:///**)<5>:~french revolutionary history:FIND
133
- <<FIND(known:///**)<0.7>:~french territorial concessions:FIND
134
- <<FOLD(log:///**/get)<101,200>::FOLD
135
- <<FIND(log:///**/error):#timeout|deadline exceeded#i:FIND
136
- <<FIND(known:///**):revolution:FIND
137
- <<FIND(#(draft|final)/.*#i)::FIND
138
- <<FIND(#src/.*\.test\.ts#)::FIND
139
- <<FIND(src/**):@<createCoder:FIND
140
- <<SEND(run://capital-checker):{"hint":"known entries are your persistent memory"}:SEND
141
-
142
- <<EDIT[tutorial,training,scripts](example.sh):#!/usr/bin/env sh
143
- echo "Taxonomic path names and folksonomic tags on entries improve reasoning and recall!" > advice.txt
144
- :EDIT
102
+ * <<FIND(config/**/*.xml)://user[@role='admin']:FIND
103
+ * <<READ(lang/??.json):$.greeting:READ
104
+ * <<READ(plurnk://docs/sh.md):$.Environment:READ
105
+ * <<READ(README.md)://h2/text():READ
106
+ * <<READ(known:///users.json):$[?(@.role=="admin")]:READ
107
+ * <<READ(log:///1/2/3):$[*].matched.codename:READ
108
+ * <<READ(node:///3/1/2#stdout)<1,40>::READ
109
+ * <<READ(../../../../etc/hosts)<2>::READ
110
+ * <<READ(https://en.wikipedia.org/wiki/Paris)<426,465>::READ
111
+ * <<EDIT[philosophy,existentialism](known:///philosophy/existentialism/meaning.md):The meaning of life is 42:EDIT
112
+ * <<EDIT[france,geography](unknown:///countries/france/capital.md):What is the capital of France?:EDIT
113
+ * <<EDIT[plan,france,task](known:///plan.md):- [ ] Decompose prompt into unknowns:EDIT
114
+ * <<EDIT(known:///plan.md)<2>:- [x] Discover capital of France:EDIT
115
+ * <<EDIT(known:///countries/france/capital.md)<-1>:[Wikipedia: Paris](https://en.wikipedia.org/wiki/Paris):EDIT
116
+ * <<EDIT(known:///countries/france/capital.md)<1,-1>::EDIT
117
+ * <<EDIT(known:///users.json)<0>:{"name":"Eve"}:EDIT
118
+ * <<COPY[archive,2026-05-14](known:///draft.md):known:///archive/2026-05-14/draft.md:COPY
119
+ * <<MOVE[final](known:///draft/answer.md):known:///final/answer.md:MOVE
120
+ * <<KILL(known:///draft.md)::KILL
121
+ * <<KILL(obsolete/file.md)::KILL
122
+ * <<KILL(sh:///3/1/2)::KILL
123
+ * <<KILL[9](sh:///3/1/3)::KILL
124
+ * <<EDIT(run://capital-checker):Find the capital of France.:EDIT
125
+ * <<COPY(run://.):Re-derive the capital from a primary source.:COPY
126
+ * <<OPEN(log:///**/get)<1,10>::OPEN
127
+ * <<FIND(known:///**)<5>:~french revolutionary history:FIND
128
+ * <<FIND(known:///**)<0.7>:~french territorial concessions:FIND
129
+ * <<FOLD(log:///**/get)<101,200>::FOLD
130
+ * <<FIND(log:///**/error):#budget overflow|budget exceeded#i:FIND
131
+ * <<FIND(known:///**):revolution:FIND
132
+ * <<FIND(#(draft|final)/.*#i)::FIND
133
+ * <<FIND(#src/.*\.test\.ts#)::FIND
134
+ * <<FIND(src/**):@<createCoder:FIND
135
+ * <<SEND(run://capital-checker):{"hint":"known entries are your persistent memory"}:SEND
136
+ * <<EDIT[tutorial,training,scripts](example.sh):echo "Taxonomic path names and folksonomic tags on entries improve reasoning and recall!" > advice.txt:EDIT