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
@@ -17,8 +17,7 @@ ruleset io.picolabs.pds {
17
17
 
18
18
  shares items, get_keys,
19
19
  profile,
20
- settings, get_config_value, get_setting_data_value, config_value, settings_names,
21
- getChannelEci
20
+ settings, get_config_value, get_setting_data_value, config_value, settings_names
22
21
 
23
22
  }
24
23
 
@@ -49,7 +48,8 @@ ruleset io.picolabs.pds {
49
48
  // "name": "<display name>",
50
49
  // "rid": "<rulesetRID>",
51
50
  // "data": { "<configKey>": <value>, ... },
52
- // "schema": []
51
+ // "schema": [],
52
+ // "secret": ["<configKey>", ...] // those data values are masked in settings
53
53
  // }
54
54
  // Path: ent:settings{[rulesetRID, "data", configKey]} for config_value()
55
55
  //
@@ -132,12 +132,39 @@ ruleset io.picolabs.pds {
132
132
  })
133
133
  };
134
134
 
135
+ is_secret_key = function(rid, key) {
136
+ listed = ent:settings{[rid, "secret"]} || [];
137
+ listed >< key
138
+ };
139
+
140
+ mask_secret = function(value) {
141
+ { "secret": true, "set": not value.isnull() }
142
+ };
143
+
144
+ // Present secret values become the mask. Secret keys with no value are
145
+ // reported as set: false.
146
+ mask_data = function(rid, data) {
147
+ values = data || {};
148
+ secrets = ent:settings{[rid, "secret"]} || [];
149
+ masked = values.map(function(v, k) {
150
+ secrets >< k => mask_secret(v) | v
151
+ });
152
+ secrets.reduce(function(acc, key) {
153
+ values{key}.isnull() => acc.put([key], mask_secret(null)) | acc
154
+ }, masked)
155
+ };
156
+
157
+ mask_record = function(rid, record) {
158
+ record.isnull() => record | record.put(["data"], mask_data(rid, record{"data"}))
159
+ };
160
+
135
161
  /**
136
162
  * Read per-ruleset settings. No arguments: all settings. Rid: that ruleset's
137
- * settings record ({ name, rid, data, schema }). Rid and Key: one field of the
163
+ * settings record ({ name, rid, data, schema, secret }). Rid and Key: one field of the
138
164
  * record. Rid, Key, and detail: the value of data key `detail` (Key is ignored).
165
+ * A key listed in `secret` is returned as { secret: true, set }, never the value.
139
166
  * @param Rid String "ruleset id whose settings to read"
140
- * @param Key String "field of the settings record (name, rid, data, schema)"
167
+ * @param Key String "field of the settings record (name, rid, data, schema, secret)"
141
168
  * @param detail String "key within the record's data map"
142
169
  * @returns Map "{ status, settings }"
143
170
  * @example "one ruleset" { "Rid": "<rid>" }
@@ -145,16 +172,19 @@ ruleset io.picolabs.pds {
145
172
  */
146
173
  settings = function(Rid = null, Key = null, detail = null){
147
174
  get_setting_all = function() {
148
- ent:settings
175
+ ent:settings.isnull() => ent:settings |
176
+ ent:settings.map(function(record, rid) { mask_record(rid, record) })
149
177
  };
150
178
  get_setting = function(rid) {
151
- ent:settings{rid}
179
+ mask_record(rid, ent:settings{rid})
152
180
  };
153
181
  get_setting_value = function(rid, varible) {
182
+ varible == "data" => mask_data(rid, ent:settings{[rid, "data"]}) |
154
183
  ent:settings{[rid, varible]}
155
184
  };
156
185
  get_data_value = function(rid, dataKey) {
157
- ent:settings{[rid, "data", dataKey]}
186
+ raw = ent:settings{[rid, "data", dataKey]};
187
+ is_secret_key(rid, dataKey) => mask_secret(raw) | raw
158
188
  };
159
189
  pick = function() {
160
190
  Rid.isnull() => get_setting_all()
@@ -181,13 +211,15 @@ ruleset io.picolabs.pds {
181
211
  };
182
212
 
183
213
  /**
184
- * One configuration value from a ruleset's settings data.
214
+ * One configuration value from a ruleset's settings data. A secret key is
215
+ * returned as { secret: true, set }, never the value.
185
216
  * @param setRID String "ruleset id"
186
217
  * @param setKey String "data key"
187
218
  * @returns Any
188
219
  */
189
220
  get_setting_data_value = function(setRID, setKey) {
190
- setting_data_value(setRID, setKey)
221
+ raw = setting_data_value(setRID, setKey);
222
+ is_secret_key(setRID, setKey) => mask_secret(raw) | raw
191
223
  }
192
224
 
193
225
  /**
@@ -213,14 +245,36 @@ ruleset io.picolabs.pds {
213
245
  }
214
246
 
215
247
  /**
216
- * The ECI of this pico's pds channel, which allows all pds events and queries.
217
- * Created when this ruleset is installed.
248
+ * The ECI of this pico's pds channel. Provided to rulesets on this pico.
249
+ * Not a shared query: a channel that can read settings must not receive an
250
+ * ECI that can rewrite them.
218
251
  * @returns String
219
252
  */
220
253
  getChannelEci = function() {
221
254
  ent:pds_channel_eci
222
255
  }
223
256
 
257
+ keys_from_secret_attr = function(secret, data_key) {
258
+ secret == true && data_key.typeof() == "String" => [data_key] |
259
+ secret.typeof() == "Array" => secret.filter(function(k) { k.typeof() == "String" }) |
260
+ []
261
+ };
262
+
263
+ keys_from_schema = function(schema) {
264
+ schema.typeof() == "Array" => schema.filter(function(entry) {
265
+ entry.typeof() == "Map" && entry{"secret"}
266
+ }).map(function(entry) {
267
+ entry{"key"} || entry{"name"}
268
+ }).filter(function(k) { k.typeof() == "String" }) |
269
+ []
270
+ };
271
+
272
+ merge_secret_keys = function(already, more) {
273
+ more.reduce(function(acc, key) {
274
+ acc >< key => acc | acc.append(key)
275
+ }, already || [])
276
+ };
277
+
224
278
  defaultProfile = {
225
279
  "name": "",
226
280
  "description": "",
@@ -389,14 +443,18 @@ ruleset io.picolabs.pds {
389
443
 
390
444
  /**
391
445
  * Create or update a ruleset's settings record, and optionally set one data
392
- * value in it. Raises pds:settings_added.
446
+ * value in it. Raises pds:settings_added. A key named in `secret`, or a schema
447
+ * entry with secret true, is stored as a secret: settings queries return
448
+ * { secret: true, set } and the raised event does not carry the value.
393
449
  * @attr keyed_rid String "ruleset id the settings belong to"
394
450
  * @attr name String "display name for the settings"
395
451
  * @attr schema Array optional "settings schema, stored as given"
396
452
  * @attr data_key String optional "data key to set"
397
453
  * @attr value Any optional "value for data_key"
454
+ * @attr secret Array|Boolean optional "key names to mark secret, or true to mark data_key"
398
455
  * @example "register settings" { "keyed_rid": "<rid>", "name": "<display name>" }
399
456
  * @example "set one value" { "keyed_rid": "<rid>", "name": "<display name>", "data_key": "<key>", "value": "<value>" }
457
+ * @example "secret" { "keyed_rid": "<rid>", "name": "<display name>", "data_key": "apiKey", "value": "<secret>", "secret": true }
400
458
  */
401
459
  rule settings_added {
402
460
  select when pds add_settings
@@ -406,35 +464,65 @@ ruleset io.picolabs.pds {
406
464
  set_schema = event:attr("schema").defaultsTo(0, "no Schema");
407
465
  set_attr = event:attr("data_key").defaultsTo(0, "no setAttr");
408
466
  set_value = event:attr("value").defaultsTo(0, "no Value");
409
-
467
+ already = ent:settings{[set_rid, "secret"]} || [];
468
+ next_secret = merge_secret_keys(
469
+ merge_secret_keys(already, keys_from_secret_attr(event:attr("secret"), event:attr("data_key"))),
470
+ keys_from_schema(set_schema)
471
+ );
472
+ hiding = set_attr.typeof() == "String" && (next_secret >< set_attr);
473
+ announced = hiding => event:attrs.put(["value"], mask_secret(set_value)) | event:attrs;
410
474
  }
411
475
  noop()
412
476
  always {
413
477
  ent:settings{[set_rid, "name"]} := set_name;
414
478
  ent:settings{[set_rid, "rid"]} := set_rid;
415
479
  ent:settings{[set_rid, "schema"]} := set_schema if set_schema;
480
+ ent:settings{[set_rid, "secret"]} := next_secret if next_secret.length() > 0;
416
481
  ent:settings{[set_rid, "data", set_attr]} := set_value if set_attr;
417
- raise pds event "settings_added" attributes event:attrs;
482
+ raise pds event "settings_added" attributes announced;
418
483
  }
419
484
  }
420
485
 
486
+ // On install, and on the root pico at engine start: a pico whose PDS came
487
+ // with an older engine may have no pds channel yet.
421
488
  rule create_pds_channel {
422
489
  select when wrangler ruleset_installed where event:attr("rids") >< ctx:rid
490
+ or engine started
423
491
  pre {
424
492
  channelName = "pds"
425
- eventPolicy = {"allow": [{"domain": "pds", "name": "*"}], "deny": []}
493
+ eventPolicy = {"allow": [{"domain": "pds", "name": "*"}], "deny": [{"domain": "pds", "name": "clear_all_data"}]}
426
494
  queryPolicy = {"allow": [{"rid": "io.picolabs.pds", "name": "*"}], "deny": []}
427
- existing_channels = wrangler:channels()
428
- pds_channel = existing_channels.filter(function(chan) {
429
- chan{"name"} == channelName
430
- })
495
+ pds_channel = wrangler:channels([channelName])
431
496
  channel_exists = pds_channel.length() > 0
432
497
  }
433
498
  if not channel_exists then
434
499
  wrangler:createChannel([channelName], eventPolicy, queryPolicy) setting(channel)
435
500
  fired {
436
- ent:pds_channel_eci := channel_exists => pds_channel.head(){"id"} | channel{"id"}
501
+ ent:pds_channel_eci := channel{"id"}
502
+ }
503
+ else {
504
+ ent:pds_channel_eci := pds_channel.head(){"id"}
505
+ }
506
+ }
507
+
508
+ // A channel created by an older engine allowed clear_all_data. Deny that
509
+ // event on the pds channel. A ruleset on this pico can still raise it.
510
+ rule narrow_pds_channel {
511
+ select when wrangler ruleset_installed where event:attr("rids") >< ctx:rid
512
+ or engine started
513
+ pre {
514
+ found = wrangler:channels(["pds"]).head()
515
+ denied = found.isnull() => [] | found{"eventPolicy"}{"deny"}.defaultsTo([])
516
+ already = denied.filter(function(rule) { rule{"name"} == "clear_all_data" })
517
+ open = found && already.length() == 0
437
518
  }
519
+ if open then
520
+ wrangler:updateChannel(
521
+ found{"id"},
522
+ ["pds"],
523
+ {"allow": [{"domain": "pds", "name": "*"}], "deny": [{"domain": "pds", "name": "clear_all_data"}]},
524
+ {"allow": [{"rid": "io.picolabs.pds", "name": "*"}], "deny": []}
525
+ )
438
526
  }
439
527
 
440
528
  rule seed_profile_name {
@@ -143,7 +143,8 @@ ruleset io.picolabs.pico-engine-ui {
143
143
  { "domain": "wrangler", "name": "new_child_request" },
144
144
  { "domain": "wrangler", "name": "new_child_created" },
145
145
  { "domain": "wrangler", "name": "install_ruleset_request" },
146
- { "domain": "wrangler", "name": "new_channel_request" }
146
+ { "domain": "wrangler", "name": "new_channel_request" },
147
+ { "domain": "pds", "name": "add_settings" }
147
148
  ],
148
149
  "deny": []
149
150
  }
@@ -168,7 +169,8 @@ ruleset io.picolabs.pico-engine-ui {
168
169
  { "rid": "io.picolabs.wrangler", "name": "myDid" },
169
170
  { "rid": "io.picolabs.wrangler", "name": "publicIntro" },
170
171
  { "rid": "io.picolabs.wrangler", "name": "rulesetSchema" },
171
- { "rid": "io.picolabs.wrangler", "name": "picoSchema" }
172
+ { "rid": "io.picolabs.wrangler", "name": "picoSchema" },
173
+ { "rid": "io.picolabs.pds", "name": "settings" }
172
174
  ],
173
175
  "deny": []
174
176
  }
@@ -259,7 +261,7 @@ ruleset io.picolabs.pico-engine-ui {
259
261
  gridRow = (childIndex - childIndex % 4) / 4
260
262
  layoutX = ent:x.defaultsTo(100) + 48 + gridCol * 143
261
263
  layoutY = ent:y.defaultsTo(100) + 48 + gridRow * 108
262
- childBox = ctx:query(uiEci, ctx:rid, "box")
264
+ childBox = uiEci => ctx:query(uiEci, ctx:rid, "box") | {}
263
265
  layoutColor = childBox{"backgroundColor"}
264
266
  .defaultsTo(childPalette[childIndex % childPalette.length])
265
267
  }
@@ -282,7 +284,7 @@ ruleset io.picolabs.pico-engine-ui {
282
284
  select when engine started
283
285
  foreach ctx:children setting(familyEci)
284
286
  if ent:child_ui_ecis{familyEci}.isnull() then noop()
285
- always {
287
+ fired {
286
288
  ent:child_ui_ecis{[familyEci]} := ctx:query(familyEci, ctx:rid, "uiECI")
287
289
  }
288
290
  }
@@ -304,7 +306,7 @@ ruleset io.picolabs.pico-engine-ui {
304
306
  rule backfill_parent_ui_eci {
305
307
  select when engine started
306
308
  if ctx:parent && ent:parent_ui_eci.isnull() then noop()
307
- always {
309
+ fired {
308
310
  ent:parent_ui_eci := ctx:query(ctx:parent, ctx:rid, "uiECI")
309
311
  }
310
312
  }
@@ -409,7 +411,9 @@ ruleset io.picolabs.pico-engine-ui {
409
411
  tags=event:attrs{"tags"},
410
412
  eventPolicy=event:attrs{"eventPolicy"},
411
413
  queryPolicy=event:attrs{"queryPolicy"},
412
- id=event:attrs{"id"}
414
+ id=event:attrs{"id"},
415
+ mcpPolicy=event:attrs{"mcpPolicy"},
416
+ rawBody=event:attrs{"rawBody"}
413
417
  )
414
418
  }
415
419
  rule del_channel {
@@ -422,7 +426,9 @@ ruleset io.picolabs.pico-engine-ui {
422
426
  eci=event:attrs{"eci"},
423
427
  tags=event:attrs{"tags"},
424
428
  eventPolicy=event:attrs{"eventPolicy"},
425
- queryPolicy=event:attrs{"queryPolicy"}
429
+ queryPolicy=event:attrs{"queryPolicy"},
430
+ mcpPolicy=event:attrs{"mcpPolicy"},
431
+ rawBody=event:attrs{"rawBody"}
426
432
  )
427
433
  }
428
434
  rule testing_eci {
@@ -40,9 +40,9 @@ ruleset io.picolabs.wrangler {
40
40
  { "domain": "wrangler", "name": "child_deletion_request",
41
41
  "attrs": [ "eci"] },
42
42
  { "domain": "wrangler", "name": "new_channel_request",
43
- "attrs": [ "tags", "eventPolicy", "queryPolicy" ] },
43
+ "attrs": [ "tags", "eventPolicy", "queryPolicy", "mcpPolicy", "rawBody" ] },
44
44
  { "domain": "wrangler", "name": "channel_update_request",
45
- "attrs": [ "eci", "tags", "eventPolicy", "queryPolicy" ] },
45
+ "attrs": [ "eci", "tags", "eventPolicy", "queryPolicy", "mcpPolicy", "rawBody" ] },
46
46
  { "domain": "wrangler", "name": "channel_deletion_request",
47
47
  "attrs": [ "eci" ] },
48
48
  { "domain": "wrangler", "name": "install_ruleset_request",
@@ -299,21 +299,25 @@ ruleset io.picolabs.wrangler {
299
299
  ctx:delChannel(eci)
300
300
  }
301
301
 
302
- createChannel = defaction(tags,eventPolicy,queryPolicy){
302
+ createChannel = defaction(tags,eventPolicy,queryPolicy,mcpPolicy,rawBody){
303
303
  ctx:newChannel(
304
304
  tags=tags,
305
305
  eventPolicy=eventPolicy,
306
- queryPolicy=queryPolicy
306
+ queryPolicy=queryPolicy,
307
+ mcpPolicy=mcpPolicy,
308
+ rawBody=rawBody
307
309
  ) setting(channel)
308
310
  return channel
309
311
  }
310
312
 
311
- updateChannel = defaction(eci, tags, eventPolicy, queryPolicy) {
313
+ updateChannel = defaction(eci, tags, eventPolicy, queryPolicy, mcpPolicy, rawBody) {
312
314
  ctx:putChannel(
313
315
  eci=eci,
314
316
  tags=tags,
315
317
  eventPolicy=eventPolicy,
316
- queryPolicy=queryPolicy
318
+ queryPolicy=queryPolicy,
319
+ mcpPolicy=mcpPolicy,
320
+ rawBody=rawBody
317
321
  ) setting(channel)
318
322
  return channel
319
323
  }
@@ -701,7 +705,9 @@ ruleset io.picolabs.wrangler {
701
705
  * @attr tags Array "tags for the channel, e.g. [\"myapp\", \"webhook\"]"
702
706
  * @attr eventPolicy Map "{ allow: [ { domain, name } ], deny: [ … ] }"
703
707
  * @attr queryPolicy Map "{ allow: [ { rid, name } ], deny: [ … ] }"
704
- * @example "webhook" { "tags": ["<app>", "webhook"], "eventPolicy": { "allow": [ { "domain": "<app>", "name": "*" } ], "deny": [] }, "queryPolicy": { "allow": [], "deny": [] } }
708
+ * @attr mcpPolicy Map "optional { allow: [ { surface } ], deny: [ … ] }. surface is channel, mesh, or *. Absent denies MCP."
709
+ * @attr rawBody Boolean "optional. true keeps the raw HTTP body for event:raw_body(). Absent does not."
710
+ * @example "webhook" { "tags": ["<app>", "webhook"], "eventPolicy": { "allow": [ { "domain": "<app>", "name": "*" } ], "deny": [] }, "queryPolicy": { "allow": [], "deny": [] }, "rawBody": true }
705
711
  */
706
712
  rule createChannel {
707
713
  select when wrangler new_channel_request
@@ -709,9 +715,11 @@ ruleset io.picolabs.wrangler {
709
715
  tags = event:attrs{"tags"}
710
716
  eventPolicy = event:attrs{"eventPolicy"}
711
717
  queryPolicy = event:attrs{"queryPolicy"}
718
+ mcpPolicy = event:attrs{"mcpPolicy"}
719
+ rawBody = event:attrs{"rawBody"}
712
720
  }
713
721
  if tags && eventPolicy && queryPolicy then
714
- createChannel(tags,eventPolicy,queryPolicy) setting(channel)
722
+ createChannel(tags,eventPolicy,queryPolicy,mcpPolicy,rawBody) setting(channel)
715
723
  fired {
716
724
  raise wrangler event "channel_created"
717
725
  attributes event:attrs.put({"channel":channel})
@@ -739,6 +747,8 @@ ruleset io.picolabs.wrangler {
739
747
  * @attr tags Array "new tags"
740
748
  * @attr eventPolicy Map "new event policy"
741
749
  * @attr queryPolicy Map "new query policy"
750
+ * @attr mcpPolicy Map "optional { allow: [ { surface } ], deny: [ … ] }. Omit to leave MCP exposure unchanged."
751
+ * @attr rawBody Boolean "optional. true or false. Omit to leave the raw-body setting unchanged."
742
752
  */
743
753
  rule updateChannel {
744
754
  select when wrangler channel_update_request
@@ -747,9 +757,11 @@ ruleset io.picolabs.wrangler {
747
757
  tags = event:attrs{"tags"}
748
758
  eventPolicy = event:attrs{"eventPolicy"}
749
759
  queryPolicy = event:attrs{"queryPolicy"}
760
+ mcpPolicy = event:attrs{"mcpPolicy"}
761
+ rawBody = event:attrs{"rawBody"}
750
762
  }
751
763
  if eci && tags && eventPolicy && queryPolicy then
752
- updateChannel(eci, tags, eventPolicy, queryPolicy) setting(channel)
764
+ updateChannel(eci, tags, eventPolicy, queryPolicy, mcpPolicy, rawBody) setting(channel)
753
765
  fired {
754
766
  raise wrangler event "channel_updated"
755
767
  attributes event:attrs.put({"channel": channel})
@@ -358,7 +358,8 @@ ruleset io.picolabs.xmlui {
358
358
  * Applies the theme stored in this browser tab (sessionStorage
359
359
  * picoViewTheme: default, dark, green, green-dark, gray, gray-dark) to
360
360
  * its children, on the theme's page background so rows stay readable
361
- * in dark tones.
361
+ * in dark tones. The padding keeps content off the panel's edge, which
362
+ * shows in dark tones.
362
363
  * @component
363
364
  */
364
365
  picoTheme = function() {
@@ -367,7 +368,7 @@ ruleset io.picolabs.xmlui {
367
368
  <Theme
368
369
  themeId="{['green', 'green-dark'].includes(sessionStorage.getItem('picoViewTheme') || 'default') ? 'xmlui-green' : ['gray', 'gray-dark'].includes(sessionStorage.getItem('picoViewTheme') || 'default') ? 'xmlui-gray' : 'xmlui'}"
369
370
  tone="{(sessionStorage.getItem('picoViewTheme') || 'default').endsWith('dark') ? 'dark' : 'light'}">
370
- <VStack gap="$space-2" backgroundColor="$backgroundColor">
371
+ <VStack gap="$space-2" padding="$space-3" backgroundColor="$backgroundColor">
371
372
  <Slot />
372
373
  </VStack>
373
374
  </Theme>
@@ -19,11 +19,63 @@ function readFile(filePath) {
19
19
  function readDoc(relativeFromRepoRoot) {
20
20
  return (
21
21
  readFile(path.join(repoRoot, relativeFromRepoRoot)) ||
22
+ readFile(path.join(bundledDir, relativeFromRepoRoot.replace(/^docs\//, ""))) ||
22
23
  readFile(path.join(bundledDir, path.basename(relativeFromRepoRoot)))
23
24
  );
24
25
  }
25
26
 
27
+ /** Markdown pages under docs/<dir>, as paths relative to it ("echo/README.md"). */
28
+ function listPages(dir) {
29
+ const root = fs.existsSync(path.join(repoRoot, "docs", dir))
30
+ ? path.join(repoRoot, "docs", dir)
31
+ : path.join(bundledDir, dir);
32
+ const out = [];
33
+ const walk = (sub) => {
34
+ let entries = [];
35
+ try {
36
+ entries = fs.readdirSync(path.join(root, sub), { withFileTypes: true });
37
+ } catch (_e) {
38
+ return;
39
+ }
40
+ for (const entry of entries) {
41
+ const rel = sub ? `${sub}/${entry.name}` : entry.name;
42
+ if (entry.isDirectory()) walk(rel);
43
+ else if (entry.name.endsWith(".md")) out.push(rel);
44
+ }
45
+ };
46
+ walk("");
47
+ return out.sort();
48
+ }
49
+
50
+ function firstHeading(text, fallback) {
51
+ const m = /^# (.+)$/m.exec(text);
52
+ return m ? m[1].trim() : fallback;
53
+ }
54
+
55
+ // Every page of the cookbook (demo overviews and instructions) and of Patterns
56
+ // and tips, at pico://docs/<dir>/<page without .md>.
57
+ function registerDocPages(server, dir, label) {
58
+ for (const rel of listPages(dir)) {
59
+ const page = rel.replace(/\.md$/, "");
60
+ const uri = `pico://docs/${dir}/${page}`;
61
+ const docPath = `docs/${dir}/${rel}`;
62
+ const title = firstHeading(readDoc(docPath), page);
63
+ server.resource(
64
+ `${dir}/${page}`,
65
+ uri,
66
+ { description: `${label}: ${title}`, mimeType: "text/markdown" },
67
+ async () => ({
68
+ contents: [{ uri, mimeType: "text/markdown", text: readDoc(docPath) }],
69
+ })
70
+ );
71
+ }
72
+ }
73
+
26
74
  function registerDevResources(server, client) {
75
+ registerDocPages(server, "cookbook", "Cookbook");
76
+ registerDocPages(server, "developing", "Developing with Picos");
77
+ registerDocPages(server, "wrangler", "Wrangler");
78
+
27
79
  server.resource(
28
80
  "krl-conventions",
29
81
  "pico://docs/krl-conventions",
package/mcp/devTools.js CHANGED
@@ -13,6 +13,35 @@ function textResult(text, isError = false) {
13
13
 
14
14
  const emptySchema = {};
15
15
 
16
+ /** The attrs of a wrangler:<name> event anywhere in an event-wait body, or null. */
17
+ function findWranglerEvent(node, name) {
18
+ if (!node || typeof node !== "object") return null;
19
+ if (node.domain === "wrangler" && node.name === name) {
20
+ return (node.data && node.data.attrs) || {};
21
+ }
22
+ for (const value of Object.values(node)) {
23
+ const hit = findWranglerEvent(value, name);
24
+ if (hit) return hit;
25
+ }
26
+ return null;
27
+ }
28
+
29
+ /**
30
+ * An event-wait body as a tool result. The engine answers some failures with
31
+ * HTTP 200 and an error in the body (a channel policy refusal), and install or
32
+ * flush failures as a raised wrangler event; both are reported as errors.
33
+ */
34
+ function eventResult(data, failureEvent) {
35
+ if (data && typeof data === "object" && data.error != null) {
36
+ return textResult(jsonText(data), true);
37
+ }
38
+ const failed = failureEvent ? findWranglerEvent(data, failureEvent) : null;
39
+ if (failed) {
40
+ return textResult(jsonText({ error: `wrangler:${failureEvent}`, details: failed, response: data }), true);
41
+ }
42
+ return textResult(jsonText(data));
43
+ }
44
+
16
45
  function registerDevTools(server, client) {
17
46
  server.tool(
18
47
  "engine_status",
@@ -111,7 +140,7 @@ function registerDevTools(server, client) {
111
140
  name,
112
141
  attrs || {}
113
142
  );
114
- return textResult(jsonText(data));
143
+ return eventResult(data);
115
144
  } catch (err) {
116
145
  return textResult(String(err), true);
117
146
  }
@@ -258,7 +287,7 @@ function registerDevTools(server, client) {
258
287
  const data = await client.channelEventWait(ui, "engine_ui", "install", {
259
288
  url,
260
289
  });
261
- return textResult(jsonText(data));
290
+ return eventResult(data, "ruleset_install_failed");
262
291
  } catch (err) {
263
292
  return textResult(String(err), true);
264
293
  }
@@ -278,7 +307,7 @@ function registerDevTools(server, client) {
278
307
  const data = await client.channelEventWait(ui, "engine_ui", "flush", {
279
308
  url,
280
309
  });
281
- return textResult(jsonText(data));
310
+ return eventResult(data, "ruleset_flush_failed");
282
311
  } catch (err) {
283
312
  return textResult(String(err), true);
284
313
  }
@@ -295,7 +324,7 @@ function registerDevTools(server, client) {
295
324
  async (attrs) => {
296
325
  try {
297
326
  const data = await client.engineUiEvent("new", attrs);
298
- return textResult(jsonText(data));
327
+ return eventResult(data);
299
328
  } catch (err) {
300
329
  return textResult(String(err), true);
301
330
  }
@@ -309,7 +338,7 @@ function registerDevTools(server, client) {
309
338
  async ({ eci }) => {
310
339
  try {
311
340
  const data = await client.engineUiEvent("del", { eci });
312
- return textResult(jsonText(data));
341
+ return eventResult(data);
313
342
  } catch (err) {
314
343
  return textResult(String(err), true);
315
344
  }
@@ -318,14 +347,15 @@ function registerDevTools(server, client) {
318
347
 
319
348
  server.tool(
320
349
  "create_channel",
321
- "Create a channel on the root pico (engine_ui new_channel)",
350
+ "Create a channel on the root pico (engine_ui new_channel). Omit mcpPolicy and the channel is not exposed to MCP.",
322
351
  {
323
352
  tags: z.union([z.string(), z.array(z.string())]),
324
353
  id: z.string().optional(),
325
354
  eventPolicy: z.record(z.any()).optional(),
326
355
  queryPolicy: z.record(z.any()).optional(),
356
+ mcpPolicy: z.record(z.any()).optional(),
327
357
  },
328
- async ({ tags, id, eventPolicy, queryPolicy }) => {
358
+ async ({ tags, id, eventPolicy, queryPolicy, mcpPolicy }) => {
329
359
  try {
330
360
  const tagList =
331
361
  typeof tags === "string"
@@ -339,8 +369,9 @@ function registerDevTools(server, client) {
339
369
  id,
340
370
  eventPolicy,
341
371
  queryPolicy,
372
+ mcpPolicy,
342
373
  });
343
- return textResult(jsonText(data));
374
+ return eventResult(data);
344
375
  } catch (err) {
345
376
  return textResult(String(err), true);
346
377
  }
@@ -348,4 +379,4 @@ function registerDevTools(server, client) {
348
379
  );
349
380
  }
350
381
 
351
- module.exports = { registerDevTools };
382
+ module.exports = { registerDevTools, findWranglerEvent };
@@ -2,7 +2,7 @@
2
2
 
3
3
  This is the **pico engine**: an open-source Node.js runtime for **picos** (persistent compute objects) — small, always-on actors with persistent identity, state, and availability that talk by events and queries. Behavior is written in **KRL** (the pico rules language), compiled to JavaScript. Read `docs/design/pico-overview.md` first if the model isn't in your head yet.
4
4
 
5
- Lerna mono-repo. Current release line: 1.9.0 (`docs/release/1.9.0.md`).
5
+ Lerna mono-repo. Current release line: 1.10.0 (`docs/release/1.10.0.md`).
6
6
 
7
7
  ## The one rule that governs all design: strict layering
8
8
 
@@ -20,6 +20,7 @@ Engine and wrangler stay **domain-agnostic**. If a change needs the words "owner
20
20
  | Path | What |
21
21
  |------|------|
22
22
  | `packages/pico-engine` | The npm package people install; HTTP server, CLI, auth/OAuth, identity, UI host |
23
+ | `packages/pico-framework` | Pico runtime without KRL: picos, channels, policy, persistence. Versioned with the engine |
23
24
  | `packages/pico-engine-core` | Executes compiled KRL; event lifecycle |
24
25
  | `packages/krl-parser` → `krl-compiler` → `krl-generator` | KRL → AST → JS; AST → KRL |
25
26
  | `packages/krl-stdlib` | KRL standard library |
@@ -28,9 +29,9 @@ Engine and wrangler stay **domain-agnostic**. If a change needs the words "owner
28
29
  | `docs/design/` | Design docs (schemas, identity, move, relationships, harness) |
29
30
  | `docs/release/` | Per-release plans (`1.8.md`) and notes (`1.7.0.md`) |
30
31
  | `MEMORY.md` | Long-running working log: roadmap, decisions, gotchas. Source of truth for *why*; skim the TOC |
31
- | `test-rulesets/`, `demos/` | KRL used by tests and demos |
32
+ | `test-rulesets/`, `demos/` | KRL used by tests and demos. Each `demos/<name>/` has a README; its overview and instructions are in `docs/cookbook/<name>/` |
32
33
 
33
- Sibling repos (same org, not in this tree): `manifold-api` (Manifold KRL), `sensor-network`, `MCPforEXP`, `pico-framework` (lifecycle/channels/LevelDB; engine depends on `^0.8.2` for 1.8 policy ceiling).
34
+ Sibling repos (same org, not in this tree): `manifold-api` (Manifold KRL), `sensor-network`, `MCPforEXP`. `pico-framework` is `packages/pico-framework` in this repo.
34
35
 
35
36
  ## Commands
36
37
 
@@ -72,7 +73,7 @@ rule name {
72
73
  | `raise wrangler event "child_deletion_request" attributes {"eci": picoId}` | legacy `wrangler child_deletion` with `{"id": …}` (never runs) |
73
74
  | `wrangler:picoQuery` (works over family channels) | `wrangler:skyQuery` (deprecated; HTTP blocked on family channels) |
74
75
 
75
- Also: `if X then noop(); fired { … }` runs `fired` when X is **true**. Rules in one ruleset selecting the same event run in **rule-name lexicographic order**; across rulesets the order is undefined. A stray character after `meta { }` silently prevents registration — if a ruleset never seems to run, check it actually loaded.
76
+ Also: `if X then noop(); fired { … }` runs `fired` when X is **true**. Rules in one ruleset selecting the same event run in **source order** (the order they're written), and `last` stops only the rest of that ruleset; across rulesets the order is undefined. A stray character after `meta { }` silently prevents registration — if a ruleset never seems to run, check it actually loaded.
76
77
 
77
78
  Terminology: **relationships** (1.6.2+; "subscriptions" in older code and docs). Channels have **ECIs** and **policies**; policy is the authorization gate. Every pico has a `discovery` channel.
78
79
 
@@ -80,6 +81,7 @@ Terminology: **relationships** (1.6.2+; "subscriptions" in older code and docs).
80
81
 
81
82
  - Design before code for anything touching identity, policy, schema, or the Sky API: add or update a doc in `docs/design/` and link it from `MEMORY.md`.
82
83
  - Keep `MEMORY.md` current when you learn an engine behavior the hard way; it is what future sessions read.
84
+ - View markup in KRL heredocs: put `<Component …>` on its own line after `<<`, not `<<<Component`. XMLUI accepts the leading newline.
83
85
  - Don't commit or publish; leave that to the maintainer. `npm run publish` builds and publishes every package — never run it.
84
86
  - Tests are ava, serial for engine suites (`--serial`, 2–3 min timeouts). Add a focused `test:*` script when you add a suite.
85
87
  - UI changes need `npm run build` (repo root) or `npm run dev` in `pico-engine-ui` or they won't appear in `public/`.