pico-engine 1.6.4 → 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 (98) hide show
  1. package/README.md +13 -8
  2. package/dist/RulesetRegistryLoaderFs.js +14 -2
  3. package/dist/auth/cookies.js +32 -0
  4. package/dist/auth/index.js +6 -1
  5. package/dist/channelIdentityPolicy.js +22 -0
  6. package/dist/cli.js +104 -69
  7. package/dist/engineConfig.js +280 -0
  8. package/dist/identity/IdentityService.js +90 -0
  9. package/dist/identity/crossPico.js +24 -8
  10. package/dist/identity/didoModule.js +80 -18
  11. package/dist/identity/establishSubscription.js +2 -2
  12. package/dist/identity/identityPortable.js +92 -0
  13. package/dist/identity/index.js +10 -1
  14. package/dist/identity/localPeerReconcile.js +65 -0
  15. package/dist/identity/peerDid4.js +175 -0
  16. package/dist/identity/peerDid4Create.js +90 -0
  17. package/dist/identity/portableExportPrepare.js +196 -0
  18. package/dist/identity/portableMove.js +87 -0
  19. package/dist/identity/skyIntro.js +6 -3
  20. package/dist/identity/skyProtocol.js +26 -1
  21. package/dist/identity/skyRotation.js +121 -0
  22. package/dist/identity/store.js +5 -1
  23. package/dist/identity/subscriptionEntSync.js +72 -0
  24. package/dist/identity/veramoDidComm.js +41 -2
  25. package/dist/identity/webvh.js +4 -2
  26. package/dist/identity/webvhRelocation.js +115 -0
  27. package/dist/index.js +82 -22
  28. package/dist/logging.js +8 -12
  29. package/dist/oauth/OAuthService.js +6 -2
  30. package/dist/policyConfigFromJson.js +112 -0
  31. package/dist/runMcp.js +27 -0
  32. package/dist/server.js +56 -24
  33. package/dist/subtreeWrangler.js +180 -0
  34. package/dist/uiChannelPolicies.js +15 -0
  35. package/krl/io.picolabs.oauth.krl +41 -2
  36. package/krl/io.picolabs.pds.krl +131 -10
  37. package/krl/io.picolabs.pico-engine-ui.krl +209 -21
  38. package/krl/io.picolabs.portable_subtree.krl +97 -0
  39. package/krl/io.picolabs.subscription.krl +180 -72
  40. package/krl/io.picolabs.wrangler.krl +296 -57
  41. package/mcp/devResources.js +118 -0
  42. package/mcp/devTools.js +351 -0
  43. package/mcp/engineClient.js +133 -0
  44. package/mcp/meshHttp.js +137 -0
  45. package/mcp/meshTools.js +189 -0
  46. package/mcp/runStdio.js +34 -0
  47. package/mcp/schemaToZod.js +56 -0
  48. package/package.json +20 -8
  49. package/public/docs/_sidebar.md +2 -1
  50. package/public/docs/llms-full.txt +479 -0
  51. package/public/docs/llms.txt +37 -0
  52. package/public/docs/openapi.yaml +78 -0
  53. package/public/docs/pico-engine.md +235 -4
  54. package/public/docs/pico-overview.md +117 -0
  55. package/public/docs/pico.md +3 -1
  56. package/public/docs/rulesets/README.md +25 -0
  57. package/public/docs/rulesets/io.picolabs.oauth.md +71 -0
  58. package/public/docs/rulesets/io.picolabs.pds.md +327 -0
  59. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +65 -0
  60. package/public/docs/rulesets/io.picolabs.portable_subtree.md +94 -0
  61. package/public/docs/rulesets/io.picolabs.subscription.md +398 -0
  62. package/public/docs/rulesets/io.picolabs.wrangler.md +471 -0
  63. package/public/pico-engine-ui.css +1 -1
  64. package/public/pico-engine-ui.js +28 -26
  65. package/src/RulesetRegistryLoaderFs.ts +18 -3
  66. package/src/auth/cookies.ts +34 -0
  67. package/src/auth/index.ts +7 -0
  68. package/src/channelIdentityPolicy.ts +29 -0
  69. package/src/cli.ts +68 -37
  70. package/src/engineConfig.ts +345 -0
  71. package/src/identity/IdentityService.ts +189 -1
  72. package/src/identity/crossPico.ts +57 -8
  73. package/src/identity/didoModule.ts +140 -23
  74. package/src/identity/establishSubscription.ts +2 -2
  75. package/src/identity/identityPortable.ts +153 -0
  76. package/src/identity/index.ts +14 -0
  77. package/src/identity/localPeerReconcile.ts +97 -0
  78. package/src/identity/peerDid4.ts +197 -0
  79. package/src/identity/peerDid4Create.ts +121 -0
  80. package/src/identity/portableExportPrepare.ts +302 -0
  81. package/src/identity/portableMove.ts +193 -0
  82. package/src/identity/skyIntro.ts +11 -11
  83. package/src/identity/skyProtocol.ts +46 -0
  84. package/src/identity/skyRotation.ts +211 -0
  85. package/src/identity/store.ts +5 -1
  86. package/src/identity/subscriptionEntSync.ts +97 -0
  87. package/src/identity/veramoDidComm.ts +52 -2
  88. package/src/identity/webvh.ts +4 -4
  89. package/src/identity/webvhRelocation.ts +167 -0
  90. package/src/index.ts +119 -25
  91. package/src/logging.ts +8 -14
  92. package/src/oauth/OAuthService.ts +11 -3
  93. package/src/policyConfigFromJson.ts +131 -0
  94. package/src/runMcp.ts +30 -0
  95. package/src/server.ts +79 -26
  96. package/src/subtreeWrangler.ts +278 -0
  97. package/src/uiChannelPolicies.ts +15 -0
  98. package/krl/io.picolabs.did-o.krl +0 -349
@@ -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,18 +11,18 @@ 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
19
+ rulesetConfig, rulesetMeta, installedRIDs, picoSchema, rulesetSchema, channelSchema, schemaBindings, rulesetWarnings, //ruleset / schema
21
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
25
+ rulesetConfig, rulesetMeta, installedRIDs, picoSchema, rulesetSchema, channelSchema, schemaBindings, rulesetWarnings, //ruleset / schema
27
26
  children, parent_eci, name, myself, myDid, publicIntro, establishSubscription, establishRelationship, callerDid, id //pico
28
27
  }
29
28
  global {
@@ -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,19 +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 relationship 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
- /** Alias for establishSubscription (preferred name in new rulesets). */
459
+ // Alias for establishSubscription (preferred name in new rulesets).
349
460
  establishRelationship = establishSubscription
350
461
 
351
- /** did:webvh of the pico that sent the current event (layer2 cross-pico delivery). */
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.
352
464
  callerDid = function() {
353
465
  event:attr("callerDid")
354
466
  }
355
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
+ */
356
472
  children = function() {
357
473
  convert = function(eci){
358
474
  pico = {}
@@ -366,17 +482,80 @@ ruleset io.picolabs.wrangler {
366
482
  wrangler_children
367
483
  }
368
484
 
485
+ /**
486
+ * The family-channel ECI of this pico's parent; null for a root pico.
487
+ * @returns String
488
+ */
369
489
  parent_eci = function() {
370
490
  ent:parent_eci
371
491
  }
372
492
 
493
+ /**
494
+ * This pico's wrangler name.
495
+ * @returns String
496
+ */
373
497
  name = function() {
374
498
  ent:name
375
499
  }
376
500
 
501
+ /**
502
+ * This pico's id.
503
+ * @returns String
504
+ */
377
505
  id = function() {
378
506
  meta:picoId
379
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
+ }
380
559
 
381
560
  }
382
561
 
@@ -400,6 +579,15 @@ ruleset io.picolabs.wrangler {
400
579
  // ********************************************************************************************
401
580
 
402
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
+ */
403
591
  rule install_ruleset_relatively {
404
592
  select when wrangler install_ruleset_request
405
593
  absoluteURL re#(.+)# // required
@@ -417,14 +605,28 @@ ruleset io.picolabs.wrangler {
417
605
  }
418
606
  }
419
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
+ */
420
617
  rule install_ruleset_absolutely {
421
618
  select when wrangler install_ruleset_request
422
619
  url re#(.+)# // required
423
620
  setting(url)
424
621
  pre {
425
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"}
426
628
  }
427
- every {
629
+ if ok then every {
428
630
  ctx:flush(url=url)
429
631
  ctx:install(url=url, config=config) setting(rid)
430
632
  }
@@ -432,8 +634,18 @@ ruleset io.picolabs.wrangler {
432
634
  raise wrangler event "ruleset_installed" attributes
433
635
  event:attrs.put({"rids": [rid]})
434
636
  }
637
+ else {
638
+ raise wrangler event "ruleset_install_failed" attributes
639
+ {"url": url, "rid": validate_rid, "errors": validate_errors, "warnings": validate_warnings}
640
+ }
435
641
  }
436
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
+ */
437
649
  rule uninstall_one_ruleset {
438
650
  select when wrangler uninstall_ruleset_request
439
651
  rid re#(.+)# setting(rid)
@@ -443,6 +655,10 @@ ruleset io.picolabs.wrangler {
443
655
  }
444
656
  }
445
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
+ */
446
662
  rule flush_all_rulesets {
447
663
  select when wrangler rulesets_need_flushing
448
664
  foreach ctx:rulesets setting(rs)
@@ -456,6 +672,14 @@ ruleset io.picolabs.wrangler {
456
672
  // *** Channels ***
457
673
  // ********************************************************************************************
458
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
+ */
459
683
  rule createChannel {
460
684
  select when wrangler new_channel_request
461
685
  pre {
@@ -471,6 +695,10 @@ ruleset io.picolabs.wrangler {
471
695
  }
472
696
  }
473
697
 
698
+ /**
699
+ * Delete a channel on this pico. Raises wrangler:channel_deleted.
700
+ * @attr eci String "the channel to delete"
701
+ */
474
702
  rule deleteChannel {
475
703
  select when wrangler channel_deletion_request
476
704
  eci re#^(.+)$# // required
@@ -481,6 +709,14 @@ ruleset io.picolabs.wrangler {
481
709
  }
482
710
  }
483
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
+ */
484
720
  rule updateChannel {
485
721
  select when wrangler channel_update_request
486
722
  pre {
@@ -502,57 +738,28 @@ ruleset io.picolabs.wrangler {
502
738
  // ********************************************************************************************
503
739
  //-------------------- Picos initializing ----------------------
504
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
+ */
505
753
  rule createChild {
506
754
  select when wrangler new_child_request
507
755
  name re#.+# // required
508
756
  backgroundColor re#.*# // optional (layout rule assigns palette color)
509
- pre {
510
- name = event:attrs{"name"}
511
- engine_ui_rid = "io.picolabs.pico-engine-ui"
512
- engine_ui_ruleset = function(){
513
- the_ruleset = ctx:rulesets
514
- .filter(function(r){r.get("rid")==engine_ui_rid})
515
- .head();
516
- { "url":the_ruleset.get("url"),
517
- "config":the_ruleset.get("config")
518
- }
519
- }
520
- parentUiEci = ctx:channels
521
- .filter(function(c){c["tags"].sort().join(",") == "engine,ui"})
522
- .map(function(c){c["id"]})
523
- .head()
524
- }
525
757
  every {
526
- ctx:newPico(rulesets=[
527
- engine_ui_ruleset(),
528
- { "url": ctx:rid_url, "config": {} }
529
- ]) setting(newEci)
530
- ctx:eventQuery(
531
- eci=newEci,
532
- domain="engine_ui",
533
- name="setup",
534
- rid=engine_ui_rid,
535
- queryName="uiECI"
536
- ) setting(newUiECI)
537
- ctx:event(
538
- eci=newEci,
539
- domain="wrangler",
540
- name="pico_created",
541
- attrs=event:attrs
542
- )
543
- ctx:event(
544
- eci=newUiECI,
545
- domain="engine_ui",
546
- name="box",
547
- attrs={
548
- "name": name,
549
- "parentUiEci": parentUiEci
550
- }
551
- )
758
+ bootstrapNewChild(event:attrs{"name"}, event:attrs) setting(boot)
552
759
  }
553
760
  fired {
554
761
  raise wrangler event "new_child_created"
555
- attributes event:attrs.put({"eci":newEci, "uiEci": newUiECI})
762
+ attributes event:attrs.put(boot)
556
763
  }
557
764
  }
558
765
 
@@ -589,6 +796,15 @@ ruleset io.picolabs.wrangler {
589
796
  "domain": "wrangler", "type": "child_initialized",
590
797
  "attrs" : event:attrs })
591
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
+ }
592
808
 
593
809
  // this pico is the primary pico
594
810
 
@@ -602,6 +818,10 @@ ruleset io.picolabs.wrangler {
602
818
  }
603
819
  }
604
820
 
821
+ /**
822
+ * Change this pico's wrangler name (what name() and myself() return).
823
+ * @attr name String "new name"
824
+ */
605
825
  rule take_note_of_name_change {
606
826
  select when wrangler name_changed
607
827
  name re#(.+)# // required
@@ -612,6 +832,11 @@ ruleset io.picolabs.wrangler {
612
832
  }
613
833
 
614
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
+ */
615
840
  rule deleteOneChild {
616
841
  select when wrangler child_deletion_request
617
842
  eci re#^(.+)$# setting(eci)
@@ -671,6 +896,20 @@ ruleset io.picolabs.wrangler {
671
896
  createChannel(["discovery"], discoveryEventPolicy(), discoveryQueryPolicy())
672
897
  }
673
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
+ */
674
913
  rule wrangler_set_public_intro {
675
914
  select when wrangler set_public_intro
676
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 };