pico-engine 1.6.2 → 1.8.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 (107) hide show
  1. package/README.md +117 -14
  2. package/dist/RulesetRegistryLoaderFs.js +24 -8
  3. package/dist/auth/cookies.js +32 -0
  4. package/dist/auth/index.js +6 -1
  5. package/dist/bundledKrl.js +129 -11
  6. package/dist/channelIdentityPolicy.js +22 -0
  7. package/dist/cli.js +105 -46
  8. package/dist/engineConfig.js +280 -0
  9. package/dist/identity/IdentityService.js +90 -0
  10. package/dist/identity/crossPico.js +106 -30
  11. package/dist/identity/didoModule.js +80 -18
  12. package/dist/identity/establishSubscription.js +2 -2
  13. package/dist/identity/identityPortable.js +92 -0
  14. package/dist/identity/index.js +10 -1
  15. package/dist/identity/localPeerReconcile.js +65 -0
  16. package/dist/identity/peerDid4.js +175 -0
  17. package/dist/identity/peerDid4Create.js +90 -0
  18. package/dist/identity/portableExportPrepare.js +196 -0
  19. package/dist/identity/portableMove.js +87 -0
  20. package/dist/identity/skyIntro.js +10 -4
  21. package/dist/identity/skyProtocol.js +26 -1
  22. package/dist/identity/skyRotation.js +121 -0
  23. package/dist/identity/store.js +5 -1
  24. package/dist/identity/subscriptionEntSync.js +72 -0
  25. package/dist/identity/veramoDidComm.js +41 -2
  26. package/dist/identity/webvh.js +4 -2
  27. package/dist/identity/webvhRelocation.js +115 -0
  28. package/dist/index.js +127 -34
  29. package/dist/levelDb.js +102 -0
  30. package/dist/logging.js +47 -8
  31. package/dist/oauth/OAuthService.js +12 -5
  32. package/dist/oauth/channelEligibility.js +7 -1
  33. package/dist/oauth/index.js +3 -1
  34. package/dist/policyConfigFromJson.js +112 -0
  35. package/dist/runMcp.js +27 -0
  36. package/dist/server.js +95 -24
  37. package/dist/subtreeWrangler.js +180 -0
  38. package/dist/uiChannelPolicies.js +16 -0
  39. package/krl/io.picolabs.oauth.krl +51 -5
  40. package/krl/io.picolabs.pds.krl +131 -10
  41. package/krl/io.picolabs.pico-engine-ui.krl +219 -22
  42. package/krl/io.picolabs.portable_subtree.krl +97 -0
  43. package/krl/io.picolabs.subscription.krl +226 -72
  44. package/krl/io.picolabs.wrangler.krl +300 -58
  45. package/mcp/devResources.js +118 -0
  46. package/mcp/devTools.js +351 -0
  47. package/mcp/engineClient.js +133 -0
  48. package/mcp/meshHttp.js +137 -0
  49. package/mcp/meshTools.js +189 -0
  50. package/mcp/runStdio.js +34 -0
  51. package/mcp/schemaToZod.js +56 -0
  52. package/package.json +22 -8
  53. package/public/docs/_sidebar.md +2 -1
  54. package/public/docs/llms-full.txt +479 -0
  55. package/public/docs/llms.txt +37 -0
  56. package/public/docs/openapi.yaml +78 -0
  57. package/public/docs/pico-engine.md +235 -4
  58. package/public/docs/pico-overview.md +117 -0
  59. package/public/docs/pico.md +3 -1
  60. package/public/docs/rulesets/README.md +25 -0
  61. package/public/docs/rulesets/io.picolabs.oauth.md +71 -0
  62. package/public/docs/rulesets/io.picolabs.pds.md +327 -0
  63. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +65 -0
  64. package/public/docs/rulesets/io.picolabs.portable_subtree.md +94 -0
  65. package/public/docs/rulesets/io.picolabs.subscription.md +398 -0
  66. package/public/docs/rulesets/io.picolabs.wrangler.md +471 -0
  67. package/public/pico-engine-ui.css +1 -1
  68. package/public/pico-engine-ui.js +28 -26
  69. package/src/RulesetRegistryLoaderFs.ts +43 -11
  70. package/src/auth/cookies.ts +34 -0
  71. package/src/auth/index.ts +7 -0
  72. package/src/bundledKrl.ts +150 -12
  73. package/src/channelIdentityPolicy.ts +29 -0
  74. package/src/cli.ts +98 -40
  75. package/src/engineConfig.ts +345 -0
  76. package/src/identity/IdentityService.ts +189 -1
  77. package/src/identity/crossPico.ts +161 -41
  78. package/src/identity/didoModule.ts +140 -23
  79. package/src/identity/establishSubscription.ts +2 -2
  80. package/src/identity/identityPortable.ts +153 -0
  81. package/src/identity/index.ts +14 -0
  82. package/src/identity/localPeerReconcile.ts +97 -0
  83. package/src/identity/peerDid4.ts +197 -0
  84. package/src/identity/peerDid4Create.ts +121 -0
  85. package/src/identity/portableExportPrepare.ts +302 -0
  86. package/src/identity/portableMove.ts +193 -0
  87. package/src/identity/skyIntro.ts +16 -12
  88. package/src/identity/skyProtocol.ts +46 -0
  89. package/src/identity/skyRotation.ts +211 -0
  90. package/src/identity/store.ts +5 -1
  91. package/src/identity/subscriptionEntSync.ts +97 -0
  92. package/src/identity/veramoDidComm.ts +52 -2
  93. package/src/identity/webvh.ts +4 -4
  94. package/src/identity/webvhRelocation.ts +167 -0
  95. package/src/index.ts +179 -39
  96. package/src/levelDb.ts +122 -0
  97. package/src/logging.ts +63 -11
  98. package/src/oauth/OAuthService.ts +20 -6
  99. package/src/oauth/channelEligibility.ts +9 -0
  100. package/src/oauth/index.ts +7 -1
  101. package/src/policyConfigFromJson.ts +131 -0
  102. package/src/runMcp.ts +30 -0
  103. package/src/server.ts +133 -27
  104. package/src/subtreeWrangler.ts +278 -0
  105. package/src/uiChannelPolicies.ts +16 -0
  106. package/krl/io.picolabs.did-o.krl +0 -349
  107. package/krl/test/didtestdid.krl +0 -78
@@ -1,7 +1,6 @@
1
- /* Rules with a public facing point of entry are camelCase, internal rules are snake_case
2
- For skyQuery and parent-child trees:
3
- wrangler is built so that the parent can skyQuery its children for info at any time,
4
- but children only get information from their direct parent through event-passing to prevent race conditions
1
+ /*
2
+ Rules with a public facing point of entry are camelCase, internal rules are snake_case
3
+ For skyQuery and parent-child trees: wrangler is built so that the parent can skyQuery its children for info at any time, but children only get information from their direct parent through event-passing to prevent race conditions
5
4
  */
6
5
  ruleset io.picolabs.wrangler {
7
6
  meta {
@@ -12,19 +11,19 @@ ruleset io.picolabs.wrangler {
12
11
  This Ruleset/Module provides a developer interface to the pico (persistent compute object).
13
12
  When a pico is created this ruleset will be installed to provide essential services.
14
13
  >>
15
- author "BYU Pico Lab"
14
+ author "Pico Labs"
16
15
 
17
16
  provides skyQuery, picoQuery,
18
17
  channels, createChannel, updateChannel, deleteChannel, //channel
19
18
  discoveryChannel, filterBindingsForCaller, //discovery
20
- rulesetConfig, rulesetMeta, installedRIDs, //ruleset
21
- children, parent_eci, name, myself, myDid, publicIntro, establishSubscription, callerDid //pico
19
+ rulesetConfig, rulesetMeta, installedRIDs, picoSchema, rulesetSchema, channelSchema, schemaBindings, rulesetWarnings, //ruleset / schema
20
+ children, parent_eci, name, myself, myDid, publicIntro, establishSubscription, establishRelationship, callerDid //pico
22
21
 
23
22
  shares skyQuery, picoQuery,
24
23
  channels, //channel
25
24
  discoveryChannel, filterBindingsForCaller, //discovery
26
- rulesetConfig, rulesetMeta,installedRIDs, //ruleset
27
- children, parent_eci, name, myself, myDid, publicIntro, establishSubscription, callerDid, id //pico
25
+ rulesetConfig, rulesetMeta, installedRIDs, picoSchema, rulesetSchema, channelSchema, schemaBindings, rulesetWarnings, //ruleset / schema
26
+ children, parent_eci, name, myself, myDid, publicIntro, establishSubscription, establishRelationship, callerDid, id //pico
28
27
  }
29
28
  global {
30
29
  __testing = { "queries": [ {"name": "name"},
@@ -32,7 +31,7 @@ ruleset io.picolabs.wrangler {
32
31
  { "name": "channels", "args":["tags"] },
33
32
  { "name": "discoveryChannel"},
34
33
  { "name": "installedRIDs"},
35
- {"name":"skyQuery", "args":["eci", "mod", "func", "params","_host","_path","_root_url"]},
34
+ {"name":"picoQuery", "args":["eci", "mod", "func", "params","_host","_path","_root_url"]},
36
35
  {"name":"children", "args":[]}
37
36
  ],
38
37
  "events": [
@@ -122,6 +121,7 @@ ruleset io.picolabs.wrangler {
122
121
  (status == 200 && not is_bad_response) => response_content | error.klog("error: ")
123
122
  }
124
123
 
124
+ // Deprecated: use picoQuery. Shared for old rulesets; not discoverable.
125
125
  skyQuery = function(eci, mod, func, params,_host,_path,_root_url) { // path must start with "/"", _host must include protocol(http:// or https://)
126
126
  //.../sky/query/<eci>/<rid>/<name>?name0=value0&...&namen=valuen
127
127
  thisPico = ctx:channels.any(function(c){c{"id"}==eci})
@@ -143,6 +143,23 @@ ruleset io.picolabs.wrangler {
143
143
  response
144
144
  }
145
145
 
146
+ /**
147
+ * Query a shared function on another pico. Picos on this engine are queried
148
+ * directly (which also works over parent/child family channels); a DID is
149
+ * queried over DIDComm; picos on another engine (_host) over HTTP. Querying
150
+ * one of this pico's own channels is refused. On failure, returns a map with
151
+ * error, httpStatus, and picoQueryError.
152
+ * @param eci String "channel on the other pico, or its DID"
153
+ * @param mod String "ruleset id on the other pico"
154
+ * @param func String "shared function to call"
155
+ * @param params Map "arguments for the function"
156
+ * @param _host String "the other pico's engine URL, if on a different engine"
157
+ * @param _path String "path prefix on that engine (default /sky/cloud/)"
158
+ * @param _root_url String "full query URL prefix, instead of _host and _path"
159
+ * @returns Any "the function's result, or an error map"
160
+ * @example "child's name" { "eci": "<child family eci>", "mod": "io.picolabs.wrangler", "func": "name" }
161
+ * @example "another engine" { "eci": "<eci>", "mod": "<rid>", "func": "<function>", "params": {}, "_host": "https://other.example" }
162
+ */
146
163
  picoQuery = function(eci, mod, func, params,_host,_path,_root_url) {
147
164
  isDid = eci.match(re#^did:#)
148
165
  thisPico = ctx:channels.any(function(c){c{"id"}==eci})
@@ -168,22 +185,95 @@ ruleset io.picolabs.wrangler {
168
185
  ctx:rulesets.filter(function(rs){rs{"rid"}==rid}).head()
169
186
  }
170
187
 
188
+ /**
189
+ * The configuration an installed ruleset was installed with, or null if it
190
+ * isn't installed.
191
+ * @param rid String "ruleset id"
192
+ * @returns Map
193
+ */
171
194
  rulesetConfig = function(rid) {
172
195
  rulesetByRID(rid){"config"}
173
196
  }
174
197
 
198
+ /**
199
+ * The meta block of an installed ruleset (name, description, shares, provides,
200
+ * …), or null if it isn't installed.
201
+ * @param rid String "ruleset id"
202
+ * @returns Map
203
+ */
175
204
  rulesetMeta = function(rid) {
176
205
  rulesetByRID(rid){["meta","krlMeta"]}
177
206
  }
178
207
 
208
+ /**
209
+ * Ids of the rulesets installed on this pico.
210
+ * @returns Array
211
+ */
179
212
  installedRIDs = function() {
180
213
  ctx:rulesets.map(function(rs){rs{"rid"}})
181
214
  }
182
215
 
216
+ /**
217
+ * Everything discoverable on this pico: the annotated operations and queries of
218
+ * all installed rulesets, merged and grouped by event, with any attr type
219
+ * conflicts between rulesets. For discovery and generated tools (MCP).
220
+ * @returns Map "{ version, rulesets, events, queries, conflicts }"
221
+ */
222
+ picoSchema = function() {
223
+ ctx:picoSchema()
224
+ }
225
+
226
+ /**
227
+ * The discovery schema of one installed ruleset: its annotated operations (with
228
+ * their select, condition, prechecks, emits, and the other rules on the same
229
+ * event) and queries. What the Testing tab shows. Null if not installed.
230
+ * @param rid String "ruleset id"
231
+ * @returns Map
232
+ * @example "one ruleset" { "rid": "io.picolabs.pds" }
233
+ * @example "all installed" {}
234
+ */
235
+ rulesetSchema = function(rid = null) {
236
+ ctx:rulesetSchema(rid)
237
+ }
238
+
239
+ /**
240
+ * Compiler/schema warnings for an installed ruleset (from last flush/load).
241
+ * @param rid String "ruleset id"
242
+ * @returns Array
243
+ */
244
+ rulesetWarnings = function(rid) {
245
+ ctx:rulesetWarnings(rid)
246
+ }
247
+
248
+ /**
249
+ * The part of picoSchema() a channel allows: what a caller holding this ECI can
250
+ * discover and use. Use the caller's own ECI for "what can I do here?", or any
251
+ * channel to check what it would expose.
252
+ * @param eci String "channel on this pico"
253
+ * @returns Map
254
+ */
255
+ channelSchema = function(eci) {
256
+ ctx:channelSchema(eci)
257
+ }
258
+
259
+ // Builds the discovery bindings() shape from a ruleset schema, for rulesets that
260
+ // implement discovery capabilities. A KRL helper; not discoverable.
261
+ schemaBindings = function(rid) {
262
+ ctx:schemaBindings(rid)
263
+ }
264
+
183
265
  // ********************************************************************************************
184
266
  // *** Channels ***
185
267
  // ********************************************************************************************
186
268
 
269
+ /**
270
+ * This pico's channels, with their tags and event and query policies. With tags,
271
+ * only channels whose tags are exactly those (order and case don't matter).
272
+ * @param tags String "comma-separated tags, or an array of tags"
273
+ * @returns Array
274
+ * @example "all" {}
275
+ * @example "by tags" { "tags": "discovery" }
276
+ */
187
277
  channels = function(tags){
188
278
  all_channels = ctx:channels
189
279
  str_tags = tags.typeof()=="Array" => tags.join(",") | tags
@@ -233,6 +323,11 @@ ruleset io.picolabs.wrangler {
233
323
  }
234
324
  }
235
325
 
326
+ /**
327
+ * This pico's discovery channel, which every pico has: integrators query it to
328
+ * learn what the pico can do.
329
+ * @returns Map "the channel, including its id"
330
+ */
236
331
  discoveryChannel = function() {
237
332
  channels("discovery").head()
238
333
  }
@@ -309,6 +404,8 @@ ruleset io.picolabs.wrangler {
309
404
  }
310
405
  }
311
406
 
407
+ // Filters a bindings() map down to what caller_eci's channel policy allows. A KRL
408
+ // helper for discovery rulesets; not discoverable.
312
409
  filterBindingsForCaller = function(bindings, caller_eci, rid) {
313
410
  caller_eci.isnull() => bindings |
314
411
  filterBindingsBody(bindings.defaultsTo({}), caller_eci, rid)
@@ -318,6 +415,10 @@ ruleset io.picolabs.wrangler {
318
415
  // *** Picos ***
319
416
  // ********************************************************************************************
320
417
 
418
+ /**
419
+ * This pico's wrangler name, id, and the ECI it was created with.
420
+ * @returns Map "{ name, id, eci }"
421
+ */
321
422
  myself = function(){
322
423
  {
323
424
  "name":ent:name,
@@ -326,12 +427,21 @@ ruleset io.picolabs.wrangler {
326
427
  }
327
428
  }
328
429
 
329
- /** Portable did:webvh for this pico (Layer 2). */
430
+ /**
431
+ * This pico's portable did:webvh, the identity other picos and meshes use for
432
+ * Layer 2 relationships. It survives moving the pico to another engine.
433
+ * @returns String
434
+ */
330
435
  myDid = function() {
331
436
  dido:myDid()
332
437
  }
333
438
 
334
- /** True when this pico accepts unsolicited intro DIDComm on its did:webvh. */
439
+ /**
440
+ * True when this pico accepts unsolicited introduction messages (Layer 2
441
+ * relationship requests) on its did:webvh. Change it with
442
+ * wrangler:set_public_intro.
443
+ * @returns Boolean
444
+ */
335
445
  publicIntro = function() {
336
446
  dido:publicIntro()
337
447
  }
@@ -340,16 +450,25 @@ ruleset io.picolabs.wrangler {
340
450
  dido:setPublicIntro(enabled)
341
451
  }
342
452
 
343
- /** Layer 2: create did:peer + internal Rx for a subscription bus map. */
453
+ // Layer 2: create did:peer + internal Rx for a relationship bus map.
454
+ // Called by io.picolabs.subscription; not discoverable.
344
455
  establishSubscription = function(bus) {
345
456
  dido:establishSubscription(bus)
346
457
  }
347
458
 
348
- /** did:webvh of the pico that sent the current event (layer2 cross-pico delivery). */
459
+ // Alias for establishSubscription (preferred name in new rulesets).
460
+ establishRelationship = establishSubscription
461
+
462
+ // did:webvh of the pico that sent the current event (layer2 cross-pico delivery).
463
+ // Only meaningful inside a rule handling that event; not discoverable.
349
464
  callerDid = function() {
350
465
  event:attr("callerDid")
351
466
  }
352
467
 
468
+ /**
469
+ * This pico's children, each with its family-channel ECI, name, and parent ECI.
470
+ * @returns Array "[ { eci, name, parent_eci } ]"
471
+ */
353
472
  children = function() {
354
473
  convert = function(eci){
355
474
  pico = {}
@@ -363,17 +482,80 @@ ruleset io.picolabs.wrangler {
363
482
  wrangler_children
364
483
  }
365
484
 
485
+ /**
486
+ * The family-channel ECI of this pico's parent; null for a root pico.
487
+ * @returns String
488
+ */
366
489
  parent_eci = function() {
367
490
  ent:parent_eci
368
491
  }
369
492
 
493
+ /**
494
+ * This pico's wrangler name.
495
+ * @returns String
496
+ */
370
497
  name = function() {
371
498
  ent:name
372
499
  }
373
500
 
501
+ /**
502
+ * This pico's id.
503
+ * @returns String
504
+ */
374
505
  id = function() {
375
506
  meta:picoId
376
507
  }
508
+
509
+ // OS bootstrap for a new child (shared by events and import queries).
510
+ bootstrapNewChild = defaction(name, passthroughAttrs) {
511
+ attrs = passthroughAttrs.defaultsTo({})
512
+ policyCeiling = attrs{"policyCeiling"}
513
+ engine_ui_rid = "io.picolabs.pico-engine-ui"
514
+ engine_ui_ruleset = function(){
515
+ the_ruleset = ctx:rulesets
516
+ .filter(function(r){r.get("rid")==engine_ui_rid})
517
+ .head();
518
+ { "url":the_ruleset.get("url"),
519
+ "config":the_ruleset.get("config")
520
+ }
521
+ }
522
+ parentUiEci = ctx:channels
523
+ .filter(function(c){c["tags"].sort().join(",") == "engine,ui"})
524
+ .map(function(c){c["id"]})
525
+ .head()
526
+ every {
527
+ ctx:newPico(
528
+ rulesets=[
529
+ engine_ui_ruleset(),
530
+ { "url": ctx:rid_url, "config": {} }
531
+ ],
532
+ policyCeiling=policyCeiling
533
+ ) setting(newEci)
534
+ ctx:eventQuery(
535
+ eci=newEci,
536
+ domain="engine_ui",
537
+ name="setup",
538
+ rid=engine_ui_rid,
539
+ queryName="uiECI"
540
+ ) setting(newUiECI)
541
+ ctx:event(
542
+ eci=newEci,
543
+ domain="wrangler",
544
+ name="pico_created",
545
+ attrs=attrs
546
+ )
547
+ ctx:event(
548
+ eci=newUiECI,
549
+ domain="engine_ui",
550
+ name="box",
551
+ attrs={
552
+ "name": name,
553
+ "parentUiEci": parentUiEci
554
+ }
555
+ )
556
+ }
557
+ return {"eci": newEci, "uiEci": newUiECI}
558
+ }
377
559
 
378
560
  }
379
561
 
@@ -397,6 +579,15 @@ ruleset io.picolabs.wrangler {
397
579
  // ********************************************************************************************
398
580
 
399
581
 
582
+ /**
583
+ * Install a ruleset that lives next to another one: the URL is built by
584
+ * replacing the last part of absoluteURL with <rid>.krl (pass meta:rulesetURI to
585
+ * install a sibling of the calling ruleset). Continues as an install by url.
586
+ * @attr absoluteURL String "URL of a ruleset in the same directory"
587
+ * @attr rid String "id of the ruleset to install"
588
+ * @attr config Map optional "configuration for the installed ruleset"
589
+ * @example "sibling of this ruleset" { "absoluteURL": "<meta:rulesetURI>", "rid": "<rid>" }
590
+ */
400
591
  rule install_ruleset_relatively {
401
592
  select when wrangler install_ruleset_request
402
593
  absoluteURL re#(.+)# // required
@@ -414,14 +605,28 @@ ruleset io.picolabs.wrangler {
414
605
  }
415
606
  }
416
607
 
608
+ /**
609
+ * Install (or reinstall) a ruleset from a URL on this pico. The URL is fetched
610
+ * and compiled first, so this also picks up a new version. Raises
611
+ * wrangler:ruleset_installed with the installed rid.
612
+ * @attr url String "URL of the .krl file"
613
+ * @attr config Map optional "configuration for the installed ruleset"
614
+ * @example "from a URL" { "url": "https://example.com/krl/<rid>.krl" }
615
+ * @example "with config" { "url": "https://example.com/krl/<rid>.krl", "config": { "<key>": "<value>" } }
616
+ */
417
617
  rule install_ruleset_absolutely {
418
618
  select when wrangler install_ruleset_request
419
619
  url re#(.+)# // required
420
620
  setting(url)
421
621
  pre {
422
622
  config = event:attr("config") || {}
623
+ validation = ctx:validate(url)
624
+ ok = validation{"ok"}
625
+ validate_errors = validation{"errors"}
626
+ validate_warnings = validation{"warnings"}
627
+ validate_rid = validation{"rid"}
423
628
  }
424
- every {
629
+ if ok then every {
425
630
  ctx:flush(url=url)
426
631
  ctx:install(url=url, config=config) setting(rid)
427
632
  }
@@ -429,8 +634,18 @@ ruleset io.picolabs.wrangler {
429
634
  raise wrangler event "ruleset_installed" attributes
430
635
  event:attrs.put({"rids": [rid]})
431
636
  }
637
+ else {
638
+ raise wrangler event "ruleset_install_failed" attributes
639
+ {"url": url, "rid": validate_rid, "errors": validate_errors, "warnings": validate_warnings}
640
+ }
432
641
  }
433
642
 
643
+ /**
644
+ * Uninstall a ruleset from this pico. Refused if another installed ruleset uses
645
+ * it as a module. Raises wrangler:ruleset_uninstalled.
646
+ * @attr rid String "ruleset id"
647
+ * @example "by rid" { "rid": "<rid>" }
648
+ */
434
649
  rule uninstall_one_ruleset {
435
650
  select when wrangler uninstall_ruleset_request
436
651
  rid re#(.+)# setting(rid)
@@ -440,6 +655,10 @@ ruleset io.picolabs.wrangler {
440
655
  }
441
656
  }
442
657
 
658
+ /**
659
+ * Re-fetch and recompile every ruleset installed on this pico, so each picks up
660
+ * its latest source. Raises wrangler:rulesets_flushed when done.
661
+ */
443
662
  rule flush_all_rulesets {
444
663
  select when wrangler rulesets_need_flushing
445
664
  foreach ctx:rulesets setting(rs)
@@ -453,6 +672,14 @@ ruleset io.picolabs.wrangler {
453
672
  // *** Channels ***
454
673
  // ********************************************************************************************
455
674
 
675
+ /**
676
+ * Create a channel on this pico. Raises wrangler:channel_created with the new
677
+ * channel (including its id).
678
+ * @attr tags Array "tags for the channel, e.g. [\"myapp\", \"webhook\"]"
679
+ * @attr eventPolicy Map "{ allow: [ { domain, name } ], deny: [ … ] }"
680
+ * @attr queryPolicy Map "{ allow: [ { rid, name } ], deny: [ … ] }"
681
+ * @example "webhook" { "tags": ["<app>", "webhook"], "eventPolicy": { "allow": [ { "domain": "<app>", "name": "*" } ], "deny": [] }, "queryPolicy": { "allow": [], "deny": [] } }
682
+ */
456
683
  rule createChannel {
457
684
  select when wrangler new_channel_request
458
685
  pre {
@@ -468,6 +695,10 @@ ruleset io.picolabs.wrangler {
468
695
  }
469
696
  }
470
697
 
698
+ /**
699
+ * Delete a channel on this pico. Raises wrangler:channel_deleted.
700
+ * @attr eci String "the channel to delete"
701
+ */
471
702
  rule deleteChannel {
472
703
  select when wrangler channel_deletion_request
473
704
  eci re#^(.+)$# // required
@@ -478,6 +709,14 @@ ruleset io.picolabs.wrangler {
478
709
  }
479
710
  }
480
711
 
712
+ /**
713
+ * Replace a channel's tags and policies. Raises wrangler:channel_updated with the
714
+ * updated channel.
715
+ * @attr eci String "the channel to update"
716
+ * @attr tags Array "new tags"
717
+ * @attr eventPolicy Map "new event policy"
718
+ * @attr queryPolicy Map "new query policy"
719
+ */
481
720
  rule updateChannel {
482
721
  select when wrangler channel_update_request
483
722
  pre {
@@ -499,57 +738,28 @@ ruleset io.picolabs.wrangler {
499
738
  // ********************************************************************************************
500
739
  //-------------------- Picos initializing ----------------------
501
740
 
741
+ /**
742
+ * Create a child pico with wrangler, PDS, and relationships installed. Raises
743
+ * wrangler:new_child_created here with the child's family-channel eci and uiEci.
744
+ * Other attrs are passed to the child, and come back to this pico in
745
+ * wrangler:child_initialized once the child is set up (Manifold uses this, e.g.
746
+ * event_name, to tell its creations apart).
747
+ * @attr name String "name for the child"
748
+ * @attr backgroundColor String optional "developer UI color, e.g. #87cefa"
749
+ * @attr policyCeiling Map optional "max channel policy for the child pico; must not exceed parent ceiling"
750
+ * @example "named" { "name": "<name>" }
751
+ * @example "with color" { "name": "<name>", "backgroundColor": "#ffb347" }
752
+ */
502
753
  rule createChild {
503
754
  select when wrangler new_child_request
504
755
  name re#.+# // required
505
756
  backgroundColor re#.*# // optional (layout rule assigns palette color)
506
- pre {
507
- name = event:attrs{"name"}
508
- engine_ui_rid = "io.picolabs.pico-engine-ui"
509
- engine_ui_ruleset = function(){
510
- the_ruleset = ctx:rulesets
511
- .filter(function(r){r.get("rid")==engine_ui_rid})
512
- .head();
513
- { "url":the_ruleset.get("url"),
514
- "config":the_ruleset.get("config")
515
- }
516
- }
517
- parentUiEci = ctx:channels
518
- .filter(function(c){c["tags"].sort().join(",") == "engine,ui"})
519
- .map(function(c){c["id"]})
520
- .head()
521
- }
522
757
  every {
523
- ctx:newPico(rulesets=[
524
- engine_ui_ruleset(),
525
- { "url": ctx:rid_url, "config": {} }
526
- ]) setting(newEci)
527
- ctx:eventQuery(
528
- eci=newEci,
529
- domain="engine_ui",
530
- name="setup",
531
- rid=engine_ui_rid,
532
- queryName="uiECI"
533
- ) setting(newUiECI)
534
- ctx:event(
535
- eci=newEci,
536
- domain="wrangler",
537
- name="pico_created",
538
- attrs=event:attrs
539
- )
540
- ctx:event(
541
- eci=newUiECI,
542
- domain="engine_ui",
543
- name="box",
544
- attrs={
545
- "name": name,
546
- "parentUiEci": parentUiEci
547
- }
548
- )
758
+ bootstrapNewChild(event:attrs{"name"}, event:attrs) setting(boot)
549
759
  }
550
760
  fired {
551
761
  raise wrangler event "new_child_created"
552
- attributes event:attrs.put({"eci":newEci, "uiEci": newUiECI})
762
+ attributes event:attrs.put(boot)
553
763
  }
554
764
  }
555
765
 
@@ -586,6 +796,15 @@ ruleset io.picolabs.wrangler {
586
796
  "domain": "wrangler", "type": "child_initialized",
587
797
  "attrs" : event:attrs })
588
798
  }
799
+
800
+ rule note_subtree_import {
801
+ select when wrangler pico_imported
802
+ fired {
803
+ ent:last_subtree_import := event:attrs
804
+ raise wrangler event "subtree_imported"
805
+ attributes event:attrs
806
+ }
807
+ }
589
808
 
590
809
  // this pico is the primary pico
591
810
 
@@ -599,6 +818,10 @@ ruleset io.picolabs.wrangler {
599
818
  }
600
819
  }
601
820
 
821
+ /**
822
+ * Change this pico's wrangler name (what name() and myself() return).
823
+ * @attr name String "new name"
824
+ */
602
825
  rule take_note_of_name_change {
603
826
  select when wrangler name_changed
604
827
  name re#(.+)# // required
@@ -609,6 +832,11 @@ ruleset io.picolabs.wrangler {
609
832
  }
610
833
 
611
834
  //-------------------- PARENT PERSPECTIVE ----------------------
835
+ /**
836
+ * Delete a child pico and all of its descendants. Raises wrangler:child_deleted.
837
+ * @attr eci String "the child's family-channel ECI (from children())"
838
+ * @example "by eci" { "eci": "<child family eci>" }
839
+ */
612
840
  rule deleteOneChild {
613
841
  select when wrangler child_deletion_request
614
842
  eci re#^(.+)$# setting(eci)
@@ -668,6 +896,20 @@ ruleset io.picolabs.wrangler {
668
896
  createChannel(["discovery"], discoveryEventPolicy(), discoveryQueryPolicy())
669
897
  }
670
898
 
899
+ rule schema_updated_on_ruleset_set {
900
+ select when engine ruleset_set_changed
901
+ always {
902
+ raise wrangler event "schema_updated" attributes event:attrs
903
+ }
904
+ }
905
+
906
+ /**
907
+ * Turn on or off accepting unsolicited introduction messages (Layer 2
908
+ * relationship requests) on this pico's did:webvh. See publicIntro().
909
+ * @attr enabled Boolean "true to accept introductions"
910
+ * @example "accept" { "enabled": true }
911
+ * @example "refuse" { "enabled": false }
912
+ */
671
913
  rule wrangler_set_public_intro {
672
914
  select when wrangler set_public_intro
673
915
  setPublicIntro(event:attr("enabled"))
@@ -0,0 +1,118 @@
1
+ "use strict";
2
+
3
+ const fs = require("fs");
4
+ const path = require("path");
5
+
6
+ function readDoc(relativeFromPackage) {
7
+ const filePath = path.join(__dirname, "..", relativeFromPackage);
8
+ try {
9
+ return fs.readFileSync(filePath, "utf8");
10
+ } catch (_e) {
11
+ return "";
12
+ }
13
+ }
14
+
15
+ function registerDevResources(server, client) {
16
+ server.resource(
17
+ "krl-conventions",
18
+ "pico://docs/krl-conventions",
19
+ {
20
+ description: "KRL rule shape and conventions (from CLAUDE.md)",
21
+ mimeType: "text/markdown",
22
+ },
23
+ async () => ({
24
+ contents: [
25
+ {
26
+ uri: "pico://docs/krl-conventions",
27
+ mimeType: "text/markdown",
28
+ text: readDoc("../../../CLAUDE.md"),
29
+ },
30
+ ],
31
+ })
32
+ );
33
+
34
+ server.resource(
35
+ "pico-overview",
36
+ "pico://docs/pico-overview",
37
+ {
38
+ description: "Pico model overview",
39
+ mimeType: "text/markdown",
40
+ },
41
+ async () => ({
42
+ contents: [
43
+ {
44
+ uri: "pico://docs/pico-overview",
45
+ mimeType: "text/markdown",
46
+ text:
47
+ readDoc("public/docs/pico-overview.md") ||
48
+ readDoc("../../../docs/design/pico-overview.md"),
49
+ },
50
+ ],
51
+ })
52
+ );
53
+
54
+ server.resource(
55
+ "pico-engine-operator",
56
+ "pico://docs/pico-engine",
57
+ {
58
+ description: "Pico engine operator notes",
59
+ mimeType: "text/markdown",
60
+ },
61
+ async () => ({
62
+ contents: [
63
+ {
64
+ uri: "pico://docs/pico-engine",
65
+ mimeType: "text/markdown",
66
+ text: readDoc("public/docs/pico-engine.md"),
67
+ },
68
+ ],
69
+ })
70
+ );
71
+
72
+ server.prompt(
73
+ "write-ruleset",
74
+ "Draft KRL using pico conventions; optionally pass target ECI to embed channel schema",
75
+ {
76
+ purpose: zOptionalString(),
77
+ eci: zOptionalString(),
78
+ },
79
+ async ({ purpose, eci }) => {
80
+ let schemaBlock = "";
81
+ if (eci) {
82
+ try {
83
+ const ui = await client.resolveUiEci();
84
+ const target = eci || ui;
85
+ const data = await client.channelQuery(
86
+ target,
87
+ "io.picolabs.wrangler",
88
+ "channelSchema",
89
+ { eci: target }
90
+ );
91
+ schemaBlock = `\n\nChannel schema (JSON):\n\`\`\`json\n${JSON.stringify(data, null, 2)}\n\`\`\`\n`;
92
+ } catch (err) {
93
+ schemaBlock = `\n\n(Could not load channel schema: ${String(err)})\n`;
94
+ }
95
+ }
96
+ const conventions = readDoc("../../../CLAUDE.md");
97
+ return {
98
+ messages: [
99
+ {
100
+ role: "user",
101
+ content: {
102
+ type: "text",
103
+ text:
104
+ `Write a KRL ruleset${purpose ? ` for: ${purpose}` : ""}. Follow these conventions:\n\n${conventions}${schemaBlock}`,
105
+ },
106
+ },
107
+ ],
108
+ };
109
+ }
110
+ );
111
+ }
112
+
113
+ function zOptionalString() {
114
+ const { z } = require("zod");
115
+ return z.string().optional();
116
+ }
117
+
118
+ module.exports = { registerDevResources };