pico-engine 1.9.5 → 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 (126) hide show
  1. package/README.md +11 -5
  2. package/demos/bootstrap/com.example.visitors.bootstrap.krl +9 -5
  3. package/demos/child_tasks/com.example.task_runner.bootstrap.krl +10 -7
  4. package/demos/echo/com.example.echo.bootstrap.krl +10 -7
  5. package/demos/guard_rules/com.example.archive.bootstrap.krl +10 -7
  6. package/demos/json_query/README.md +11 -0
  7. package/demos/json_query/com.example.json_query.bootstrap.krl +84 -0
  8. package/demos/json_query/com.example.json_query.krl +162 -0
  9. package/demos/json_query/try-it.md +5 -0
  10. package/demos/kblog/com.example.kblog.bootstrap.krl +10 -7
  11. package/demos/layered_rulesets/com.example.invitations.bootstrap.krl +10 -7
  12. package/demos/score_tracker/com.example.score_tracker.bootstrap.krl +10 -7
  13. package/demos/secrets/com.example.notifier.bootstrap.krl +10 -7
  14. package/demos/try-it-order.json +1 -1
  15. package/demos/two_picos/com.example.two_picos.bootstrap.krl +5 -2
  16. package/demos/xmlui/com.example.thermostat.bootstrap.krl +10 -7
  17. package/dist/cli.js +5 -1
  18. package/dist/engineConfig.js +1 -1
  19. package/dist/identity/portableMove.js +5 -1
  20. package/dist/index.js +44 -12
  21. package/dist/internalAccess.js +110 -0
  22. package/dist/oauth/OAuthService.js +172 -10
  23. package/dist/oauth/acg.js +194 -24
  24. package/dist/oauth/cimd.js +381 -0
  25. package/dist/oauth/discovery.js +175 -0
  26. package/dist/runMcp.js +1 -1
  27. package/dist/server.js +197 -48
  28. package/dist/subtreeWrangler.js +8 -5
  29. package/dist/uiChannelPolicies.js +2 -0
  30. package/krl/io.picolabs.pds.krl +109 -21
  31. package/krl/io.picolabs.pico-engine-ui.krl +13 -7
  32. package/krl/io.picolabs.wrangler.krl +21 -9
  33. package/mcp/devResources.js +52 -0
  34. package/mcp/devTools.js +40 -9
  35. package/mcp/docs/CLAUDE.md +3 -2
  36. package/mcp/docs/cookbook/README.md +23 -0
  37. package/mcp/docs/cookbook/bootstrap/README.md +23 -0
  38. package/mcp/docs/cookbook/bootstrap/instructions.md +75 -0
  39. package/mcp/docs/cookbook/child_tasks/README.md +20 -0
  40. package/mcp/docs/cookbook/child_tasks/instructions.md +60 -0
  41. package/mcp/docs/cookbook/collection/README.md +21 -0
  42. package/mcp/docs/cookbook/collection/instructions.md +93 -0
  43. package/mcp/docs/cookbook/echo/README.md +19 -0
  44. package/mcp/docs/cookbook/echo/instructions.md +59 -0
  45. package/mcp/docs/cookbook/guard_rules/README.md +22 -0
  46. package/mcp/docs/cookbook/guard_rules/instructions.md +73 -0
  47. package/mcp/docs/cookbook/json_query/README.md +26 -0
  48. package/mcp/docs/cookbook/json_query/instructions.md +64 -0
  49. package/mcp/docs/cookbook/kblog/README.md +60 -0
  50. package/mcp/docs/cookbook/kblog/instructions.md +102 -0
  51. package/mcp/docs/cookbook/layered_rulesets/README.md +24 -0
  52. package/mcp/docs/cookbook/layered_rulesets/instructions.md +87 -0
  53. package/mcp/docs/cookbook/moving_picos/README.md +44 -0
  54. package/mcp/docs/cookbook/moving_picos/instructions.md +150 -0
  55. package/mcp/docs/cookbook/score_tracker/README.md +19 -0
  56. package/mcp/docs/cookbook/score_tracker/instructions.md +73 -0
  57. package/mcp/docs/cookbook/secrets/README.md +25 -0
  58. package/mcp/docs/cookbook/secrets/instructions.md +98 -0
  59. package/mcp/docs/cookbook/two_picos/README.md +20 -0
  60. package/mcp/docs/cookbook/two_picos/instructions.md +88 -0
  61. package/mcp/docs/cookbook/xmlui/README.md +23 -0
  62. package/mcp/docs/cookbook/xmlui/instructions.md +84 -0
  63. package/mcp/docs/developing/README.md +28 -0
  64. package/mcp/docs/developing/accepting-relationship-requests.md +65 -0
  65. package/mcp/docs/developing/arrays-and-maps.md +77 -0
  66. package/mcp/docs/developing/converting-time-formats.md +28 -0
  67. package/mcp/docs/developing/cookies-and-redirects.md +81 -0
  68. package/mcp/docs/developing/decoding-form-data.md +67 -0
  69. package/mcp/docs/developing/engine-log-files.md +34 -0
  70. package/mcp/docs/developing/event-loop.md +77 -0
  71. package/mcp/docs/developing/events-from-email.md +80 -0
  72. package/mcp/docs/developing/initializing-entity-variables.md +83 -0
  73. package/mcp/docs/developing/mcp-ai-tools.md +98 -0
  74. package/mcp/docs/developing/misconceptions.md +467 -0
  75. package/mcp/docs/developing/names-and-scope.md +44 -0
  76. package/mcp/docs/developing/postman.md +159 -0
  77. package/mcp/docs/developing/querying-another-pico.md +47 -0
  78. package/mcp/docs/developing/singleton-picos.md +36 -0
  79. package/mcp/docs/developing/tabular-data.md +67 -0
  80. package/mcp/docs/developing/tips.md +251 -0
  81. package/mcp/docs/developing/webhook-signatures.md +56 -0
  82. package/mcp/docs/developing/workflow.md +106 -0
  83. package/mcp/docs/exp/README.md +46 -0
  84. package/mcp/docs/exp/event.md +110 -0
  85. package/mcp/docs/exp/query.md +94 -0
  86. package/mcp/docs/lessons/README.md +59 -0
  87. package/mcp/docs/lessons/events-and-queries.md +247 -0
  88. package/mcp/docs/lessons/gossip.md +28 -0
  89. package/mcp/docs/lessons/modules-and-apis.md +270 -0
  90. package/mcp/docs/lessons/pico-based-systems.md +470 -0
  91. package/mcp/docs/lessons/pico-state.md +267 -0
  92. package/mcp/docs/lessons/pico-views.md +290 -0
  93. package/mcp/docs/lessons/quickstart.md +157 -0
  94. package/mcp/docs/lessons/relationships.md +530 -0
  95. package/mcp/docs/lessons/scatter-gather.md +362 -0
  96. package/mcp/docs/pico-engine.md +7 -5
  97. package/mcp/docs/pico-overview.md +3 -3
  98. package/mcp/docs/wrangler/README.md +47 -0
  99. package/mcp/docs/wrangler/channels.md +235 -0
  100. package/mcp/docs/wrangler/oauth.md +56 -0
  101. package/mcp/docs/wrangler/pds.md +423 -0
  102. package/mcp/docs/wrangler/portable-subtree.md +44 -0
  103. package/mcp/docs/wrangler/relationships.md +297 -0
  104. package/mcp/docs/wrangler/wrangler.md +253 -0
  105. package/mcp/docs/wrangler/xmlui.md +60 -0
  106. package/mcp/engineClient.js +57 -5
  107. package/mcp/mcpScopes.js +118 -0
  108. package/mcp/meshHttp.js +151 -45
  109. package/mcp/runStdio.js +2 -0
  110. package/mcp/subtreeTools.js +184 -0
  111. package/mcp/tryItTools.js +202 -0
  112. package/package.json +14 -8
  113. package/public/pico-engine-ui.js +26 -26
  114. package/src/cli.ts +6 -2
  115. package/src/engineConfig.ts +5 -2
  116. package/src/identity/portableMove.ts +6 -1
  117. package/src/index.ts +469 -430
  118. package/src/internalAccess.ts +127 -0
  119. package/src/oauth/OAuthService.ts +243 -11
  120. package/src/oauth/acg.ts +289 -25
  121. package/src/oauth/cimd.ts +508 -0
  122. package/src/oauth/discovery.ts +233 -0
  123. package/src/runMcp.ts +3 -1
  124. package/src/server.ts +252 -52
  125. package/src/subtreeWrangler.ts +17 -5
  126. package/src/uiChannelPolicies.ts +2 -0
@@ -0,0 +1,202 @@
1
+ "use strict";
2
+
3
+ // Try It! for agents: the same steps the developer UI's Try It! tab takes.
4
+
5
+ const { z } = require("zod");
6
+ const { jsonText } = require("./engineClient");
7
+ const { findWranglerEvent } = require("./devTools");
8
+
9
+ const UI_RID = "io.picolabs.pico-engine-ui";
10
+ const OAUTH_NOTE =
11
+ "The demos are meant for an engine without OAuth: on a mesh with OAuth turned on they install, but their pages and curl examples send no access token, so they may not load data.";
12
+
13
+ function textResult(text, isError = false) {
14
+ return { content: [{ type: "text", text }], isError };
15
+ }
16
+
17
+ const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
18
+
19
+ function resourceUris(folder) {
20
+ return {
21
+ overview: `pico://docs/cookbook/${folder}/README`,
22
+ instructions: `pico://docs/cookbook/${folder}/instructions`,
23
+ };
24
+ }
25
+
26
+ function summarize(demo) {
27
+ return {
28
+ name: demo.name || demo.rid,
29
+ folder: demo.folder,
30
+ bootstrapRid: demo.rid,
31
+ shows: demo.description,
32
+ whatToLookForAndTry: demo.notes || null,
33
+ cookbook: demo.docs,
34
+ resources: resourceUris(demo.folder),
35
+ files: (demo.files || []).map((f) => ({ rid: f.rid, file: f.file, url: f.url, path: f.path })),
36
+ };
37
+ }
38
+
39
+ function findDemo(demos, wanted) {
40
+ const w = wanted.trim().toLowerCase();
41
+ return demos.find(
42
+ (d) =>
43
+ d.folder.toLowerCase() === w ||
44
+ d.rid.toLowerCase() === w ||
45
+ String(d.name || "").toLowerCase() === w
46
+ );
47
+ }
48
+
49
+ async function box(client, uiEci) {
50
+ return client.channelQuery(uiEci, UI_RID, "box", {});
51
+ }
52
+
53
+ /** A child of a pico running a demo (it has a try_it channel and a demo's bootstrap), or null. */
54
+ async function runningDemo(client, childUiEci, demos) {
55
+ const info = await client.channelQuery(childUiEci, UI_RID, "pico", {});
56
+ const channel = ((info && info.channels) || []).find((c) => (c.tags || []).includes("try_it"));
57
+ if (!channel) return null;
58
+ const rulesets = (info && info.rulesets) || [];
59
+ const demo = demos.find((d) => rulesets.some((rs) => rs.rid === d.rid));
60
+ if (!demo) return null;
61
+ const name = ((await box(client, childUiEci)) || {}).name || demo.rid;
62
+ let status = null;
63
+ let error;
64
+ try {
65
+ status = await client.channelQuery(channel.id, demo.rid, "tryIt", {});
66
+ } catch (err) {
67
+ error = String(err);
68
+ }
69
+ return {
70
+ demo: demo.name || demo.rid,
71
+ folder: demo.folder,
72
+ picoName: name,
73
+ uiEci: childUiEci,
74
+ tryItEci: channel.id,
75
+ ready: !!(status && status.ready),
76
+ stage: status ? status.stage : undefined,
77
+ links: status ? status.links || [] : [],
78
+ error,
79
+ };
80
+ }
81
+
82
+ function registerTryItTools(server, client) {
83
+ server.tool(
84
+ "list_try_it_demos",
85
+ "List the Try It! demos that ship with this engine, in the order the developer UI shows them: what each shows, what to look for and try, its cookbook page (also an MCP resource), and its files. " +
86
+ OAUTH_NOTE,
87
+ {},
88
+ async () => {
89
+ try {
90
+ const { show, demos } = await client.getTryIt();
91
+ return textResult(
92
+ jsonText({
93
+ show,
94
+ hint:
95
+ show === "off"
96
+ ? "show_tryit_menu is off on this engine, so no demos are listed."
97
+ : "Run one with run_try_it_demo, passing its folder.",
98
+ demos: (demos || []).map(summarize),
99
+ })
100
+ );
101
+ } catch (err) {
102
+ return textResult(String(err), true);
103
+ }
104
+ }
105
+ );
106
+
107
+ server.tool(
108
+ "run_try_it_demo",
109
+ "Run a Try It! demo the way the developer UI does: create a child pico, install the demo's bootstrap ruleset on it, and wait until its tryIt() reports ready. Returns the child's UI ECI, the links to open (pages on their channels), and what to look for and try. Remove the demo afterwards with delete_pico on the returned uiEci. " +
110
+ OAUTH_NOTE,
111
+ {
112
+ demo: z.string().describe("The demo's folder (such as echo or collection), bootstrap rid, or name"),
113
+ parentEci: z
114
+ .string()
115
+ .optional()
116
+ .describe("UI ECI of the pico to create the child under; default the root pico"),
117
+ name: z.string().optional().describe("Name for the new child pico; default the demo's name"),
118
+ timeoutSeconds: z.number().int().min(1).max(300).optional().describe("How long to wait for ready; default 60"),
119
+ },
120
+ async ({ demo, parentEci, name, timeoutSeconds }) => {
121
+ try {
122
+ const { demos } = await client.getTryIt();
123
+ const found = findDemo(demos || [], demo);
124
+ if (!found) {
125
+ return textResult(
126
+ `No demo "${demo}". Folders: ${(demos || []).map((d) => d.folder).join(", ") || "(none; is show_tryit_menu off?)"}`,
127
+ true
128
+ );
129
+ }
130
+ const parent = parentEci || (await client.resolveUiEci());
131
+ const before = new Set(((await box(client, parent)) || {}).children || []);
132
+ const childName = name || found.name || found.rid;
133
+ await client.channelEventWait(parent, "engine_ui", "new", {
134
+ name: childName,
135
+ backgroundColor: "#c8e6c9",
136
+ });
137
+ let child;
138
+ for (let i = 0; i < 50 && !child; i++) {
139
+ child = (((await box(client, parent)) || {}).children || []).find((c) => !before.has(c));
140
+ if (!child) await sleep(200);
141
+ }
142
+ if (!child) return textResult("The new child pico did not appear.", true);
143
+
144
+ const installed = await client.channelEventWait(child, "engine_ui", "install", { url: found.url });
145
+ const failed = findWranglerEvent(installed, "ruleset_install_failed");
146
+ if (failed) {
147
+ return textResult(
148
+ jsonText({ error: "The bootstrap ruleset did not install.", details: failed, uiEci: child }),
149
+ true
150
+ );
151
+ }
152
+
153
+ const deadline = Date.now() + (timeoutSeconds || 60) * 1000;
154
+ let state = null;
155
+ while (Date.now() < deadline) {
156
+ state = await runningDemo(client, child, [found]);
157
+ if (state && state.ready) break;
158
+ await sleep(500);
159
+ }
160
+ const ready = !!(state && state.ready);
161
+ return textResult(
162
+ jsonText({
163
+ ...(state || { demo: found.name || found.rid, folder: found.folder, uiEci: child, ready: false }),
164
+ whatToLookForAndTry: found.notes || null,
165
+ cookbook: found.docs,
166
+ resources: resourceUris(found.folder),
167
+ hint: ready
168
+ ? "Open the links, or use query and raise_event on the channel ids in them (the segment after /ui/)."
169
+ : "Not ready yet. Check again with try_it_status; the stage says how far it got.",
170
+ }),
171
+ !ready
172
+ );
173
+ } catch (err) {
174
+ return textResult(String(err), true);
175
+ }
176
+ }
177
+ );
178
+
179
+ server.tool(
180
+ "try_it_status",
181
+ "The Try It! demos running in a pico's children, with each one's progress and links (the developer UI's \"Running here\").",
182
+ {
183
+ parentEci: z.string().optional().describe("UI ECI of the parent pico; default the root pico"),
184
+ },
185
+ async ({ parentEci }) => {
186
+ try {
187
+ const { demos } = await client.getTryIt();
188
+ const parent = parentEci || (await client.resolveUiEci());
189
+ const running = [];
190
+ for (const child of ((await box(client, parent)) || {}).children || []) {
191
+ const state = await runningDemo(client, child, demos || []);
192
+ if (state) running.push(state);
193
+ }
194
+ return textResult(jsonText({ parentEci: parent, running }));
195
+ } catch (err) {
196
+ return textResult(String(err), true);
197
+ }
198
+ }
199
+ );
200
+ }
201
+
202
+ module.exports = { registerTryItTools, findDemo };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pico-engine",
3
- "version": "1.9.5",
3
+ "version": "1.10.0",
4
4
  "description": "Node.js runtime for picos: persistent actors with their own identity, state, and channels that communicate by events and queries. Behavior is written in KRL. Includes an MCP server so AI coding assistants can inspect and drive a running engine.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -52,11 +52,16 @@
52
52
  "dev": "scriptsp -r dev:tsc dev:api",
53
53
  "dev:tsc": "tsc -w --preserveWatchOutput",
54
54
  "dev:api": "onchange -i -k dist/ -- node dist/cli.js",
55
- "test": "ava reset-cache && ava",
55
+ "test": "ava reset-cache && ava --serial --timeout=3m",
56
56
  "test:auth": "ava reset-cache && ava --serial ./test/auth.ts --timeout=2m",
57
57
  "test:oauth": "ava reset-cache && ava --serial ./test/oauth.ts --timeout=2m",
58
+ "test:oauth-discovery": "ava reset-cache && ava --serial ./test/oauthDiscovery.ts --timeout=2m",
59
+ "test:oauth-resource": "ava reset-cache && ava --serial ./test/oauthResource.ts --timeout=2m",
60
+ "test:cimd": "ava reset-cache && ava --serial ./test/cimd.ts --timeout=2m",
58
61
  "test:acg": "ava reset-cache && ava --serial ./test/acg.ts --timeout=2m",
59
62
  "test:http": "ava reset-cache && ava --serial ./test/httpSurface.ts --timeout=2m",
63
+ "test:internal-access": "ava reset-cache && ava --serial ./test/internalAccess.ts --timeout=2m",
64
+ "test:listen": "ava reset-cache && ava --serial ./test/listenFailure.ts --timeout=2m",
60
65
  "test:identity": "ava reset-cache && ava --serial ./test/identityStore.ts ./test/identityStoreEngine.ts --timeout=2m",
61
66
  "test:dido": "ava reset-cache && ava --serial ./test/didoModule.ts --timeout=2m",
62
67
  "test:webvh": "ava reset-cache && ava --serial ./test/webvh.ts --timeout=2m",
@@ -71,7 +76,7 @@
71
76
  "test:wildcard-channel-identity": "ava reset-cache && ava --serial ./test/wildcardChannelIdentity.ts --timeout=2m",
72
77
  "test:policy": "ava reset-cache && ava --serial ./test/layer2ChannelPolicy.ts ./test/channelPolicyCeiling.ts ./test/wildcardChannelIdentity.ts ./test/channelIdentityPolicy.ts ./test/engineConfig.ts --timeout=3m",
73
78
  "test:schema": "ava reset-cache && ava --serial ./test/uiTestingSchema.ts ./test/uiTestingHistorySaved.ts --timeout=3m",
74
- "test:mcp": "ava reset-cache && ava --serial ./test/mcpDevClient.ts ./test/mcpDevStdioE2e.ts ./test/mcpMesh.ts --timeout=5m && node test/helpers/printMcpTestNoiseNotes.js",
79
+ "test:mcp": "ava reset-cache && ava --serial ./test/mcpDevClient.ts ./test/mcpDevStdioE2e.ts ./test/mcpTryIt.ts ./test/mcpMesh.ts --timeout=5m && node test/helpers/printMcpTestNoiseNotes.js",
75
80
  "test:install-failure": "ava reset-cache && ava --serial ./test/installFailureVisibility.ts --timeout=3m",
76
81
  "test:cross-engine": "ava reset-cache && ava --serial ./test/crossEngineSubscription.ts --timeout=3m",
77
82
  "test:relationship-alias": "ava reset-cache && ava --serial ./test/relationshipAlias.ts --timeout=2m",
@@ -81,6 +86,7 @@
81
86
  "test:peer-did4": "ava reset-cache && ava --serial ./test/peerDid4.ts --timeout=2m",
82
87
  "test:views": "ava reset-cache && ava --serial ./test/xmluiSpike.ts ./test/xmluiRoutes.ts ./test/xmluiLauncher.ts ./test/xmluiConfig.ts ./test/xmluiViewSchema.ts ./test/xmluiViewPolicy.ts ./test/xmluiViewsOAuth.ts ./test/xmluiS2Demos.ts ./test/xmluiComponents.ts --timeout=2m",
83
88
  "test:try-it": "ava reset-cache && ava --serial ./test/tryIt.ts ./test/tryItDemos.ts --timeout=2m",
89
+ "test:libraries": "ava reset-cache && ava --serial ./test/krlLibraries.ts --timeout=2m",
84
90
  "vendor:xmlui": "node scripts/copy-xmlui-runtime.mjs"
85
91
  },
86
92
  "dependencies": {
@@ -106,14 +112,14 @@
106
112
  "express": "^4.16.4",
107
113
  "helmet": "^7.1.0",
108
114
  "home-dir": "^1.0.0",
109
- "krl-compiler": "^1.9.4",
110
- "krl-stdlib": "^1.9.0",
115
+ "krl-compiler": "^1.10.0",
116
+ "krl-stdlib": "^1.10.0",
111
117
  "level-json-coerce-null": "^1.0.1",
112
118
  "lodash": "^4.17.11",
113
119
  "make-dir": "^4.0.0",
114
120
  "minimist": "^1.2.5",
115
- "pico-engine-core": "^1.9.4",
116
- "pico-framework": "^0.8.2",
121
+ "pico-engine-core": "^1.10.0",
122
+ "pico-framework": "^1.10.0",
117
123
  "rotating-file-stream": "^1.4.1",
118
124
  "zod": "^3.25.76"
119
125
  },
@@ -143,5 +149,5 @@
143
149
  "!test/helpers/**/*"
144
150
  ]
145
151
  },
146
- "gitHead": "86e860664bb60d22c76656bc7c93b14d878405e1"
152
+ "gitHead": "9578ad6cd53c11fa60cac584f9814dcb58d8648e"
147
153
  }