pico-engine 1.9.0 → 1.9.1

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 (41) hide show
  1. package/README.md +2 -2
  2. package/krl/io.picolabs.pico-engine-ui.krl +2 -0
  3. package/krl/io.picolabs.wrangler.krl +7 -1
  4. package/krl/io.picolabs.xmlui.krl +13 -3
  5. package/mcp/devResources.js +17 -7
  6. package/mcp/docs/CLAUDE.md +85 -0
  7. package/{public → mcp}/docs/pico-engine.md +8 -8
  8. package/package.json +5 -4
  9. package/public/pico-engine-ui.js +2 -2
  10. package/public/.DS_Store +0 -0
  11. package/public/docs/README.md +0 -9
  12. package/public/docs/_media/logo.png +0 -0
  13. package/public/docs/_sidebar.md +0 -7
  14. package/public/docs/contributing.md +0 -64
  15. package/public/docs/favicon.ico +0 -0
  16. package/public/docs/index.html +0 -29
  17. package/public/docs/krl/README.md +0 -3
  18. package/public/docs/krl/_sidebar.md +0 -10
  19. package/public/docs/krl/discovery.md +0 -144
  20. package/public/docs/krl/modules/ctx.md +0 -151
  21. package/public/docs/krl/modules/event.md +0 -70
  22. package/public/docs/krl/modules/http.md +0 -42
  23. package/public/docs/krl/modules/math.md +0 -5
  24. package/public/docs/krl/modules/schedule.md +0 -5
  25. package/public/docs/krl/modules.md +0 -11
  26. package/public/docs/krl/rulesets.md +0 -81
  27. package/public/docs/krl/stdlib.md +0 -3
  28. package/public/docs/llms-full.txt +0 -630
  29. package/public/docs/llms.txt +0 -38
  30. package/public/docs/openapi.yaml +0 -78
  31. package/public/docs/pico-views-xmlui.md +0 -5
  32. package/public/docs/pico-views.md +0 -140
  33. package/public/docs/pico.md +0 -5
  34. package/public/docs/rulesets/README.md +0 -26
  35. package/public/docs/rulesets/io.picolabs.oauth.md +0 -71
  36. package/public/docs/rulesets/io.picolabs.pds.md +0 -327
  37. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +0 -65
  38. package/public/docs/rulesets/io.picolabs.portable_subtree.md +0 -94
  39. package/public/docs/rulesets/io.picolabs.subscription.md +0 -398
  40. package/public/docs/rulesets/io.picolabs.wrangler.md +0 -471
  41. /package/{public → mcp}/docs/pico-overview.md +0 -0
@@ -1,29 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8" />
5
- <title>pico-engine</title>
6
- <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
7
- <meta name="description" content="Description" />
8
- <meta
9
- name="viewport"
10
- content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
11
- />
12
- <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css" />
13
- </head>
14
- <body>
15
- <div id="app"></div>
16
- <script>
17
- window.$docsify = {
18
- name: "pico-engine",
19
- repo: "https://github.com/Picolab/pico-engine",
20
- logo: "/_media/logo.png",
21
- themeColor: "#1A90CF",
22
- loadSidebar: true,
23
- auto2top: true,
24
- subMaxLevel: 3
25
- };
26
- </script>
27
- <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
28
- </body>
29
- </html>
@@ -1,3 +0,0 @@
1
- # KRL Manual NEXT
2
-
3
- This is the manual Kinetic Rule Language NEXT
@@ -1,10 +0,0 @@
1
- - [KRL Manual](/krl/)
2
- - [Rulesets](/krl/rulesets)
3
- - [Discovery](/krl/discovery)
4
- - [Standard Library](/krl/stdlib)
5
- - [Modules](/krl/modules)
6
- - [ctx](/krl/modules/ctx)
7
- - [event](/krl/modules/event)
8
- - [http](/krl/modules/http)
9
- - [math](/krl/modules/math)
10
- - [schedule](/krl/modules/schedule)
@@ -1,144 +0,0 @@
1
- # Discovery
2
-
3
- Every pico has a **`discovery`** channel. Integrators send a single event to learn what the pico can do. Each installed ruleset that participates in discovery responds with a **`discovery capability`** directive.
4
-
5
- This is event-based (not a query on a specific ruleset) so the engine can aggregate responses from every ruleset that implements discovery.
6
-
7
- ## Discovery channel
8
-
9
- Wrangler creates a channel tagged `discovery` on every pico. Its policy allows **only** the discovery event:
10
-
11
- | Direction | Allowed |
12
- |-----------|---------|
13
- | Events in | `discovery capabilities` |
14
- | Queries | none |
15
-
16
- Find the channel with `wrangler:discoveryChannel()` or `wrangler:channels(["discovery"])`.
17
-
18
- ## Integrator flow
19
-
20
- 1. Obtain the target pico's discovery channel ECI (via relationship metadata, parent query, etc.).
21
- 2. Send `discovery capabilities` on that channel.
22
- 3. Optionally include an **`eci`** attribute — the channel the integrator will use for subsequent queries and events on this pico.
23
- 4. Collect **`discovery capability`** directives from the event response.
24
-
25
- When `eci` is present, each ruleset filters its bindings so the integrator only sees capabilities that channel's policy **allows**. Denied operations are omitted, not listed and blocked later.
26
-
27
- Example (HTTP):
28
-
29
- ```http
30
- POST /sky/event/{discovery_eci}/discovery/capabilities/wait
31
- Content-Type: application/json
32
-
33
- {"eci": "{caller_eci}"}
34
- ```
35
-
36
- ## Ruleset author pattern
37
-
38
- Discovery is opt-in per ruleset. Add:
39
-
40
- 1. An **`app`** map — short metadata (`name`, `version`, optional `title`, `description`, `iconURL`).
41
- 2. A **`bindings()`** function — the integrator contract (queries, events, notifications).
42
- 3. A **discovery rule** that selects on `discovery capabilities` and sends a directive.
43
-
44
- ```krl
45
- ruleset io.picolabs.myapp {
46
- meta {
47
- use module io.picolabs.wrangler alias wrangler
48
- }
49
- global {
50
- app = {
51
- "name": "myapp",
52
- "title": "My App",
53
- "version": "1.0",
54
- "description": "One sentence explaining what this app does on the pico."
55
- };
56
-
57
- bindings = function() {
58
- {
59
- "version": 1,
60
- "queries": [
61
- {
62
- "name": "getStatus",
63
- "description": "Return the current status map."
64
- }
65
- ],
66
- "events": [
67
- {
68
- "domain": "myapp",
69
- "name": "refresh",
70
- "attrs": [],
71
- "description": "Ask the app to refresh its state."
72
- }
73
- ]
74
- }
75
- }
76
- }
77
-
78
- rule discovery {
79
- select when discovery capabilities
80
- send_directive("discovery capability", {
81
- "app": app,
82
- "rid": meta:rid,
83
- "bindings": wrangler:filterBindingsForCaller(
84
- bindings(),
85
- event:attr("eci"),
86
- meta:rid
87
- ),
88
- "iconURL": "https://example.com/myapp.svg"
89
- });
90
- }
91
- }
92
- ```
93
-
94
- ### Bindings shape
95
-
96
- `bindings()` describes what an integrator may use — not internal rule names.
97
-
98
- | Key | Purpose |
99
- |-----|---------|
100
- | `version` | Bindings schema version (currently `1`) |
101
- | `queries` | `[{"name": "...", "args": [...], "description": "..."}]` callable via `/sky/query/` |
102
- | `events` | `[{"domain": "...", "name": "...", "attrs": [...], "description": "..."}]` sendable to this pico |
103
- | `notifications` | Optional block with `trigger`, `forward`, and `channels` for notification routing |
104
-
105
- ### App metadata
106
-
107
- | Field | Purpose |
108
- |-------|---------|
109
- | `name` | Short id (e.g. `journal`) |
110
- | `title` | Human-readable label (e.g. `Journal`) |
111
- | `version` | App version string |
112
- | `description` | What the app does on this pico — shown to integrators during discovery |
113
-
114
- ### Policy filtering
115
-
116
- Use `wrangler:filterBindingsForCaller(bindings, caller_eci, rid)` in your discovery rule:
117
-
118
- - **`caller_eci`** — from `event:attr("eci")`; pass through when null (unfiltered).
119
- - **`rid`** — `meta:rid` for this ruleset (used to check query policy).
120
-
121
- Filtering uses `wrangler:allowsEventForChannel` and `wrangler:allowsQueryForChannel`, which evaluate the caller channel's policy from `ctx:channels` on this pico.
122
-
123
- ## Directive: `discovery capability`
124
-
125
- Each participating ruleset may emit one directive:
126
-
127
- ```json
128
- {
129
- "name": "discovery capability",
130
- "options": {
131
- "app": {
132
- "name": "myapp",
133
- "title": "My App",
134
- "version": "1.0",
135
- "description": "One sentence explaining what this app does."
136
- },
137
- "rid": "io.picolabs.myapp",
138
- "bindings": { "version": 1, "queries": [], "events": [] },
139
- "iconURL": "https://example.com/myapp.svg"
140
- }
141
- }
142
- ```
143
-
144
- The engine merges directives from all selecting rules. Integrators should handle zero, one, or many capabilities per pico.
@@ -1,151 +0,0 @@
1
- # ctx
2
-
3
- The `ctx` module provides context information and actions for running code. Context includes the pico, ruleset, and engine the code is running for and on.
4
-
5
- ## ctx:picoId
6
-
7
- Get the identifier for the pico assigned by the engine.
8
-
9
- ## ctx:rid
10
-
11
- Get the ruleset id (rid) string.
12
-
13
- ## ctx:rid_version
14
-
15
- The ruleset version string.
16
-
17
- ## ctx:rid_url
18
-
19
- The ruleset url string.
20
-
21
- ## ctx:rid_config
22
-
23
- The configuration Map when the ruleset was installed onto the pico.
24
-
25
- ## ctx:parent
26
-
27
- The eci string of the parent or null if there is no parent.
28
-
29
- ## ctx:children
30
-
31
- A list of the eci strings of the pico's children.
32
-
33
- ## ctx:channels
34
-
35
- A list of all channels this pico owns.
36
-
37
- TODO channel schema
38
-
39
- ## ctx:rulesets
40
-
41
- A list of all the rulesets the pico has installed
42
-
43
- ## ctx:raiseEvent(domain, name, attrs)
44
-
45
- Raise an event to yourself. This event does not use a channel, only runs on the current pico, and happens in the same event schedule.
46
-
47
- - `domain` - String - The event domain.
48
- - `name` - String - The event name.
49
- - `attrs` - Map - The event attributes.
50
-
51
- ## ctx:allowsEvent(eci, domain, name)
52
-
53
- Return `true` when the given channel's event policy would allow an event with this domain and name. Returns `false` for unknown channels or denied events (never throws).
54
-
55
- ## ctx:allowsQuery(eci, rid, name)
56
-
57
- Return `true` when the given channel's query policy would allow this query. Returns `false` for unknown channels or denied queries (never throws).
58
-
59
- ## ctx:query(eci, rid, name, args = {})
60
-
61
- Query a local pico.
62
-
63
- - `eci` - String - Which channel to send the query over.
64
- - `rid` - String - The rid you wish to query.
65
- - `name` - String - The name of the function you wish to query.
66
- - `args` - Map - Any query function arguments where the map keys match the argument name.
67
-
68
- ## ctx:event(eci, domain, name, attrs = {})
69
-
70
- Send an event to a local pico.
71
-
72
- - `eci` - String - Which channel to signal the event to.
73
- - `domain` - String - The event domain.
74
- - `name` - String - The event name.
75
- - `attrs` - Map - The event attributes.
76
-
77
- ## ctx:eventWait(eci, domain, name, attrs = {})
78
-
79
- - `eci` - String - Which channel to signal the event to.
80
- - `domain` - String - The event domain.
81
- - `name` - String - The event name.
82
- - `attrs` - Map - The event attributes.
83
-
84
- ## ctx:eventQuery(eci, domain, name, attrs, rid, qname, args = {})
85
-
86
- Signal an event then query immediately after the event finished processing.
87
-
88
- - `eci` - String - Which channel to signal the event to and query over.
89
- - `domain` - String - The event domain.
90
- - `name` - String - The event name.
91
- - `attrs` - Map - The event attributes.
92
- - `rid` - String - The rid you wish to query.
93
- - `qname` - String - The name from the ruleset you wish to query.
94
- - `args` - Map - Any query function arguments where the map keys match the argument name.
95
-
96
- ## ctx:newPico(rulesets = [])
97
-
98
- Create a new child pico. This returns the channel you can use to talk the child pico.
99
-
100
- - `rulesets` - Array - List of the rulesets you wish installed on this pico when it's created.
101
-
102
- Example:
103
-
104
- ```krl
105
- ctx:newPico([
106
- {"url": "http://.../ruleset.krl", "config": {"some": "config"}}
107
- ])
108
- ```
109
-
110
- ## ctx:delPico(eci)
111
-
112
- Delete a child pico.
113
-
114
- - `eci` - String - The parent's eci for talking to the child. No other eci will work.
115
-
116
- ## ctx:newChannel(tags, eventPolicy, queryPolicy)
117
-
118
- - `tags` - String[] - An array of tags to organize your channels
119
- - `eventPolicy` - EventPolicy - Your event allow/deny rules
120
- - `queryPolicy` - QueryPolicy - Your query allow/deny rules
121
-
122
- ## ctx:putChannel(eci, tags, eventPolicy, queryPolicy)
123
-
124
- Same as newChannel except you provide the eci you whish to modify. Channels can only be modified by their owners.
125
-
126
- ## ctx:upsertChannel(tags, eventPolicy, queryPolicy)
127
-
128
- If there is a channel with the same tags it will update it. Otherwise it will create a new channel.
129
-
130
- ## ctx:delChannel(eci)
131
-
132
- Delete a channel. Only the owner pico can delete their channel.
133
-
134
- ## ctx:install(url, config = {})
135
-
136
- Install a ruleset.
137
-
138
- - `url` - String - The url to the ruleset you wish to install.
139
- - `config` - Map - Any configuration data the ruleset may want.
140
-
141
- ## ctx:uninstall(rid)
142
-
143
- Uninstall a ruleset.
144
-
145
- - `rid` - String - The id of the ruleset you wish to uninstall.
146
-
147
- ## ctx:flush(url)
148
-
149
- Flush a ruleset by fetching the url and reloading it.
150
-
151
- - `url` - String - The url to the ruleset you wish to flush.
@@ -1,70 +0,0 @@
1
- # event
2
-
3
- The `event` module provides access to the current executing event. These return `null` if the code is running when there is no event i.e. query.
4
-
5
- ## event:eci
6
-
7
- Get the event channel id. `String` or `null`
8
-
9
- ## event:domain
10
-
11
- Get the event domain. `String` or `null`
12
-
13
- ## event:name
14
-
15
- Get the event name. `String` or `null`
16
-
17
- ## event:attrs
18
-
19
- Get the event attributes. `Map` or `null`
20
-
21
- ## event:eid
22
-
23
- Get the event transaction id. `String` or `null`
24
-
25
- ## event:time
26
-
27
- Get the event timestamp as number of milliseconds since epoch. `Number` or `null`
28
-
29
- ## event:send
30
-
31
- Send an event to another pico. Action.
32
-
33
- ```krl
34
- event:send({
35
- "eci": "<channel id>", // local or remote ECI
36
- "domain": "wrangler",
37
- "type": "ping", // alias: "name"
38
- "attrs": { "key": "value" }
39
- }, host) // optional host for remote ECI
40
- ```
41
-
42
- **DID-based (1.6+) — send by DID** (requires an established DID-based relationship):
43
-
44
- ```krl
45
- event:send({
46
- "did": "did:peer:2....", // or did:webvh:...
47
- "domain": "wrangler",
48
- "type": "ping",
49
- "attrs": {}
50
- })
51
- ```
52
-
53
- **DID-based — send via established relationship map** (from `relationship:established()` etc.; legacy module name `subscription:established()`):
54
-
55
- ```krl
56
- use module io.picolabs.subscription alias relationship
57
-
58
- event:send({
59
- "sub": bus, // established relationship (bus) map
60
- "domain": "wrangler",
61
- "type": "ping",
62
- "attrs": {}
63
- })
64
- ```
65
-
66
- When `bus.layer2` is true (DID-based relationship), routing uses `Tx_did` and DIDComm (or verified local dispatch on the same engine). ECI-based relationships use `bus.Tx` and optional `bus.Tx_host` as before.
67
-
68
- ## event:attr
69
-
70
- Get a single attribute by name. `Function(name)` → value or `null`
@@ -1,42 +0,0 @@
1
- # http
2
-
3
- This module allows you to make http requests.
4
-
5
- ## http:do(method, url, qs, headers, body, auth, json, form, parseJSON, autoraise, autosignal)
6
-
7
- - `method` - String -
8
- - `url` - String - the http(s) base url
9
- - `qs` - Map - query string values
10
- - `headers` - Map - http headers
11
- - `body` - String - the payload of the data
12
- - TODO rest
13
-
14
- Example:
15
-
16
- ```krl
17
- TODO example
18
- ```
19
-
20
- ## http:get(...)
21
-
22
- Same as `http:do('GET', ...)`
23
-
24
- ## http:post(...)
25
-
26
- Same as `http:do('POST', ...)`
27
-
28
- ## http:put(...)
29
-
30
- Same as `http:do('PUT', ...)`
31
-
32
- ## http:patch(...)
33
-
34
- Same as `http:do('PATCH', ...)`
35
-
36
- ## http:delete(...)
37
-
38
- Same as `http:do('DELETE', ...)`
39
-
40
- ## http:head(...)
41
-
42
- Same as `http:do('HEAD', ...)`
@@ -1,5 +0,0 @@
1
- # math
2
-
3
- The math library provides a number of useful math functions.
4
-
5
- TODO
@@ -1,5 +0,0 @@
1
- # schedule
2
-
3
- Scheduled events allow you to raise an event at a point in time or on a recurring basis.
4
-
5
- TODO
@@ -1,11 +0,0 @@
1
- # KRL Modules
2
-
3
- TODO explain how modules work
4
-
5
- ## Create a KRL module
6
-
7
- TODO explain how
8
-
9
- ## Create a Node.js module for KRL
10
-
11
- TODO explain how
@@ -1,81 +0,0 @@
1
- # KRL Rulesets
2
-
3
- A ruleset is the primary means of program organization in KRL. A ruleset is a collection of rules. Each rule is designed to respond to a specific event.
4
-
5
- Each ruleset can have the following sections.
6
-
7
- - `meta`
8
- - `global`
9
- - `rule`(s)
10
-
11
- ```
12
- ruleset <rid> {
13
- version <string>
14
- meta {
15
- <configuration>
16
- }
17
- global {
18
- <global declarations>
19
- }
20
- rule one {
21
- ...
22
- }
23
- rule two {
24
- ...
25
- }
26
- ...
27
- }
28
- ```
29
-
30
-
31
- ## meta
32
-
33
- The meta section stores information about a ruleset. Meta sections are optional and may be empty.
34
-
35
- The following are allowed in a meta section:
36
-
37
- ### version
38
-
39
- Rulesets are versioned. Version strings follow [Semantic Versioning](https://semver.org/). i.e `1.2.3` where `<major>.<minor>.<patch>`.
40
-
41
- During development you can set the version to `"draft"` or omit it completely. This way you can make frequent changes and see them reflected immediately on the picos that use the "draft" version.
42
-
43
-
44
- TODO
45
-
46
- ## global
47
-
48
- TODO
49
-
50
- ## rule
51
-
52
- TODO
53
-
54
- ### select
55
-
56
- Select statements are the initial condition on whether or not to run a rule.
57
-
58
- There are 2 variants of select
59
-
60
- - `select when <event-expression>`
61
- - `select where <expression>`
62
-
63
- #### select when
64
-
65
- TODO
66
-
67
- #### select where
68
-
69
- The rule will select when the `<expression>` evaluates truthy.
70
-
71
- ### prelude
72
-
73
- TODO
74
-
75
- ### action
76
-
77
- TODO
78
-
79
- ### postlude
80
-
81
- TODO
@@ -1,3 +0,0 @@
1
- # KRL Standard Library
2
-
3
- TODO