pico-engine 1.9.4 → 1.10.0

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 (186) hide show
  1. package/README.md +13 -5
  2. package/demos/bootstrap/README.md +12 -0
  3. package/demos/bootstrap/com.example.visitors.bootstrap.krl +101 -0
  4. package/demos/bootstrap/com.example.visitors.format.krl +25 -0
  5. package/demos/bootstrap/com.example.visitors.krl +228 -0
  6. package/demos/bootstrap/try-it.md +5 -0
  7. package/demos/child_tasks/README.md +12 -0
  8. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +88 -0
  9. package/demos/child_tasks/com.example.task_runner.krl +139 -0
  10. package/demos/child_tasks/com.example.task_worker.krl +45 -0
  11. package/demos/child_tasks/try-it.md +5 -0
  12. package/demos/collection/README.md +13 -0
  13. package/demos/collection/com.example.collection.bootstrap.krl +148 -0
  14. package/demos/collection/com.example.collection.krl +95 -0
  15. package/demos/collection/com.example.collection.report.krl +93 -0
  16. package/demos/collection/com.example.collection.room.krl +101 -0
  17. package/demos/collection/try-it.md +6 -0
  18. package/demos/echo/README.md +11 -0
  19. package/demos/echo/com.example.echo.bootstrap.krl +84 -0
  20. package/demos/echo/com.example.echo.krl +73 -0
  21. package/demos/echo/try-it.md +5 -0
  22. package/demos/guard_rules/README.md +12 -0
  23. package/demos/guard_rules/com.example.archive.bootstrap.krl +98 -0
  24. package/demos/guard_rules/com.example.archive.krl +213 -0
  25. package/demos/guard_rules/com.example.archive_store.krl +36 -0
  26. package/demos/guard_rules/try-it.md +5 -0
  27. package/demos/json_query/README.md +11 -0
  28. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  29. package/demos/json_query/com.example.json_query.krl +162 -0
  30. package/demos/json_query/try-it.md +5 -0
  31. package/demos/kblog/README.md +14 -0
  32. package/demos/kblog/com.example.kblog.bootstrap.krl +135 -0
  33. package/demos/kblog/com.example.kblog.config.krl +50 -0
  34. package/demos/kblog/com.example.kblog.data.krl +75 -0
  35. package/demos/kblog/com.example.kblog.krl +184 -0
  36. package/demos/kblog/com.example.kblog.posting.krl +109 -0
  37. package/demos/kblog/try-it.md +6 -0
  38. package/demos/layered_rulesets/README.md +13 -0
  39. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +87 -0
  40. package/demos/layered_rulesets/com.example.invitations.krl +164 -0
  41. package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
  42. package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
  43. package/demos/layered_rulesets/try-it.md +5 -0
  44. package/demos/moving_picos/README.md +15 -0
  45. package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
  46. package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
  47. package/demos/score_tracker/README.md +11 -0
  48. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +107 -0
  49. package/demos/score_tracker/com.example.score_tracker.krl +162 -0
  50. package/demos/score_tracker/try-it.md +5 -0
  51. package/demos/secrets/README.md +12 -0
  52. package/demos/secrets/com.example.hook_service.krl +120 -0
  53. package/demos/secrets/com.example.notifier.bootstrap.krl +130 -0
  54. package/demos/secrets/com.example.notifier.krl +138 -0
  55. package/demos/secrets/try-it.md +5 -0
  56. package/demos/try-it-order.json +1 -0
  57. package/demos/two_picos/README.md +12 -0
  58. package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
  59. package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
  60. package/demos/two_picos/com.example.two_picos.bootstrap.krl +134 -0
  61. package/demos/two_picos/try-it.md +5 -0
  62. package/demos/xmlui/README.md +17 -0
  63. package/demos/xmlui/com.example.contacts.krl +132 -0
  64. package/demos/xmlui/com.example.fav_color.krl +39 -0
  65. package/demos/xmlui/com.example.guestbook.krl +61 -0
  66. package/demos/xmlui/com.example.hello.krl +19 -0
  67. package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
  68. package/demos/xmlui/com.example.thermostat.bootstrap.krl +95 -0
  69. package/demos/xmlui/com.example.thermostat.krl +124 -0
  70. package/demos/xmlui/temperature_sensors.krl +56 -0
  71. package/demos/xmlui/try-it.md +5 -0
  72. package/dist/bundledKrl.js +97 -12
  73. package/dist/cli.js +7 -1
  74. package/dist/engineConfig.js +20 -1
  75. package/dist/identity/portableMove.js +5 -1
  76. package/dist/index.js +45 -12
  77. package/dist/internalAccess.js +110 -0
  78. package/dist/oauth/OAuthService.js +172 -10
  79. package/dist/oauth/acg.js +194 -24
  80. package/dist/oauth/cimd.js +381 -0
  81. package/dist/oauth/discovery.js +175 -0
  82. package/dist/runMcp.js +1 -1
  83. package/dist/server.js +210 -47
  84. package/dist/subtreeWrangler.js +8 -5
  85. package/dist/uiChannelPolicies.js +2 -0
  86. package/krl/io.picolabs.pds.krl +109 -21
  87. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  88. package/krl/io.picolabs.wrangler.krl +21 -9
  89. package/krl/io.picolabs.xmlui.krl +3 -2
  90. package/mcp/devResources.js +52 -0
  91. package/mcp/devTools.js +40 -9
  92. package/mcp/docs/CLAUDE.md +6 -4
  93. package/mcp/docs/cookbook/README.md +23 -0
  94. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  95. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  96. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  97. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  98. package/mcp/docs/cookbook/collection/README.md +21 -0
  99. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  100. package/mcp/docs/cookbook/echo/README.md +19 -0
  101. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  102. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  103. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  104. package/mcp/docs/cookbook/json_query/README.md +26 -0
  105. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  106. package/mcp/docs/cookbook/kblog/README.md +60 -0
  107. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  108. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  109. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  110. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  111. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  112. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  113. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  114. package/mcp/docs/cookbook/secrets/README.md +25 -0
  115. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  116. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  117. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  118. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  119. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  120. package/mcp/docs/developing/README.md +28 -0
  121. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  122. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  123. package/mcp/docs/developing/converting-time-formats.md +28 -0
  124. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  125. package/mcp/docs/developing/decoding-form-data.md +67 -0
  126. package/mcp/docs/developing/engine-log-files.md +34 -0
  127. package/mcp/docs/developing/event-loop.md +77 -0
  128. package/mcp/docs/developing/events-from-email.md +80 -0
  129. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  130. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  131. package/mcp/docs/developing/misconceptions.md +467 -0
  132. package/mcp/docs/developing/names-and-scope.md +44 -0
  133. package/mcp/docs/developing/postman.md +159 -0
  134. package/mcp/docs/developing/querying-another-pico.md +47 -0
  135. package/mcp/docs/developing/singleton-picos.md +36 -0
  136. package/mcp/docs/developing/tabular-data.md +67 -0
  137. package/mcp/docs/developing/tips.md +251 -0
  138. package/mcp/docs/developing/webhook-signatures.md +56 -0
  139. package/mcp/docs/developing/workflow.md +106 -0
  140. package/mcp/docs/exp/README.md +46 -0
  141. package/mcp/docs/exp/event.md +110 -0
  142. package/mcp/docs/exp/query.md +94 -0
  143. package/mcp/docs/lessons/README.md +59 -0
  144. package/mcp/docs/lessons/events-and-queries.md +247 -0
  145. package/mcp/docs/lessons/gossip.md +28 -0
  146. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  147. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  148. package/mcp/docs/lessons/pico-state.md +267 -0
  149. package/mcp/docs/lessons/pico-views.md +290 -0
  150. package/mcp/docs/lessons/quickstart.md +157 -0
  151. package/mcp/docs/lessons/relationships.md +530 -0
  152. package/mcp/docs/lessons/scatter-gather.md +362 -0
  153. package/mcp/docs/pico-engine.md +10 -5
  154. package/mcp/docs/pico-overview.md +3 -3
  155. package/mcp/docs/wrangler/README.md +47 -0
  156. package/mcp/docs/wrangler/channels.md +235 -0
  157. package/mcp/docs/wrangler/oauth.md +56 -0
  158. package/mcp/docs/wrangler/pds.md +423 -0
  159. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  160. package/mcp/docs/wrangler/relationships.md +297 -0
  161. package/mcp/docs/wrangler/wrangler.md +253 -0
  162. package/mcp/docs/wrangler/xmlui.md +60 -0
  163. package/mcp/engineClient.js +57 -5
  164. package/mcp/mcpScopes.js +118 -0
  165. package/mcp/meshHttp.js +151 -45
  166. package/mcp/runStdio.js +2 -0
  167. package/mcp/subtreeTools.js +184 -0
  168. package/mcp/tryItTools.js +202 -0
  169. package/package.json +18 -9
  170. package/public/.DS_Store +0 -0
  171. package/public/pico-engine-ui.css +1 -1
  172. package/public/pico-engine-ui.js +26 -25
  173. package/src/bundledKrl.ts +118 -12
  174. package/src/cli.ts +8 -2
  175. package/src/engineConfig.ts +33 -2
  176. package/src/identity/portableMove.ts +6 -1
  177. package/src/index.ts +469 -422
  178. package/src/internalAccess.ts +127 -0
  179. package/src/oauth/OAuthService.ts +243 -11
  180. package/src/oauth/acg.ts +289 -25
  181. package/src/oauth/cimd.ts +508 -0
  182. package/src/oauth/discovery.ts +233 -0
  183. package/src/runMcp.ts +3 -1
  184. package/src/server.ts +266 -51
  185. package/src/subtreeWrangler.ts +17 -5
  186. package/src/uiChannelPolicies.ts +2 -0
@@ -0,0 +1,98 @@
1
+ # Configuration and secrets: instructions
2
+
3
+ These steps use the developer UI of a running engine at `http://localhost:3000`. Replace that with your engine's URL. See the [overview](/cookbook/secrets/) for what the demo shows.
4
+
5
+ ## The quick way: Try It!
6
+
7
+ On the root pico in the developer UI, open the **Try It!** tab, click **Configuration and secrets**, then **Run in a new child pico**. When it shows **ready**, open **Notifier** and **Hook service inbox**.
8
+
9
+ - The Notifier page says where it posts, with the token hidden. One message was not sent, because it came before the webhook was set. One was delivered, with HTTP status 200.
10
+ - The inbox has the delivered message, and no refused posts.
11
+
12
+ ## By hand
13
+
14
+ 1. Create a pico for the hook service. On its **Rulesets** tab, install `http://localhost:3000/krl/io.picolabs.xmlui.krl`. Then install `http://localhost:3000/krl/demos/secrets/com.example.hook_service.krl` with a configuration, such as `{"token": "pick-a-long-random-string"}` (the **Rulesets** tab has a box for it).
15
+ 2. The hook service sends its webhook URL to its parent pico as `hook_service:webhook_url_issued`. Find it in the parent's **Logging** tab, or build it yourself: `http://localhost:3000/sky/event/<eci>/webhook/hook/post?token=<token>`, where `<eci>` is the hook service's channel tagged `hook_service, webhook`.
16
+ 3. Create a pico for the notifier and install `io.picolabs.xmlui` and `http://localhost:3000/krl/demos/secrets/com.example.notifier.krl` on it. Open its page on the `notifier, app` channel and send a message: it is not sent.
17
+ 4. On the notifier's **Testing** tab, raise `notifier_config` `new_webhook` with `webhook_url` set to the URL from step 2. Send a message from the page again: it is delivered.
18
+
19
+ ## Try it
20
+
21
+ - On the Notifier page, send a few messages. Each appears in the inbox and in the Notifier's list with status 200.
22
+ - Post to the webhook with the wrong token. Take the URL the Notifier page shows, replace `(hidden)` with anything, and `curl -X POST` it. The hook service answers with a `refused` directive, and its **Refused** count goes up.
23
+ - On the Notifier's **Testing** tab, raise `notifier_config` `webhook_forgotten`. Messages from the page are counted as not sent again.
24
+
25
+ ## Where the secrets are visible
26
+
27
+ Neither secret is in a ruleset file. That is the point of both methods. But both can still be seen, by anyone who can see the developer UI or the engine's files:
28
+
29
+ | Where | What shows |
30
+ |-------|------------|
31
+ | **Rulesets** tab, on the hook service | The install configuration, with the token, for as long as the ruleset is installed. `wrangler:rulesetConfig` returns it too, to anyone with a channel that allows that query |
32
+ | **Logging** tab | Every event's attributes: the install request with its `config`, the `webhook_url_issued` and `new_webhook` events with the URL, and every `hook:post`, because the token is in the URL |
33
+ | `pico-engine.log` in the engine's home directory | The same events, until the log files rotate away |
34
+ | The pico's database | The entity variables: the notifier's `ent:webhook_url` |
35
+
36
+ The **Testing** tab hides the values of attributes named like `password`, `secret`, `token`, or `apikey` in its own saved history. The engine's logs don't.
37
+
38
+ What the rulesets do to help:
39
+
40
+ - The notifier shares `status()`, which hides the token, and never shares the URL itself.
41
+ - `notifier_config:new_webhook` is in its own domain, and the app channel allows only `notifier` events. The page can send messages but can't change where they go. Put operator events in a domain the app channel doesn't allow.
42
+ - The rule that posts is selected only `where ent:webhook_url`, so the notifier is idle, not failing, until it has a URL.
43
+
44
+ ## How it works
45
+
46
+ **From install configuration.** The hook service reads its token from the configuration it was installed with:
47
+
48
+ ```krl
49
+ token = function() {
50
+ meta:rulesetConfig{"token"}
51
+ }
52
+ ```
53
+
54
+ The bootstrap installs it with `"config": {"token": random:uuid()}`, so each run gets a new token.
55
+
56
+ **From an event.** The notifier keeps the URL it is sent:
57
+
58
+ ```krl
59
+ rule set_webhook {
60
+ select when notifier_config new_webhook
61
+ webhook_url re#^(https?://.+)$#
62
+ setting(url)
63
+ always {
64
+ ent:webhook_url := url
65
+ ent:configured_at := time:now()
66
+ }
67
+ }
68
+ ```
69
+
70
+ **Idle until configured.** Two rules select `notifier:message`, and their `where` clauses decide which one runs:
71
+
72
+ ```krl
73
+ rule notify {
74
+ select when notifier message where ent:webhook_url
75
+ pre {
76
+ text = event:attr("text") || "Hello from a pico"
77
+ }
78
+ http:post(ent:webhook_url, json = {"text": text}) setting(response)
79
+ fired {
80
+ ent:deliveries := deliveries().append({"text": text, "status": response{"status_code"}, "time": time:now()})
81
+ }
82
+ }
83
+
84
+ rule not_configured {
85
+ select when notifier message where not ent:webhook_url
86
+ ...
87
+ }
88
+ ```
89
+
90
+ **Accepting or refusing.** The hook service's webhook channel allows only `hook:post`. Its `receive` rule selects posts `where event:attr("token") == token()`, and `refuse` selects the rest.
91
+
92
+ ## Change it and watch
93
+
94
+ The **Try It!** window lists each file with its path on disk. Edit a file there, click **Flush**, and use the pages.
95
+
96
+ - Show less: in `com.example.notifier.krl`, make `masked` hide everything after the host, not just the token.
97
+ - Use configuration for the notifier too: read the URL from `meta:rulesetConfig{"webhook_url"}` when `ent:webhook_url` is not set, and reinstall it with a configuration on the **Rulesets** tab. Then look at where the URL shows.
98
+ - Rotate the token: on the hook service's **Rulesets** tab, install `com.example.hook_service` again from the same URL with a new configuration. Messages from the notifier now raise the inbox's **Refused** count. The Notifier still records status 200, because the hook service answers every post and says "refused" in a directive. Make `notify` record the directive's name, or send the notifier the new URL with `notifier_config` `new_webhook`.
@@ -0,0 +1,20 @@
1
+ # Two picos talking
2
+
3
+ Picos talk to each other over **relationships**. A relationship is a pair of channels, one on each pico, made for that connection and labeled with each side's role. This demo has two picos. Alice is an *answerer* who knows some facts about herself. Bob is an *asker*. Bob asks Alice for a relationship, Alice accepts, and Bob asks her questions by querying her over it.
4
+
5
+ Neither pico needs the other's family channels or knows where it lives in the pico tree. Bob reaches Alice only through the relationship, and only for what Alice's ruleset shares.
6
+
7
+ To run it, follow the [instructions](/cookbook/two_picos/instructions).
8
+
9
+ ## The rulesets
10
+
11
+ | Ruleset | File | What it shows |
12
+ |---------|------|---------------|
13
+ | Answerer (Alice) | [`com.example.two_picos.answerer.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/two_picos/com.example.two_picos.answerer.krl) | Accepting relationship requests by role (`inbound_pending_subscription_added`, `pending_subscription_approval`), a shared `answer` function, and a page to teach Alice facts |
14
+ | Asker (Bob) | [`com.example.two_picos.asker.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/two_picos/com.example.two_picos.asker.krl) | Asking for a relationship through a well-known channel (`wrangler:subscription`), reacting to `subscription_added`, and querying the other side with `subscription:queryOnSub`. Has a conversation page |
15
+ | Bootstrap | [`com.example.two_picos.bootstrap.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/two_picos/com.example.two_picos.bootstrap.krl) | Creates Alice and Bob as children, installs their rulesets, and introduces Bob to Alice's well-known channel. The developer UI's **Try It!** tab runs it |
16
+
17
+ ## What you need
18
+
19
+ - A running pico engine (1.9.4 or later for the pages, which use the shared `PicoTheme` component).
20
+ - `io.picolabs.xmlui` on Alice and Bob for their pages. The bootstrap installs it.
@@ -0,0 +1,88 @@
1
+ # Two picos talking: instructions
2
+
3
+ These steps use the developer UI of a running engine at `http://localhost:3000`. Replace that with your engine's URL. See the [overview](/cookbook/two_picos/) for what the demo shows.
4
+
5
+ ## The quick way: Try It!
6
+
7
+ On the root pico in the developer UI, open the **Try It!** tab, click **Two picos talking**, then **Run in a new child pico**. The bootstrap creates two children, Alice and Bob, and introduces them. When it shows **ready**, Bob has already asked his first question. Open **Bob's conversation** and **What Alice knows**.
8
+
9
+ ## By hand
10
+
11
+ 1. Create two child picos, Alice and Bob.
12
+ 2. On each, install `io.picolabs.xmlui` from the engine: `http://localhost:3000/krl/io.picolabs.xmlui.krl`.
13
+ 3. On Alice, install `http://localhost:3000/krl/demos/two_picos/com.example.two_picos.answerer.krl`.
14
+ 4. On Bob, install `http://localhost:3000/krl/demos/two_picos/com.example.two_picos.asker.krl`.
15
+ 5. Find Alice's well-known channel: on Alice's **Channels** tab, it is the channel tagged `wellknown_rx, tx_rx`. Copy its id.
16
+ 6. On Bob's **Testing** tab, raise `two_picos` `introduce` with `wellKnown_Tx` set to that id.
17
+ 7. Both picos' **Relationships** tabs now show the relationship, and Bob has asked about Alice's favorite color. Open Bob's page on his `two_picos, asker` channel and Alice's on her `two_picos, answerer` channel (**View** on the **Rulesets** tab).
18
+
19
+ ## Try it
20
+
21
+ - On Bob's page, ask about `cat`, `hometown`, or `name`. Each answer comes from Alice's pico.
22
+ - Ask about something Alice doesn't know, such as `favorite food`. She says she doesn't know it yet.
23
+ - On Alice's page, teach her that fact, then ask Bob to ask again.
24
+ - Look at the **Relationships** tab on each pico. Bob's role is `asker`, Alice's is `answerer`, and each side has its own channel for the other.
25
+
26
+ ## How it works
27
+
28
+ **Bob asks for a relationship.** Every pico has a well-known channel that accepts only relationship requests. Given Alice's, Bob asks for a relationship and names both roles:
29
+
30
+ ```krl
31
+ raise wrangler event "subscription" attributes {
32
+ "wellKnown_Tx": well_known,
33
+ "name": "Bob and Alice",
34
+ "Rx_role": "asker",
35
+ "Tx_role": "answerer"
36
+ }
37
+ ```
38
+
39
+ **Alice accepts.** The request arrives at Alice as `wrangler:inbound_pending_subscription_added`, with the roles swapped to her point of view: her `Rx_role` is `answerer`. She accepts only requests that cast her in that role:
40
+
41
+ ```krl
42
+ rule accept_asker {
43
+ select when wrangler inbound_pending_subscription_added
44
+ where event:attr("Rx_role") == "answerer"
45
+ always {
46
+ raise wrangler event "pending_subscription_approval" attributes event:attrs
47
+ }
48
+ }
49
+ ```
50
+
51
+ **Bob hears back.** When Alice accepts, Bob's wrangler raises `wrangler:subscription_added`. Bob's `connected` rule checks that the other side is an answerer, tells the parent pico, and asks a first question.
52
+
53
+ **Bob queries Alice.** `ask` finds the relationship by role and calls Alice's shared `answer` function over it:
54
+
55
+ ```krl
56
+ bus = subscription:established("Tx_role", "answerer").head()
57
+ reply = subscription:queryOnSub(bus{"Id"}, answerer_rid, "answer", {"question": question})
58
+ ```
59
+
60
+ The query goes to the channel Alice made for Bob when she accepted. Bob uses that channel, not Alice's family channel or her app channel. Relationship channels allow every event and query, so what Bob can do to Alice is up to the rulesets she has installed.
61
+
62
+ **The bootstrap.** It creates Alice and Bob with `new_child_request` and installs their rulesets when `child_initialized` arrives. Each child sends `two_picos:child_ready` to the parent when its ruleset is installed. When both are ready, the parent queries Alice's well-known channel id (`wrangler:picoQuery(alice, "io.picolabs.subscription", "wellKnown_Rx")`) and sends Bob `two_picos:introduce`. That starts everything above.
63
+
64
+ ## Change it and watch
65
+
66
+ The **Try It!** window lists each file with its path on disk. Edit a file there, click **Flush**, and use the pages again.
67
+
68
+ - In `com.example.two_picos.answerer.krl`, change how Alice answers. For example, make `answer` return `known.uc()`.
69
+ - Change `initial_facts`. The facts are set when the answerer is installed, so run the demo again to see new ones, or teach them on Alice's page.
70
+ - In `com.example.two_picos.asker.krl`, change the first question in `connected` from `favorite color` to another topic, and run the demo again.
71
+ - Let Bob teach Alice. Add a rule to `com.example.two_picos.asker.krl` that sends her an event over the relationship:
72
+
73
+ ```krl
74
+ rule teach {
75
+ select when two_picos teach
76
+ pre {
77
+ bus = subscription:established("Tx_role", "answerer").head()
78
+ }
79
+ if bus then event:send({
80
+ "eci": bus{"Tx"},
81
+ "domain": "two_picos",
82
+ "type": "fact_learned",
83
+ "attrs": {"topic": event:attr("topic"), "value": event:attr("value")}
84
+ })
85
+ }
86
+ ```
87
+
88
+ Flush it, raise `two_picos` `teach` on Bob's **Testing** tab with a `topic` and `value`, and Alice's page shows the new fact.
@@ -0,0 +1,23 @@
1
+ # Pico views
2
+
3
+ Seven small rulesets that serve [XMLUI](https://xmlui.org) pages from a pico. Each one adds one idea, from a static page to a view that shows another pico's data. They are also the test fixtures for the engine's view routes.
4
+
5
+ Read [Pico views](/pico-views) for how views work. To install and open these, follow the [instructions](/cookbook/xmlui/instructions).
6
+
7
+ ## The rulesets
8
+
9
+ | Ruleset | File | What it shows |
10
+ |---------|------|---------------|
11
+ | Hello | [`com.example.hello.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.hello.krl) | A `@view` function and nothing else |
12
+ | Favorite color | [`com.example.fav_color.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.fav_color.krl) | Reading with `ui:query` and writing with `ui:event`, then refreshing |
13
+ | Guestbook | [`com.example.guestbook.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.guestbook.krl) | An app channel created on install with `ui:create_app_channel` |
14
+ | Contacts | [`com.example.contacts.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.contacts.krl) | A list page and a detail page (`/contact/:id`), seeded with two contacts |
15
+ | Thermostat | [`com.example.thermostat.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.thermostat.krl) | Two channels with different policies (viewer and admin), an app `@component`, and the shared `PicoSettings`, `PicoThemeField`, and `PicoTheme` components |
16
+ | Thermostat bootstrap | [`com.example.thermostat.bootstrap.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.thermostat.bootstrap.krl) | Sets up the whole Thermostat demo on a new pico. The developer UI's **Try It!** tab runs it |
17
+ | Temperature sensors (data) | [`temperature_sensors.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/temperature_sensors.krl) | Sample readings on a data pico |
18
+ | Temperature sensors (view) | [`com.example.temperature_sensors_view.krl`](https://github.com/Picolab/pico-engine/blob/master/demos/xmlui/com.example.temperature_sensors_view.krl) | A view on one pico over data on another, reached through a relationship |
19
+
20
+ ## What you need
21
+
22
+ - A running pico engine. Components (`@component` and the shared `Pico*` components, used by Thermostat) need pico-engine 1.9.4 or later.
23
+ - `io.picolabs.xmlui` installed on each pico that serves a view. The engine ships it at `/krl/io.picolabs.xmlui.krl` but does not install it anywhere by default.
@@ -0,0 +1,84 @@
1
+ # Pico views: instructions
2
+
3
+ These steps use the developer UI of a running engine at `http://localhost:3000`. Replace that with your engine's URL. See the [overview](/cookbook/xmlui/) for what each ruleset shows.
4
+
5
+ ## The quick way: Try It!
6
+
7
+ Open the root pico in the developer UI and choose the **Try It!** tab. (Operators can show the tab on every pico, or hide it, with `show_tryit_menu` in the engine config.) Click **Thermostat**, then **Run in a new child pico**. The tab creates a child pico and installs `com.example.thermostat.bootstrap` on it. That one ruleset installs `io.picolabs.xmlui` and the thermostat, and records three readings. When the demo shows **ready**, open the dashboard links. **Delete Child** deletes the child pico.
8
+
9
+ The same window shows **the code**: the bootstrap and the rulesets it installed, each with its path on the engine's machine. Change one. For example, in `com.example.thermostat.krl` change `ent:threshold.defaultsTo(80)` to `65`, click **Flush**, and reload the dashboard: it says "Alert above 65 F". To contribute a change, make it in a clone of the [pico-engine repository](https://github.com/Picolab/pico-engine) and open a pull request.
10
+
11
+ The steps below do the same by hand, for every demo.
12
+
13
+ ## 1. Prepare a pico
14
+
15
+ 1. Open the developer UI and sign in.
16
+ 2. Pick the pico that will serve the views. A new child pico keeps the demos apart from everything else.
17
+ 3. On its **Rulesets** tab, install `io.picolabs.xmlui` from the engine:
18
+
19
+ ```
20
+ http://localhost:3000/krl/io.picolabs.xmlui.krl
21
+ ```
22
+
23
+ ## 2. Install a demo
24
+
25
+ On the same **Rulesets** tab, install the demo by URL. Use the raw GitHub file:
26
+
27
+ ```
28
+ https://raw.githubusercontent.com/Picolab/pico-engine/master/demos/xmlui/com.example.hello.krl
29
+ ```
30
+
31
+ or a `file://` URL to your checkout of the repository:
32
+
33
+ ```
34
+ file:///path/to/pico-engine/demos/xmlui/com.example.hello.krl
35
+ ```
36
+
37
+ Install the others the same way: `com.example.fav_color.krl`, `com.example.guestbook.krl`, `com.example.contacts.krl`, `com.example.thermostat.krl`.
38
+
39
+ ## 3. Open it
40
+
41
+ A ruleset with a `@view` function has a **View** button on the Rulesets tab. Click it, pick a channel, and open the app. The page is at:
42
+
43
+ ```
44
+ http://localhost:3000/ui/<eci>/<rid>/
45
+ ```
46
+
47
+ `http://localhost:3000/ui/<eci>/` lists every app that channel can open.
48
+
49
+ The channel must allow `io.picolabs.xmlui` / `file` and the view's functions. Guestbook, Contacts, and Thermostat create channels like that when they are installed. Use those channels (tags `guestbook, app`, `contacts, app`, `thermostat, viewer`, `thermostat, admin`).
50
+
51
+ ## 4. Try each demo
52
+
53
+ **Hello.** The page shows a heading and the ruleset id. There is nothing to click.
54
+
55
+ **Favorite color.** Enter a color such as `#3366cc` and submit. The card shows the color you picked. Reload the page: the pico remembers it.
56
+
57
+ **Guestbook.** Open it on the `guestbook, app` channel. Sign with a name and a message. The table refreshes with your entry.
58
+
59
+ **Contacts.** Open it on the `contacts, app` channel. It starts with Ada Lovelace and Grace Hopper. Add a contact, then click a name to open its detail page and add a note.
60
+
61
+ **Thermostat.** It has no readings until you send some. On the **Testing** tab, raise `thermostat` `new_reading` with `temperature` set to `72`, then `75`. Then open it on each of its channels:
62
+
63
+ - `thermostat, viewer` shows only the Dashboard. The Settings page is not reachable on this channel.
64
+ - `thermostat, admin` shows Dashboard and Settings. Settings changes the alert threshold.
65
+
66
+ On the Dashboard, **Display** opens a theme picker built from the shared `PicoSettings` and `PicoThemeField` components. The readings table is the ruleset's own `ReadingHistory` component.
67
+
68
+ **Temperature sensors (two picos).**
69
+
70
+ 1. Create two child picos, one for the data and one for the view.
71
+ 2. On the data pico, install `temperature_sensors.krl`.
72
+ 3. On the view pico, install `io.picolabs.xmlui` and `com.example.temperature_sensors_view.krl`.
73
+ 4. Create a relationship between the two picos. On the view pico's **Relationships** tab, note the relationship's `Id`. It is the same on both picos.
74
+ 5. On the view pico, raise `temperature_sensors_view` `link_data_pico` with `relationship_id` set to that `Id`.
75
+ 6. Open the view on its `temperature_sensors_view, app` channel. The table shows the data pico's readings.
76
+
77
+ ## If something doesn't load
78
+
79
+ | Symptom | Check |
80
+ |---------|-------|
81
+ | HTTP 403 | The channel's query policy does not allow `io.picolabs.xmlui` / `file`, or the view function |
82
+ | HTTP 404, or a component not found | `io.picolabs.xmlui` is not installed on this pico, or the function is not a `@view` or `@component` the channel allows |
83
+ | The page loads but shows no data | The channel does not allow the page's queries or events, or (on an OAuth mesh) no access token is set |
84
+ | A change to the KRL doesn't show | Flush the ruleset on the Rulesets tab, then reload the page |
@@ -0,0 +1,28 @@
1
+ # Developing with Picos
2
+
3
+ Practical notes for people writing KRL and running picos on the pico engine: how a ruleset gets from your editor into a running pico, what the engine does when an event arrives, and the mistakes that cost the most time.
4
+
5
+ If you're new, start with the [Programming lessons](/lessons/), which build a working system step by step. Come back here when you want the "why did that happen?" and "how do I set things up?" answers.
6
+
7
+ ## In this section
8
+
9
+ 1. [Programming Workflow](/developing/workflow): develop, build, deploy, test, and release a ruleset.
10
+ 2. [Event Loop Introduction](/developing/event-loop): the five phases a pico goes through for every event, and why rule order can surprise you.
11
+ 3. [Tips](/developing/tips): engine setup, hosting and flushing rulesets, `krl-check`, and short technique tips (data, HTTP, picos working together).
12
+ 4. [Event and Query URLs with Postman](/developing/postman): building Sky event and query requests in Postman (or `curl`).
13
+ 5. [KRL misconceptions and common errors](/developing/misconceptions): where habits from other languages mislead, and the typos that are hard to see.
14
+ 6. [Webhook signatures](/developing/webhook-signatures): check a Square-style signature over the raw body.
15
+ 7. [AI tools over MCP](/developing/mcp-ai-tools): connect Claude, or another remote MCP client, to a channel or a mesh.
16
+
17
+ ## Elsewhere in the docs
18
+
19
+ - [Programming lessons](/lessons/): hands-on lessons from the Quickstart to scatter-gather.
20
+ - [KRL manual](/krl/): the language and its libraries.
21
+ - [Event Exchange Protocol](/exp/): the Sky event and query APIs.
22
+ - [Cookbook](/cookbook/): runnable demos from the **Try It!** tab.
23
+
24
+ The engine listens on port 3000 by default, so the examples here use `http://localhost:3000`. Change that if you've configured another port or public URL (see the [operator guide](/pico-engine)).
25
+
26
+ ---
27
+
28
+ <small>Section intro for pages ported from the Pico Labs wiki (Programming Workflow, Event Loop Introduction, Developer Tips, Event and Query URLs with Postman, KRL misconceptions, and the KRL Cookbook tips), updated for this engine.</small>
@@ -0,0 +1,65 @@
1
+ # Accepting relationship requests
2
+
3
+ When another pico asks for a relationship, the request waits on the receiving pico (its **Relationships** tab lists it) until something approves it. Here are three ways to approve requests automatically. The examples share one setup: a list pico asks participant picos to join it, in the role `participant list` for itself and `participant` for them.
4
+
5
+ ## A rule that approves
6
+
7
+ On each participant:
8
+
9
+ ```krl
10
+ rule accept_list {
11
+ select when wrangler inbound_pending_subscription_added
12
+ where event:attr("Rx_role") == "participant"
13
+ && event:attr("Tx_role") == "participant list"
14
+ always {
15
+ raise wrangler event "pending_subscription_approval" attributes event:attrs
16
+ }
17
+ }
18
+ ```
19
+
20
+ Passing the event's attributes along tells wrangler which request to approve. Roles arrive from the receiving pico's point of view: `Rx_role` is this pico's, and `Tx_role` is the other pico's.
21
+
22
+ Don't approve every request. A rule without a `where` accepts a relationship with any pico that has your well-known channel. Accept only what you expect: the right roles, a request from your parent, a request that carries a shared secret. To refuse, raise `wrangler:inbound_rejection` with the same attributes. The [Collection](/cookbook/collection/) demo does both, and remembers whom it turned away.
23
+
24
+ ## Wrangler's auto-accept configuration
25
+
26
+ Without writing a rule, give the participant a pattern to accept:
27
+
28
+ ```krl
29
+ raise wrangler event "autoAcceptConfigUpdate" attributes {
30
+ "config": {"configName": "lists", "entries": {"Tx_role": ["^participant list$"]}}
31
+ }
32
+ ```
33
+
34
+ Each entry maps an attribute of the request, as the participant sees it, to a list of regular expressions. A request that matches any of them is approved. Send the same event with `"delete": true` and the `configName` to remove it. `autoAcceptConfig()`, shared by `io.picolabs.subscription`, shows what is set. You can also send this event from the pico's **Testing** tab.
35
+
36
+ ## Accept later, by installing a ruleset
37
+
38
+ If a request arrived before there was anything to approve it, install a ruleset that approves it and then removes itself:
39
+
40
+ ```krl
41
+ ruleset acceptance {
42
+ meta {
43
+ use module io.picolabs.subscription alias subs
44
+ }
45
+ rule initialize {
46
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
47
+ pre {
48
+ s = subs:inbound("Tx_role", "participant list")
49
+ .filter(function(i) { i{"Rx_role"} == "participant" })
50
+ .head()
51
+ }
52
+ if s then noop()
53
+ fired {
54
+ raise wrangler event "pending_subscription_approval" attributes s
55
+ }
56
+ finally {
57
+ raise wrangler event "uninstall_ruleset_request" attributes {"rid": meta:rid}
58
+ }
59
+ }
60
+ }
61
+ ```
62
+
63
+ It looks for a pending request from a participant list, approves it, and uninstalls itself either way. This is handy when a parent asked many children to join before they could accept: install it on each child.
64
+
65
+ *From the Pico Labs KRL Cookbook pages "Automatic Replies to Subscription Requests" and "Accepting a subscription offer by installing a ruleset".*
@@ -0,0 +1,77 @@
1
+ # Arrays and maps
2
+
3
+ KRL has no `for` loop in expressions. Array operators do the same work: `map`, `filter`, `reduce`, `sort`, and the others in [Array operators](/krl/krl-expression-language/operators/array-operators). Here are a few patterns that come up often.
4
+
5
+ ## Loop with `reduce`
6
+
7
+ To repeat a step a fixed number of times, `reduce` over a range and carry the state in the accumulator. This converts a number to an 8-byte array, high byte first, the way this JavaScript does:
8
+
9
+ ```js
10
+ for (var index = 0; index < byteArray.length; index++) {
11
+ var byte = long & 0xff;
12
+ byteArray[index] = byte;
13
+ long = (long - byte) / 256;
14
+ }
15
+ ```
16
+
17
+ ```krl
18
+ toByteArray = function(str) {
19
+ 1.range(8)
20
+ .reduce(function(a, i) {
21
+ [a[0].append(a[1] % 256), math:int(a[1] / 256)]
22
+ }, [[], str.as("Number")])
23
+ .head()
24
+ .reverse()
25
+ }
26
+ ```
27
+
28
+ `1.range(8)` is `[1, 2, ... 8]`. It only counts; the function doesn't use `i`. The accumulator is a pair: the bytes so far, and what's left of the number. Each step appends the low byte and divides by 256. At the end, `head()` takes the bytes and `reverse()` puts the high byte first. `toByteArray("1551127401")` is `[0,0,0,0,92,116,83,105]`.
29
+
30
+ Add `.klog("step")` inside the function to watch the accumulator change on each step.
31
+
32
+ The inverse is one `reduce`. With no initial value, it starts from the first element:
33
+
34
+ ```krl
35
+ fromByteArray = function(bytes) {
36
+ bytes.reduce(function(a, b) { a * 256 + b })
37
+ }
38
+ ```
39
+
40
+ ## Flatten an array of arrays
41
+
42
+ ```krl
43
+ [[1, 2, 3], [4, 5, 6], [7, 8, 9]].reduce(function(a, b) { a.append(b) }, [])
44
+ // [1, 2, 3, 4, 5, 6, 7, 8, 9]
45
+ ```
46
+
47
+ ## Sort an array of maps
48
+
49
+ `sort` takes a comparison function. A function that returns one, for a given key, reads well:
50
+
51
+ ```krl
52
+ by = function(key) {
53
+ function(a, b) { a{key}.encode() cmp b{key}.encode() }
54
+ }
55
+ ```
56
+
57
+ `wrangler:channels().sort(by("id"))` reads "my channels, sorted by id". `cmp` compares strings, and `encode()` turns any value into a string, so `by` works whatever the values are. For numbers, compare them as numbers instead: `people.sort(function(a, b) { a{"born"} <=> b{"born"} })`.
58
+
59
+ For a primary and a secondary key:
60
+
61
+ ```krl
62
+ by = function(key1, key2) {
63
+ key2 =>
64
+ function(a, b) {
65
+ a{key1}.encode() cmp b{key1}.encode() ||
66
+ a{key2}.encode() cmp b{key2}.encode()
67
+ }
68
+ |
69
+ function(a, b) { a{key1}.encode() cmp b{key1}.encode() }
70
+ }
71
+ ```
72
+
73
+ `||` stops at the first comparison that isn't zero, so the second key only breaks ties. `by("last", "first")` sorts by last name, then first name, and `by` still works with one key.
74
+
75
+ A key can also be a path, such as `by(["meta", "flushed"])`, because `a{["meta", "flushed"]}` looks up a nested value.
76
+
77
+ *From the Pico Labs KRL Cookbook pages "Looping using the reduce operator", "Flatten an Array of Arrays", and "Sorting an Array of Maps".*
@@ -0,0 +1,28 @@
1
+ # Converting time formats
2
+
3
+ The [time library](/krl/libraries/time) works with ISO 8601 / RFC 3339 times such as `2011-09-21T15:02:01-07:00`. Other formats need converting first. RSS feeds, for example, give dates like `Wed, 21 Sep 2011 15:02:01 -0700` (RFC 2822), and `time:new` rejects them: `time:new was given an invalid date string`.
4
+
5
+ This function rearranges the parts:
6
+
7
+ ```krl
8
+ mon2num = {
9
+ "Jan": "01", "Feb": "02", "Mar": "03", "Apr": "04", "May": "05", "Jun": "06",
10
+ "Jul": "07", "Aug": "08", "Sep": "09", "Oct": "10", "Nov": "11", "Dec": "12"
11
+ }
12
+
13
+ rss2krlTime = function(pubDate) {
14
+ tarr = pubDate.split(re# #)
15
+ tzoff = tarr[5].replace(re#(\d\d)$#, ":$1")
16
+ tarr[3] + "-" + mon2num{tarr[2]} + "-" + tarr[1] + "T" + tarr[4] + tzoff
17
+ }
18
+ ```
19
+
20
+ `split` gives `["Wed,", "21", "Sep", "2011", "15:02:01", "-0700"]`. The offset `-0700` becomes `-07:00`, and `+0530` becomes `+05:30`. Then the time library can format it:
21
+
22
+ ```krl
23
+ time:strftime(rss2krlTime("Wed, 21 Sep 2011 15:02:01 -0700"), "%b %d %Y") // "Sep 21 2011"
24
+ ```
25
+
26
+ This expects a two-digit day, as RSS feeds use. For a feed that writes `1 Sep`, pad the day first, for example with `tarr[1].length() == 1 => "0" + tarr[1] | tarr[1]`.
27
+
28
+ *From the Pico Labs KRL Cookbook page "Converting Time Formats" (originally by Ed Orcutt). The time-zone handling here also covers offsets that aren't whole hours.*
@@ -0,0 +1,81 @@
1
+ # Cookies and redirects
2
+
3
+ Two directive names are special. When a rule sends one in response to an event raised over HTTP, the engine turns it into part of the HTTP response.
4
+
5
+ ## Set a cookie: `_cookie`
6
+
7
+ ```krl
8
+ rule set_cookie {
9
+ select when cookie needed
10
+ pre {
11
+ eci = wrangler:channels(["wellKnown_Rx", "Tx_Rx"]).head(){"id"} || meta:eci
12
+ }
13
+ send_directive("_cookie", {"cookie": <<wellKnown_Rx=#{eci}; Path=/sky>>})
14
+ }
15
+ ```
16
+
17
+ The engine adds `Set-Cookie: wellKnown_Rx=<eci>; Path=/sky` to the response, and the browser sends the cookie back with later requests to the same engine. This one shares the pico's well-known channel, so other picos reached from the same browser could offer it a relationship. The ruleset uses `io.picolabs.wrangler` as a module.
18
+
19
+ ## Read one cookie
20
+
21
+ `_headers` does not include the `Cookie` header. Read one cookie by name:
22
+
23
+ ```krl
24
+ eci = http:cookie("wellKnown_Rx")
25
+ ```
26
+
27
+ That is `"abc123"` when the browser sent `Cookie: wellKnown_Rx=abc123`. A cookie that was not sent is `null`. The engine's own session and ceremony cookies are not available to rulesets. `_cookie` and `_redirect` are unchanged: they still set the response.
28
+
29
+ ## Redirect: `_redirect`
30
+
31
+ ```krl
32
+ send_directive("_redirect", {"url": "https://picolabs.io/"})
33
+ ```
34
+
35
+ The engine answers the event with HTTP 302 and that URL as the `Location`.
36
+
37
+ ## A URL shortener
38
+
39
+ Together with a channel per link, `_redirect` makes a URL shortener. Each link gets its own channel, whose policy allows only the event that follows it. The channel id is the short URL:
40
+
41
+ ```krl
42
+ ruleset s {
43
+ meta {
44
+ use module io.picolabs.wrangler alias wrangler
45
+ provides u
46
+ }
47
+ global {
48
+ u = function(eci) {
49
+ <<#{meta:host}/sky/event/#{eci}/none/s/u>>
50
+ }
51
+ }
52
+ rule recordShortcut {
53
+ select when s u
54
+ url re#(.+)# setting(url)
55
+ pre {
56
+ tag = event:attr("tag").lc().replace(re#[^a-z0-9_.-]#g, "-")
57
+ eid = tag => tag | "none"
58
+ }
59
+ every {
60
+ wrangler:createChannel(
61
+ [eid, "s"],
62
+ {"allow": [{"domain": "s", "name": "u"}], "deny": []},
63
+ {"allow": [], "deny": [{"rid": "*", "name": "*"}]}
64
+ ) setting(channel)
65
+ send_directive("shortcut registered", {"tag": tag, "eci": channel{"id"}, "shortcut": u(channel{"id"}), "url": url})
66
+ }
67
+ fired {
68
+ ent:shortcuts{channel{"id"}} := url
69
+ }
70
+ }
71
+ rule redirectShortcut {
72
+ select when s u
73
+ where event:attr("url").isnull()
74
+ send_directive("_redirect", {"url": ent:shortcuts{meta:eci}})
75
+ }
76
+ }
77
+ ```
78
+
79
+ Another ruleset uses it as a module. It registers a link with `raise s event "u" attributes {"url": long_url, "tag": "docs"}`, then finds the channel with `wrangler:channels(["docs", "s"]).head()` and the short form with `s:u(eci)`. Opening the short URL redirects to the long one. The short URL can only raise `s:u`, and queries on it are all denied. Short links are handy in QR codes, which get smaller as the URL does.
80
+
81
+ *From the Pico Labs KRL Cookbook pages "Setting and reading cookies" and "Ruleset that provides a general purpose URL shortener".*