pico-engine 1.9.4 → 1.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (186) hide show
  1. package/README.md +13 -5
  2. package/demos/bootstrap/README.md +12 -0
  3. package/demos/bootstrap/com.example.visitors.bootstrap.krl +101 -0
  4. package/demos/bootstrap/com.example.visitors.format.krl +25 -0
  5. package/demos/bootstrap/com.example.visitors.krl +228 -0
  6. package/demos/bootstrap/try-it.md +5 -0
  7. package/demos/child_tasks/README.md +12 -0
  8. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +88 -0
  9. package/demos/child_tasks/com.example.task_runner.krl +139 -0
  10. package/demos/child_tasks/com.example.task_worker.krl +45 -0
  11. package/demos/child_tasks/try-it.md +5 -0
  12. package/demos/collection/README.md +13 -0
  13. package/demos/collection/com.example.collection.bootstrap.krl +148 -0
  14. package/demos/collection/com.example.collection.krl +95 -0
  15. package/demos/collection/com.example.collection.report.krl +93 -0
  16. package/demos/collection/com.example.collection.room.krl +101 -0
  17. package/demos/collection/try-it.md +6 -0
  18. package/demos/echo/README.md +11 -0
  19. package/demos/echo/com.example.echo.bootstrap.krl +84 -0
  20. package/demos/echo/com.example.echo.krl +73 -0
  21. package/demos/echo/try-it.md +5 -0
  22. package/demos/guard_rules/README.md +12 -0
  23. package/demos/guard_rules/com.example.archive.bootstrap.krl +98 -0
  24. package/demos/guard_rules/com.example.archive.krl +213 -0
  25. package/demos/guard_rules/com.example.archive_store.krl +36 -0
  26. package/demos/guard_rules/try-it.md +5 -0
  27. package/demos/json_query/README.md +11 -0
  28. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  29. package/demos/json_query/com.example.json_query.krl +162 -0
  30. package/demos/json_query/try-it.md +5 -0
  31. package/demos/kblog/README.md +14 -0
  32. package/demos/kblog/com.example.kblog.bootstrap.krl +135 -0
  33. package/demos/kblog/com.example.kblog.config.krl +50 -0
  34. package/demos/kblog/com.example.kblog.data.krl +75 -0
  35. package/demos/kblog/com.example.kblog.krl +184 -0
  36. package/demos/kblog/com.example.kblog.posting.krl +109 -0
  37. package/demos/kblog/try-it.md +6 -0
  38. package/demos/layered_rulesets/README.md +13 -0
  39. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +87 -0
  40. package/demos/layered_rulesets/com.example.invitations.krl +164 -0
  41. package/demos/layered_rulesets/com.example.invitations.short_links.krl +45 -0
  42. package/demos/layered_rulesets/com.example.invitations.welcome.krl +39 -0
  43. package/demos/layered_rulesets/try-it.md +5 -0
  44. package/demos/moving_picos/README.md +15 -0
  45. package/demos/moving_picos/io.picolabs.club_gear_demo.krl +650 -0
  46. package/demos/moving_picos/io.picolabs.ride_coordinator_demo.krl +331 -0
  47. package/demos/score_tracker/README.md +11 -0
  48. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +107 -0
  49. package/demos/score_tracker/com.example.score_tracker.krl +162 -0
  50. package/demos/score_tracker/try-it.md +5 -0
  51. package/demos/secrets/README.md +12 -0
  52. package/demos/secrets/com.example.hook_service.krl +120 -0
  53. package/demos/secrets/com.example.notifier.bootstrap.krl +130 -0
  54. package/demos/secrets/com.example.notifier.krl +138 -0
  55. package/demos/secrets/try-it.md +5 -0
  56. package/demos/try-it-order.json +1 -0
  57. package/demos/two_picos/README.md +12 -0
  58. package/demos/two_picos/com.example.two_picos.answerer.krl +125 -0
  59. package/demos/two_picos/com.example.two_picos.asker.krl +124 -0
  60. package/demos/two_picos/com.example.two_picos.bootstrap.krl +134 -0
  61. package/demos/two_picos/try-it.md +5 -0
  62. package/demos/xmlui/README.md +17 -0
  63. package/demos/xmlui/com.example.contacts.krl +132 -0
  64. package/demos/xmlui/com.example.fav_color.krl +39 -0
  65. package/demos/xmlui/com.example.guestbook.krl +61 -0
  66. package/demos/xmlui/com.example.hello.krl +19 -0
  67. package/demos/xmlui/com.example.temperature_sensors_view.krl +105 -0
  68. package/demos/xmlui/com.example.thermostat.bootstrap.krl +95 -0
  69. package/demos/xmlui/com.example.thermostat.krl +124 -0
  70. package/demos/xmlui/temperature_sensors.krl +56 -0
  71. package/demos/xmlui/try-it.md +5 -0
  72. package/dist/bundledKrl.js +97 -12
  73. package/dist/cli.js +7 -1
  74. package/dist/engineConfig.js +20 -1
  75. package/dist/identity/portableMove.js +5 -1
  76. package/dist/index.js +45 -12
  77. package/dist/internalAccess.js +110 -0
  78. package/dist/oauth/OAuthService.js +172 -10
  79. package/dist/oauth/acg.js +194 -24
  80. package/dist/oauth/cimd.js +381 -0
  81. package/dist/oauth/discovery.js +175 -0
  82. package/dist/runMcp.js +1 -1
  83. package/dist/server.js +210 -47
  84. package/dist/subtreeWrangler.js +8 -5
  85. package/dist/uiChannelPolicies.js +2 -0
  86. package/krl/io.picolabs.pds.krl +109 -21
  87. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  88. package/krl/io.picolabs.wrangler.krl +21 -9
  89. package/krl/io.picolabs.xmlui.krl +3 -2
  90. package/mcp/devResources.js +52 -0
  91. package/mcp/devTools.js +40 -9
  92. package/mcp/docs/CLAUDE.md +6 -4
  93. package/mcp/docs/cookbook/README.md +23 -0
  94. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  95. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  96. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  97. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  98. package/mcp/docs/cookbook/collection/README.md +21 -0
  99. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  100. package/mcp/docs/cookbook/echo/README.md +19 -0
  101. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  102. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  103. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  104. package/mcp/docs/cookbook/json_query/README.md +26 -0
  105. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  106. package/mcp/docs/cookbook/kblog/README.md +60 -0
  107. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  108. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  109. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  110. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  111. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  112. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  113. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  114. package/mcp/docs/cookbook/secrets/README.md +25 -0
  115. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  116. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  117. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  118. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  119. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  120. package/mcp/docs/developing/README.md +28 -0
  121. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  122. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  123. package/mcp/docs/developing/converting-time-formats.md +28 -0
  124. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  125. package/mcp/docs/developing/decoding-form-data.md +67 -0
  126. package/mcp/docs/developing/engine-log-files.md +34 -0
  127. package/mcp/docs/developing/event-loop.md +77 -0
  128. package/mcp/docs/developing/events-from-email.md +80 -0
  129. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  130. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  131. package/mcp/docs/developing/misconceptions.md +467 -0
  132. package/mcp/docs/developing/names-and-scope.md +44 -0
  133. package/mcp/docs/developing/postman.md +159 -0
  134. package/mcp/docs/developing/querying-another-pico.md +47 -0
  135. package/mcp/docs/developing/singleton-picos.md +36 -0
  136. package/mcp/docs/developing/tabular-data.md +67 -0
  137. package/mcp/docs/developing/tips.md +251 -0
  138. package/mcp/docs/developing/webhook-signatures.md +56 -0
  139. package/mcp/docs/developing/workflow.md +106 -0
  140. package/mcp/docs/exp/README.md +46 -0
  141. package/mcp/docs/exp/event.md +110 -0
  142. package/mcp/docs/exp/query.md +94 -0
  143. package/mcp/docs/lessons/README.md +59 -0
  144. package/mcp/docs/lessons/events-and-queries.md +247 -0
  145. package/mcp/docs/lessons/gossip.md +28 -0
  146. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  147. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  148. package/mcp/docs/lessons/pico-state.md +267 -0
  149. package/mcp/docs/lessons/pico-views.md +290 -0
  150. package/mcp/docs/lessons/quickstart.md +157 -0
  151. package/mcp/docs/lessons/relationships.md +530 -0
  152. package/mcp/docs/lessons/scatter-gather.md +362 -0
  153. package/mcp/docs/pico-engine.md +10 -5
  154. package/mcp/docs/pico-overview.md +3 -3
  155. package/mcp/docs/wrangler/README.md +47 -0
  156. package/mcp/docs/wrangler/channels.md +235 -0
  157. package/mcp/docs/wrangler/oauth.md +56 -0
  158. package/mcp/docs/wrangler/pds.md +423 -0
  159. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  160. package/mcp/docs/wrangler/relationships.md +297 -0
  161. package/mcp/docs/wrangler/wrangler.md +253 -0
  162. package/mcp/docs/wrangler/xmlui.md +60 -0
  163. package/mcp/engineClient.js +57 -5
  164. package/mcp/mcpScopes.js +118 -0
  165. package/mcp/meshHttp.js +151 -45
  166. package/mcp/runStdio.js +2 -0
  167. package/mcp/subtreeTools.js +184 -0
  168. package/mcp/tryItTools.js +202 -0
  169. package/package.json +18 -9
  170. package/public/.DS_Store +0 -0
  171. package/public/pico-engine-ui.css +1 -1
  172. package/public/pico-engine-ui.js +26 -25
  173. package/src/bundledKrl.ts +118 -12
  174. package/src/cli.ts +8 -2
  175. package/src/engineConfig.ts +33 -2
  176. package/src/identity/portableMove.ts +6 -1
  177. package/src/index.ts +469 -422
  178. package/src/internalAccess.ts +127 -0
  179. package/src/oauth/OAuthService.ts +243 -11
  180. package/src/oauth/acg.ts +289 -25
  181. package/src/oauth/cimd.ts +508 -0
  182. package/src/oauth/discovery.ts +233 -0
  183. package/src/runMcp.ts +3 -1
  184. package/src/server.ts +266 -51
  185. package/src/subtreeWrangler.ts +17 -5
  186. package/src/uiChannelPolicies.ts +2 -0
@@ -0,0 +1,297 @@
1
+ # Relationships
2
+
3
+ *For KRL developers and engine operators. Engine 1.6 and later (DID-based relationships); the classic ECI path is still supported. Ruleset: `io.picolabs.subscription`, installed on every pico.*
4
+
5
+ A relationship is a pairwise connection between two picos. Before engine 1.6.2, relationships were called subscriptions. Relationships are formed with `wrangler:relationship` (or the older `wrangler:subscription`). Their state lives in `io.picolabs.subscription`, which keeps that name for compatibility.
6
+
7
+ New rulesets can load it under the new name:
8
+
9
+ ```krl
10
+ use module io.picolabs.subscription alias relationship
11
+ ```
12
+
13
+ | Prefer (1.6.2 and later) | Still works |
14
+ |--------------------------|-------------|
15
+ | `wrangler:relationship` | `wrangler:subscription` |
16
+ | `relationship:established()` (module alias) | `subscription:established()` |
17
+ | The **Relationships** tab | The `/subscriptions` URL |
18
+
19
+ ## What is a relationship?
20
+
21
+ The two picos in a relationship may be in the same mesh, in different meshes, or on different engines. A parent and its children talk through family channels and don't need one. Relationships are for picos that aren't related that way, such as your pico and a community pico, two peer meshes, or a service and its clients, so they can exchange events and queries under explicit channel policy.
22
+
23
+ Each side keeps a relationship record: who the other party is, how to reach it, and which local channel (`Rx`) enforces what the other party may do. A relationship goes from outbound pending (on the side that asked) and inbound pending (on the side asked) to established, when both sides agree.
24
+
25
+ ## Identity: three identifiers
26
+
27
+ Since engine 1.6, relationships use two kinds of DID as well as ECIs:
28
+
29
+ | Identifier | Role | When you use it |
30
+ |------------|------|-----------------|
31
+ | `did:webvh` | The pico's portable identity: who the actor is | To start a DID-based relationship (`target_did`); public intro |
32
+ | `did:peer` | The relationship's private identity, for this pair | After the introduction is approved, for ongoing encrypted traffic |
33
+ | ECI (channel id) | The local policy gate on this engine | The `Rx` channel on each pico; the other side's `Tx` ECI in classic relationships |
34
+
35
+ New relationships use DIDs; ECIs are for existing applications. Use the `did:webvh` for introductions and `did:peer` for everything after. Don't start a new relationship with a peer DID or a well-known ECI.
36
+
37
+ Every pico publishes its `did:webvh` at `GET /picos/{picoId}/did.jsonl`. In KRL it's `wrangler:myDid()`; in the developer UI, it's in the **Relationships** tab's **Identity** panel. To be reached across meshes or engines by its DID, a pico needs **public intro** turned on.
38
+
39
+ ## The lifecycle
40
+
41
+ | State | The side that asked | The side asked |
42
+ |-------|---------------------|----------------|
43
+ | Outbound pending | Waiting for the other side | — |
44
+ | Inbound pending | — | Approve or ignore |
45
+ | Established | Connected | Connected |
46
+
47
+ ## DID-based relationships (recommended)
48
+
49
+ DID-based relationships are the default for new work. They form with an introduction handshake, and the established relationship stores `Tx_did` and `Rx_did` instead of the other side's ECI.
50
+
51
+ ### Forming one
52
+
53
+ The side that asks raises `wrangler:relationship`:
54
+
55
+ | Attribute | Value |
56
+ |-----------|-------|
57
+ | `layer2` | `true` |
58
+ | `target_did` | The other pico's `did:webvh` (`wrangler:myDid()` there, or from its UI) |
59
+ | `name` | Optional label, shown in the established list |
60
+ | `Tx_role`, `Rx_role` | Optional roles: the other side's and this side's |
61
+ | `channel_type` | Usually `Tx_Rx` |
62
+
63
+ The side asked approves with `wrangler:pending_relationship_approval`, or by an auto-accept rule (see [Accepting relationship requests](/developing/accepting-relationship-requests)).
64
+
65
+ Don't pass `wellKnown_Tx` on a DID-based request, or a `did:peer`: the engine makes the pairwise DIDs during the introduction.
66
+
67
+ | You have the other pico's… | DID-based request | Classic request |
68
+ |-----------------------------|-------------------|-----------------|
69
+ | `did:webvh` | ✅ `target_did` | ❌ |
70
+ | `wellKnown_Rx` ECI | ❌ | ✅ `wellKnown_Tx` |
71
+ | `did:peer` | ❌ | ❌ |
72
+
73
+ On the same engine, the engine resolves the `did:webvh` locally and runs the introduction without HTTP.
74
+
75
+ ### The established relationship
76
+
77
+ | Field | Meaning |
78
+ |-------|---------|
79
+ | `Id` | The relationship's id, the same on both sides |
80
+ | `name` | Its label |
81
+ | `layer2` | `true` |
82
+ | `Tx_did` | The other side's `did:peer` |
83
+ | `Rx_did` | This side's `did:peer` for this relationship |
84
+ | `Rx` | This side's ECI: where policy is enforced |
85
+ | `Tx_host` | Set when the other pico is on another engine |
86
+
87
+ ### Sending queries and events
88
+
89
+ Query the other pico by DID, or through the relationship:
90
+
91
+ ```krl
92
+ // By DID: wrangler finds the established relationship
93
+ wrangler:picoQuery(other_did, "io.picolabs.wrangler", "id", {})
94
+
95
+ // By relationship Id
96
+ relationship:queryOnSub(sub_id, "io.picolabs.wrangler", "id", {})
97
+ ```
98
+
99
+ Send an event by DID, or with the relationship record:
100
+
101
+ ```krl
102
+ event:send({"did": other_did, "domain": "myapp", "type": "ping", "attrs": {}})
103
+ event:send({"sub": bus, "domain": "myapp", "type": "ping", "attrs": {}})
104
+ ```
105
+
106
+ For a DID-based relationship, the engine delivers locally when both picos are in the same mesh on this engine, and otherwise over DIDComm to the other pico's ingress.
107
+
108
+ ## How traffic is routed
109
+
110
+ How a query or event reaches the other pico depends on three things: whether the relationship is DID-based or classic, whether the two picos are in the same mesh (the same passkey root on one engine), and whether the other pico is on this engine. Wherever it comes from, the other side's access is checked on this side's `Rx` channel.
111
+
112
+ | Relationship | Kind | Transport | Policy |
113
+ |--------------|------|-----------|--------|
114
+ | Parent and child | None (family) | Local | Family channel |
115
+ | Same mesh, same engine | DID-based or classic | Local | The relationship's `Rx` channel |
116
+ | Different meshes, same engine | DID-based | DIDComm to the ingress | The relationship's `Rx` channel |
117
+ | Different engines | DID-based | DIDComm to the other engine | The relationship's `Rx` channel |
118
+ | Classic | Classic | HTTP or `event:send` to `Tx` | `Tx` and `Rx` policies |
119
+
120
+ OAuth integrators are a separate path: HTTP to `/sky/*` with a bearer token, not a relationship.
121
+
122
+ To change what the other side may do, edit the `Rx` channel's policy on the **Channels** tab, or expand the relationship on the **Relationships** tab and follow its link to the channel.
123
+
124
+ ## Across engines
125
+
126
+ - Each engine needs a stable address that the other can reach, `PICO_ENGINE_BASE_URL`. It is built into each pico's `did:webvh` when the pico is created.
127
+ - The side asked (often a root pico) has public intro on. Root picos default to on; child picos to off.
128
+ - The side that asks uses the other's `did:webvh` as `target_did`.
129
+
130
+ The handshake is the same as on one engine, but the introduction, its response, and the traffic after use encrypted DIDComm to `POST {peerBase}/sky/event/{ingressEci}/none/dido/didcomm_message`.
131
+
132
+ ### Two engines on one machine
133
+
134
+ ```sh
135
+ # Terminal 1
136
+ PICO_ENGINE_HOME=/tmp/pico-engine-a PORT=3001 npm start
137
+ # Terminal 2
138
+ PICO_ENGINE_HOME=/tmp/pico-engine-b PORT=3002 npm start
139
+ ```
140
+
141
+ 1. Register a passkey on both developer UIs.
142
+ 2. On engine B, **Relationships** → **Identity**: copy the `did:webvh`.
143
+ 3. On engine A, **Relationships** → **New relationship** (DID-based): paste B's DID and submit.
144
+ 4. On B, under **Inbound pending**, approve it.
145
+ 5. On A, the established relationship shows `Tx_did`, `Rx_did`, and `Tx_host`.
146
+
147
+ ### Debugging
148
+
149
+ | Symptom | Check |
150
+ |---------|-------|
151
+ | The introduction never arrives | Public intro on the side asked; ports and firewalls |
152
+ | DID resolution failed | Fetch `{base}/picos/{id}/did.jsonl` |
153
+ | 401 on DIDComm | Approve the relationship again; check that the ingress channel exists |
154
+
155
+ ## Classic (ECI-based) relationships
156
+
157
+ The original relationship model is still fully supported for existing rulesets and tutorials:
158
+
159
+ - The side asked has a well-known channel, `wellKnown_Rx` (shown in the **Identity** panel).
160
+ - The side that asks raises `wrangler:relationship` with `wellKnown_Tx` set to that ECI, and no `layer2`.
161
+ - The established relationship has `Tx` and `Rx` ECIs, and `layer2` is false.
162
+
163
+ The [Two picos talking](/cookbook/two_picos/) and [Collection](/cookbook/collection/) demos use classic relationships.
164
+
165
+ ## The Relationships tab
166
+
167
+ The developer UI's **Relationships** tab manages a pico's relationships:
168
+
169
+ - **Identity**: the pico's `did:webvh`, with a copy button; the classic `wellKnown_Rx` ECI; and the **Public intro** checkbox.
170
+ - **Established**, **Inbound pending**, and **Outbound pending** lists. Expand a row to see its DIDs and `Rx` policy, send a test event, approve, cancel, or delete it.
171
+ - **New relationship**: DID-based or classic, with `target_did` or `wellKnown_Tx`, `name`, `Rx_role`, `Tx_role`, `channel_type`, and an optional password.
172
+
173
+ Give relationships names, so the lists stay readable. The `Id` is still shown, for debugging.
174
+
175
+ ## The KRL API
176
+
177
+ Relationships live in two rulesets on every pico. `io.picolabs.subscription` keeps the relationship records and runs most of the lifecycle. `io.picolabs.wrangler` has the identity functions and `picoQuery`. You raise `wrangler` events to create, approve, and cancel relationships, and query `io.picolabs.subscription` for their state.
178
+
179
+ ### Identity
180
+
181
+ | Function or event | Purpose |
182
+ |-------------------|---------|
183
+ | `wrangler:myDid()` | This pico's `did:webvh`: give it to the other side as its `target_did` |
184
+ | `wrangler:publicIntro()` | Whether this pico accepts introductions on its DID |
185
+ | `wrangler:set_public_intro` event, with `enabled` | Turn public intro on or off |
186
+ | `wrangler:callerDid()` | On an incoming cross-pico event, the sender's `did:webvh`, when the engine has it |
187
+
188
+ ### Reading relationships
189
+
190
+ | Function | Returns |
191
+ |----------|---------|
192
+ | `relationship:established()` | The established relationships |
193
+ | `relationship:established("Tx_role", "owner")` | Only those whose field matches (any field works) |
194
+ | `relationship:inbound()` | Requests waiting for this pico's approval |
195
+ | `relationship:outbound()` | Requests waiting for the other side |
196
+ | `relationship:wellKnown_Rx()` | The well-known channel, for classic relationships |
197
+ | `relationship:autoAcceptConfig()` | The auto-accept rules |
198
+
199
+ Each relationship is a map with `Id`, `name`, `Tx_role`, `Rx_role`, the local `Rx`, and either `Tx_did` and `Rx_did` (DID-based) or `Tx` and `Tx_host` (classic).
200
+
201
+ ### Creating a relationship
202
+
203
+ DID-based:
204
+
205
+ ```krl
206
+ raise wrangler event "relationship" attributes {
207
+ "layer2": true,
208
+ "target_did": other_did,
209
+ "name": "battery-monitor",
210
+ "Rx_role": "sensor",
211
+ "Tx_role": "controller",
212
+ "channel_type": "Tx_Rx"
213
+ }
214
+ ```
215
+
216
+ Classic:
217
+
218
+ ```krl
219
+ raise wrangler event "relationship" attributes {
220
+ "wellKnown_Tx": other_well_known_eci,
221
+ "name": "legacy-link",
222
+ "Rx_role": "client",
223
+ "Tx_role": "server"
224
+ }
225
+ ```
226
+
227
+ Either takes an optional `password`, if the other side's auto-accept configuration uses one. The relationship ruleset creates the local `Rx` channel, records the outbound request, and runs the handshake.
228
+
229
+ ### Approving, rejecting, and canceling
230
+
231
+ | Event | When | Key attributes |
232
+ |-------|------|----------------|
233
+ | `wrangler:pending_relationship_approval` | Accept an inbound request | `Id` (or `Rx` or `Tx`) |
234
+ | `wrangler:inbound_rejection` | Decline an inbound request | `Id` |
235
+ | `wrangler:outbound_cancellation` | Withdraw an outbound request | `Id` |
236
+ | `wrangler:relationship_cancellation` | End an established relationship | `Id` |
237
+
238
+ Each raises companion events that other rulesets can select, such as `wrangler:relationship_added` and `wrangler:relationship_removed` (and their older names, `subscription_added` and `subscription_removed`).
239
+
240
+ ### Talking to the other pico
241
+
242
+ 1. `wrangler:picoQuery(target, rid, name, args)`, where the target is a `did:webvh`, a `did:peer`, or a classic `Tx` ECI. The engine finds the established relationship and routes the query.
243
+ 2. `relationship:queryOnSub(Id, rid, name, args)`, by relationship `Id`.
244
+ 3. `event:send({"did": ..., ...})` or `event:send({"sub": relationship, ...})`.
245
+ 4. To several relationships at once, raise `wrangler:send_event_on_subs` with a `subID`, or a `Tx_role` or `Rx_role`, and the `domain`, `type`, and `attrs` to send.
246
+
247
+ ### Quick reference
248
+
249
+ | Goal | API |
250
+ |------|-----|
251
+ | This pico's portable DID | `wrangler:myDid()` |
252
+ | List established relationships | `relationship:established()` |
253
+ | Start a DID-based relationship | `wrangler:relationship` with `layer2` and `target_did` |
254
+ | Start a classic relationship | `wrangler:relationship` with `wellKnown_Tx` |
255
+ | Approve a request | `wrangler:pending_relationship_approval` with `Id` |
256
+ | End a relationship | `wrangler:relationship_cancellation` with `Id` |
257
+ | Query the other pico | `wrangler:picoQuery(did, rid, name, args)` or `relationship:queryOnSub(...)` |
258
+ | Send it an event | `event:send({"did": ...})` or `event:send({"sub": relationship, ...})` |
259
+
260
+ Authorization is the same for both kinds: the other side's access is enforced on your `Rx` channel's event and query policy. DID-based relationships change how messages are addressed, not who is allowed.
261
+
262
+ ## Public intro
263
+
264
+ Public intro decides whether a pico accepts an unsolicited introduction: someone starting a DID-based relationship by sending an introduction to its `did:webvh`, without a well-known channel. That matters across engines and meshes, where the asking side may know only the DID. With public intro off, the engine drops the introduction, and it never reaches the inbound pending list.
265
+
266
+ It answers "may strangers introduce themselves by DID?" It doesn't replace approval: after an introduction arrives, you still approve it (unless auto-accept matches), and the `Rx` policy still governs what the other pico may do.
267
+
268
+ Root picos default to on, so other engines can reach your mesh's root by DID. Child picos default to off.
269
+
270
+ | How | What to do |
271
+ |-----|------------|
272
+ | Developer UI | **Relationships** → **Identity** → **Public intro** |
273
+ | Query | `wrangler:publicIntro()` |
274
+ | Event | `raise wrangler event "set_public_intro" attributes {"enabled": true}` |
275
+
276
+ Leave it on for root picos that should receive requests from other engines, and for picos that partners will reach by DID. Turn it off for picos that should be reached only through their parent or a classic well-known channel, or that you don't want to be discoverable by DID.
277
+
278
+ Once a DID-based relationship is established, public intro can be turned off: the relationship uses its `did:peer` from then on.
279
+
280
+ ## Roles and policy
281
+
282
+ `Tx_role` and `Rx_role` describe each side's part, such as `controller` or `member`. They label relationships; they don't prove anything. Authorization is the local `Rx` channel's policy, as it always was. Frameworks such as Manifold confer rights through relationships plus channel policy; DID-based relationships change how you address the other pico, not how policy works.
283
+
284
+ ## Not yet implemented
285
+
286
+ - Migrating classic relationships to DID-based ones automatically (create new relationships instead)
287
+ - Authorization based on verifiable credentials over relationships
288
+ - `did:peer:4` (engine 1.6 uses `num_algo` 2)
289
+
290
+ Moving a pico to another engine is implemented: its `did:webvh` and its DID-based relationships move with it. See [Portable subtrees](/wrangler/portable-subtree).
291
+
292
+ ## Related pages
293
+
294
+ - [Engine 1.6 release notes](/release/1.6)
295
+ - [Managing channels](/wrangler/channels): `Rx` policy
296
+ - [Identity libraries](/design/pico-identity-libraries) and [relationships design](/design/pico-relationships)
297
+ - [SKY over DIDComm](/design/sky-didcomm-protocol)
@@ -0,0 +1,253 @@
1
+ # The wrangler ruleset
2
+
3
+ `io.picolabs.wrangler` manages a pico's life cycle: its child picos, the rulesets installed in it, and its channels. It also has the functions rulesets use to learn about the pico and to query other picos. For every event and function, see the [API reference](/rulesets/io.picolabs.wrangler). For what Wrangler is as a whole, see [Wrangler](/wrangler/).
4
+
5
+ The examples assume the ruleset uses Wrangler as a module:
6
+
7
+ ```krl
8
+ meta {
9
+ use module io.picolabs.wrangler alias wrangler
10
+ }
11
+ ```
12
+
13
+ ## Pico life cycle
14
+
15
+ The engine creates the first pico, the root pico, when it starts for the first time. Any pico can create child picos, and a pico can delete its children. The root pico can't be deleted.
16
+
17
+ ### Creating a child pico
18
+
19
+ Raise `wrangler:new_child_request` in the pico that will be the parent, with a `name` and, optionally, a `backgroundColor` for the developer UI:
20
+
21
+ ```krl
22
+ raise wrangler event "new_child_request" attributes {"name": "Kitchen", "task_id": "42"}
23
+ ```
24
+
25
+ Wrangler's `createChild` rule creates the child pico with the developer UI ruleset and Wrangler installed, then sends the child three events in order:
26
+
27
+ 1. `engine_ui:setup`: the developer UI ruleset creates the channel the UI uses for this pico.
28
+ 2. `wrangler:pico_created`: Wrangler on the child records its name, parent, and id, and installs `io.picolabs.pds` and `io.picolabs.subscription`.
29
+ 3. `engine_ui:box`: the UI ruleset stores the name and color the developer UI shows.
30
+
31
+ Then, in the parent, Wrangler raises `wrangler:new_child_created`, with the child's family channel (`eci`) and its UI channel (`uiEci`). When the child has finished setting up, it raises `wrangler:pico_initialized` for itself and sends `wrangler:child_initialized` to its parent.
32
+
33
+ Any other attributes on the request (`task_id` above) are passed through: they arrive on the child with `pico_created`, and come back to the parent with `new_child_created` and `child_initialized`. That's how a parent tells its new children apart. The parent selects `child_initialized` with a `where` on its own attribute, and gets the child's `eci` to send it more events, such as an `install_ruleset_request`. See the [Child pico tasks](/cookbook/child_tasks/) demo.
34
+
35
+ `new_child_request` also takes an optional `policyCeiling`: a map that limits the channel policies the child may ever have. It can't exceed the parent's own ceiling.
36
+
37
+ The developer UI's **About** tab creates children the same way: it sends `engine_ui:new`, which raises `wrangler:new_child_request`.
38
+
39
+ ### While a pico exists
40
+
41
+ | Function | Returns |
42
+ |----------|---------|
43
+ | `parent_eci()` | The family channel this pico uses to reach its parent. `null` on the root pico |
44
+ | `children()` | An array of maps, one per child: `{"eci": ..., "name": ..., "parent_eci": ...}`. `eci` is this pico's family channel to the child |
45
+ | `myself()` | `{"name": ..., "id": ..., "eci": ...}` for this pico |
46
+ | `name()`, `id()` | This pico's name and id |
47
+ | `myDid()`, `publicIntro()` | This pico's portable `did:webvh`, and whether it accepts introductions on it. See [Relationships](/wrangler/relationships) |
48
+
49
+ `wrangler:name_changed` with a `name` changes the pico's name.
50
+
51
+ ### Deleting a pico
52
+
53
+ A pico can only be deleted by its parent. A rule in the parent raises `wrangler:child_deletion_request` with `eci` set to the child's family channel, from `children()`:
54
+
55
+ ```krl
56
+ raise wrangler event "child_deletion_request" attributes {"eci": child{"eci"}}
57
+ ```
58
+
59
+ The child and all its descendants are deleted, and Wrangler raises `wrangler:child_deleted` in the parent with the same attributes.
60
+
61
+ A pico can ask to be deleted by raising `wrangler:ready_for_deletion`. Wrangler sends its parent the `child_deletion_request` for it. Finish any work in progress and release what the pico holds first.
62
+
63
+ There's no undo. When a pico is deleted, its state, channels, and relationships are gone.
64
+
65
+ The root pico can't be deleted. The only way to remove every pico, the root included, is to stop the engine and remove its database, `db/` in the engine's home directory (`~/.pico-engine` by default). That also removes passkey registrations and every pico's identity. The next start creates a new root pico, and the first visit registers a new passkey. Use it only as a last resort.
66
+
67
+ ### Life cycle events
68
+
69
+ Events Wrangler selects:
70
+
71
+ | Event | Sent by | Attributes |
72
+ |-------|---------|------------|
73
+ | `wrangler:new_child_request` | The developer UI or a ruleset | `name`; optional `backgroundColor`, `policyCeiling`, and any others to pass through |
74
+ | `wrangler:pico_created` | Wrangler, to the new child (not for rulesets) | Those of the request |
75
+ | `wrangler:child_deletion_request` | The developer UI, a ruleset, or Wrangler on a child | `eci`, the family channel to the child |
76
+ | `wrangler:ready_for_deletion` | A ruleset on the pico to delete | None |
77
+ | `wrangler:name_changed` | A ruleset | `name` |
78
+
79
+ Events Wrangler raises:
80
+
81
+ | Event | Where | Attributes |
82
+ |-------|-------|------------|
83
+ | `wrangler:new_child_created` | In the parent | Those of the request, plus the child's `eci` and `uiEci` |
84
+ | `wrangler:pico_initialized` | In the child | Those of the request, plus the child's `eci` |
85
+ | `wrangler:child_initialized` | Sent from the child to the parent | Those of the request, plus `eci` |
86
+ | `wrangler:child_deleted` | In the parent | Those of the deletion request |
87
+
88
+ ## Channels
89
+
90
+ A pico can have as many channels as it needs, and only a pico can create and delete its own. Channels and their policies are explained in [Managing channels](/wrangler/channels). This section is the Wrangler API for them.
91
+
92
+ ### Creating a channel
93
+
94
+ `createChannel(tags, eventPolicy, queryPolicy, mcpPolicy, rawBody)` is an action that creates a channel and returns it. `mcpPolicy` is optional. Leave it out and the channel is not exposed to MCP. `rawBody` is optional. Pass `true` and an HTTP event on this channel keeps its exact body for `event:raw_body()`. Leave it out and the body is not kept. Its `id` is the channel's ECI:
95
+
96
+ ```krl
97
+ rule initialize {
98
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
99
+ if ent:app_eci.isnull() then
100
+ wrangler:createChannel(
101
+ ["myapp", "app"],
102
+ {"allow": [{"domain": "myapp", "name": "*"}], "deny": []},
103
+ {"allow": [{"rid": meta:rid, "name": "*"}], "deny": []}
104
+ ) setting(channel)
105
+ fired {
106
+ ent:app_eci := channel{"id"}
107
+ }
108
+ }
109
+ ```
110
+
111
+ Or raise `wrangler:new_channel_request` with `tags`, `eventPolicy`, and `queryPolicy`. When the channel exists, Wrangler raises `wrangler:channel_created` with the request's attributes plus `channel`, the new channel. Add an attribute of your own to recognize your channel when the event arrives:
112
+
113
+ ```krl
114
+ rule ask_for_channel {
115
+ select when myapp channel_needed
116
+ always {
117
+ raise wrangler event "new_channel_request" attributes {
118
+ "tags": ["myapp", "app"],
119
+ "eventPolicy": {"allow": [{"domain": "myapp", "name": "*"}], "deny": []},
120
+ "queryPolicy": {"allow": [{"rid": meta:rid, "name": "*"}], "deny": []},
121
+ "for_rid": meta:rid
122
+ }
123
+ }
124
+ }
125
+
126
+ rule remember_channel {
127
+ select when wrangler channel_created where event:attr("for_rid") == meta:rid
128
+ always {
129
+ ent:app_eci := event:attr("channel"){"id"}
130
+ }
131
+ }
132
+ ```
133
+
134
+ ### Finding channels
135
+
136
+ `channels()` returns all of this pico's channels. `channels(tags)` returns the channels whose tags are exactly those, in any order and case. The tags can be an array or a comma-separated string. This finds the family channel by which the pico's parent knows it:
137
+
138
+ ```krl
139
+ my_child_eci = wrangler:channels("system,child").head(){"id"}
140
+ ```
141
+
142
+ `discoveryChannel()` returns the pico's `discovery` channel, which every pico has, for finding out what a pico can do.
143
+
144
+ ### Updating a channel
145
+
146
+ `updateChannel(eci, tags, eventPolicy, queryPolicy)` replaces a channel's tags and policies and keeps its ECI, so anything that already uses the channel keeps working. Pass the whole policy, not just the change. Or raise `wrangler:channel_update_request` with the same four attributes, and Wrangler raises `wrangler:channel_updated` with the updated `channel`.
147
+
148
+ ### Deleting a channel
149
+
150
+ `deleteChannel(eci)` deletes a channel. Or raise `wrangler:channel_deletion_request` with the `eci`, and Wrangler raises `wrangler:channel_deleted` with the request's attributes.
151
+
152
+ ### Rotating a channel
153
+
154
+ If a channel's ECI is being misused, replace it: make a channel with the same tags and policies, give the new ECI to the parties who should have it, and delete the old one. The old ECI then stops working.
155
+
156
+ ```krl
157
+ rule rotate_channel {
158
+ select when myapp rotation_needed
159
+ pre {
160
+ old = wrangler:channels(["myapp", "app"]).head()
161
+ }
162
+ if old then every {
163
+ wrangler:createChannel(old{"tags"}, old{"eventPolicy"}, old{"queryPolicy"}) setting(channel)
164
+ wrangler:deleteChannel(old{"id"})
165
+ send_directive("rotated", {"eci": channel{"id"}})
166
+ }
167
+ }
168
+ ```
169
+
170
+ To change what a channel allows without changing its ECI, update it instead. Pico views have a helper for rotating an app channel, `ui:rotate_app_channel(tags)`; see [Pico views](/pico-views).
171
+
172
+ ## Rulesets
173
+
174
+ A pico's behavior and state come from its rulesets. A ruleset is KRL source at a URL: `https://`, `file://` on the engine's machine, or the engine's own `/krl/` and `/krl/demos/` paths.
175
+
176
+ ### Installing a ruleset
177
+
178
+ Raise `wrangler:install_ruleset_request` in one of two forms:
179
+
180
+ - With `url`: install the KRL at that URL.
181
+ - With `absoluteURL` and `rid`: install `<rid>.krl` from the same folder as `absoluteURL`. Pass `meta:rulesetURI` to install a ruleset that sits next to the one asking. An app of several rulesets can be installed this way by a single bootstrap ruleset; see the [Bootstrap and channels](/cookbook/bootstrap/) demo.
182
+
183
+ Either form takes an optional `config` map, which the installed ruleset reads as `meta:rulesetConfig`, and others can read with `wrangler:rulesetConfig(rid)`.
184
+
185
+ The engine fetches and compiles the source before installing it. If it doesn't compile, Wrangler raises `wrangler:ruleset_install_failed` with the `url`, `rid`, and the compiler's `errors` and `warnings`. If it installs, and the ruleset wasn't already on this pico, Wrangler raises `wrangler:ruleset_installed` with `rids`, an array holding the installed rid. Installing a ruleset that is already installed updates it to the latest source without raising `ruleset_installed`.
186
+
187
+ `ruleset_installed` is the first event a newly installed ruleset sees, so it's the place to set up state. Every ruleset on the pico sees the event when any ruleset is installed, so select only your own:
188
+
189
+ ```krl
190
+ rule initialize_state {
191
+ select when wrangler ruleset_installed where event:attr("rids") >< meta:rid
192
+ always {
193
+ ent:items := {}
194
+ }
195
+ }
196
+ ```
197
+
198
+ ### Information about installed rulesets
199
+
200
+ | Function | Returns |
201
+ |----------|---------|
202
+ | `installedRIDs()` | The rids of the rulesets on this pico |
203
+ | `rulesetMeta(rid)` | The ruleset's `meta` block: name, description, author, what it shares, and so on |
204
+ | `rulesetConfig(rid)` | The configuration it was installed with |
205
+ | `rulesetSchema(rid)` | Its schema: the events its documented rules select and the functions it documents and shares |
206
+ | `picoSchema()` | The schemas of all the pico's rulesets, merged |
207
+ | `channelSchema(eci)` | What a channel's policy allows, from the pico's schema |
208
+ | `rulesetWarnings(rid)` | The compiler's warnings for it |
209
+
210
+ When the set of rulesets on a pico changes, Wrangler raises `wrangler:schema_updated`.
211
+
212
+ ### Flushing
213
+
214
+ When a ruleset's source changes, it has to be flushed: fetched and compiled again. Flush one on the **Rulesets** tab of the developer UI. From KRL, raise `wrangler:rulesets_need_flushing` to flush every ruleset on this pico. Wrangler raises `wrangler:rulesets_flushed` when it's done.
215
+
216
+ The engine compiles each URL once, so a flush affects every pico that installed a ruleset from that URL. Flushing doesn't raise `ruleset_installed` again, so rules that run on install don't run.
217
+
218
+ ### Uninstalling
219
+
220
+ Raise `wrangler:uninstall_ruleset_request` with a `rid`. Wrangler raises `wrangler:ruleset_uninstalled` with the same attributes. A ruleset that another installed ruleset uses as a module can't be uninstalled.
221
+
222
+ ## Querying other picos
223
+
224
+ `picoQuery(eci, rid, name, args)` calls a function another pico shares and returns its value:
225
+
226
+ ```krl
227
+ rule ask {
228
+ select when myapp question_asked
229
+ pre {
230
+ answer = wrangler:picoQuery(other_eci, "my.ruleset.id", "myFunction", {"arg1": "a"})
231
+ }
232
+ if answer{"error"}.isnull() then noop()
233
+ fired {
234
+ ent:answer := answer
235
+ }
236
+ }
237
+ ```
238
+
239
+ The target can be an ECI or a DID: a pico's `did:webvh`, or the `did:peer` of an established relationship. On the same engine, `picoQuery` calls the other pico directly. Otherwise it goes over HTTP, or over DIDComm for a DID.
240
+
241
+ On failure it returns a map with `error`, and for HTTP, `httpStatus` and the other pico's error as `picoQueryError`, `picoQueryErrorMsg`, and `picoQueryReturnValue`.
242
+
243
+ Optional parameters, for a pico on another engine:
244
+
245
+ | Parameter | Meaning |
246
+ |-----------|---------|
247
+ | `_host` | The other engine, with protocol and port, such as `https://picos.example.com`. Defaults to this engine (`meta:host`), and then the query doesn't use HTTP |
248
+ | `_path` | The path before the ECI. Default `/sky/cloud/` |
249
+ | `_root_url` | The whole URL before the ECI, instead of `_host` and `_path` |
250
+
251
+ A pico can't query itself: `picoQuery` returns an error ("Pico should not query itself"). A query waits for its answer, so avoid two picos that query each other at the same time. See [Querying another pico](/developing/querying-another-pico).
252
+
253
+ `skyQuery`, the older version, is still there for old rulesets. It always uses HTTP, which can't use family channels. It takes the same parameters in the same order, so switching to `picoQuery` is a rename.
@@ -0,0 +1,60 @@
1
+ # Pico views: io.picolabs.xmlui
2
+
3
+ *Optional. Not installed by default. Install it on each pico that serves pages.*
4
+
5
+ `io.picolabs.xmlui` lets a pico serve web pages built with [XMLUI](https://xmlui.org). A ruleset function tagged `@view` is a page, at `/ui/<eci>/<rid>/`. One tagged `@component` is a reusable part that pages use as a tag. This ruleset supplies the app shell and navigation, the helpers a view uses to read and write the pico, and shared components: `PicoTheme`, `PicoSettings`, `PicoThemeField`, and `PicoAccessTokenField`.
6
+
7
+ ## Install it
8
+
9
+ From a pico's **Rulesets** tab, install it from the engine:
10
+
11
+ ```
12
+ http://localhost:3000/krl/io.picolabs.xmlui.krl
13
+ ```
14
+
15
+ Or from a ruleset, the way the Try It! demos' bootstraps do:
16
+
17
+ ```krl
18
+ raise wrangler event "install_ruleset_request" attributes {"url": meta:host + "/krl/io.picolabs.xmlui.krl"}
19
+ ```
20
+
21
+ Install it before the rulesets that use it as a module.
22
+
23
+ ## Use it
24
+
25
+ ```krl
26
+ meta {
27
+ use module io.picolabs.xmlui alias ui
28
+ shares hello
29
+ }
30
+ global {
31
+ /**
32
+ * A greeting.
33
+ * @view "Hello"
34
+ */
35
+ hello = function() {
36
+ <<
37
+ <Component name="Hello">
38
+ <Text>Hello from #{meta:rid}</Text>
39
+ </Component>
40
+ >>
41
+ }
42
+ }
43
+ ```
44
+
45
+ Its main helpers:
46
+
47
+ | Helper | Use |
48
+ |--------|-----|
49
+ | `ui:query_url(name, rid, eci)`, `ui:event_url(domain, type, eci)` | URLs for a page's `DataSource` and `APICall` |
50
+ | `ui:query(id, name, opts)`, `ui:event(id, domain, type, opts)` | The `DataSource` and `APICall` markup itself. Pass `{"rid": meta:rid}` to `ui:query` |
51
+ | `ui:create_app_channel(tags, domains, queries, rid)` | A channel for the app: events in `domains`, its queries, and what the page shell needs |
52
+ | `ui:rotate_app_channel(tags)` | A new channel like the newest one with those tags |
53
+ | `ui:app_url(tags, rid)` | The page's URL on the newest channel with those tags |
54
+
55
+ When a pico's set of rulesets changes, this ruleset adds any missing component queries to the channels that serve pages.
56
+
57
+ ## Read more
58
+
59
+ - [Pico views](/pico-views): the full guide, including channels, components, and OAuth meshes.
60
+ - The [Pico views demos](/cookbook/xmlui/), and every Try It! demo, which all use it.