pico-engine 1.8.0 → 1.9.1

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 (57) hide show
  1. package/README.md +5 -3
  2. package/dist/RulesetRegistryLoaderFs.js +46 -4
  3. package/dist/cli.js +3 -1
  4. package/dist/engineConfig.js +11 -0
  5. package/dist/index.js +2 -5
  6. package/dist/logging.js +148 -4
  7. package/dist/server.js +206 -1
  8. package/dist/stageKrl.js +26 -0
  9. package/dist/xmluiRuntime.js +68 -0
  10. package/krl/io.picolabs.pico-engine-ui.krl +14 -77
  11. package/krl/io.picolabs.wrangler.krl +28 -5
  12. package/krl/io.picolabs.xmlui.krl +305 -0
  13. package/mcp/devResources.js +17 -7
  14. package/mcp/docs/CLAUDE.md +85 -0
  15. package/{public → mcp}/docs/pico-engine.md +15 -11
  16. package/package.json +11 -7
  17. package/public/pico-engine-ui.css +1 -1
  18. package/public/pico-engine-ui.js +27 -25
  19. package/public/xmlui/0.12.7.js +419 -0
  20. package/public/xmlui/pico-view-boot.js +153 -0
  21. package/src/RulesetRegistryLoaderFs.ts +48 -4
  22. package/src/cli.ts +3 -1
  23. package/src/engineConfig.ts +18 -0
  24. package/src/index.ts +4 -6
  25. package/src/logging.ts +165 -4
  26. package/src/server.ts +250 -2
  27. package/src/stageKrl.ts +26 -0
  28. package/src/xmluiRuntime.ts +66 -0
  29. package/public/docs/README.md +0 -9
  30. package/public/docs/_media/logo.png +0 -0
  31. package/public/docs/_sidebar.md +0 -6
  32. package/public/docs/contributing.md +0 -64
  33. package/public/docs/favicon.ico +0 -0
  34. package/public/docs/index.html +0 -29
  35. package/public/docs/krl/README.md +0 -3
  36. package/public/docs/krl/_sidebar.md +0 -10
  37. package/public/docs/krl/discovery.md +0 -144
  38. package/public/docs/krl/modules/ctx.md +0 -151
  39. package/public/docs/krl/modules/event.md +0 -70
  40. package/public/docs/krl/modules/http.md +0 -42
  41. package/public/docs/krl/modules/math.md +0 -5
  42. package/public/docs/krl/modules/schedule.md +0 -5
  43. package/public/docs/krl/modules.md +0 -11
  44. package/public/docs/krl/rulesets.md +0 -81
  45. package/public/docs/krl/stdlib.md +0 -3
  46. package/public/docs/llms-full.txt +0 -479
  47. package/public/docs/llms.txt +0 -37
  48. package/public/docs/openapi.yaml +0 -78
  49. package/public/docs/pico.md +0 -5
  50. package/public/docs/rulesets/README.md +0 -25
  51. package/public/docs/rulesets/io.picolabs.oauth.md +0 -71
  52. package/public/docs/rulesets/io.picolabs.pds.md +0 -327
  53. package/public/docs/rulesets/io.picolabs.pico-engine-ui.md +0 -65
  54. package/public/docs/rulesets/io.picolabs.portable_subtree.md +0 -94
  55. package/public/docs/rulesets/io.picolabs.subscription.md +0 -398
  56. package/public/docs/rulesets/io.picolabs.wrangler.md +0 -471
  57. /package/{public → mcp}/docs/pico-overview.md +0 -0
package/src/server.ts CHANGED
@@ -10,7 +10,12 @@ import {
10
10
  listEngineKrlSources,
11
11
  resolveEngineKrlFile,
12
12
  } from "./bundledKrl";
13
- import { PicoEngineCore } from "pico-engine-core";
13
+ import {
14
+ assembleLogTransactions,
15
+ isRoutineQueryError,
16
+ PicoEngineCore,
17
+ RawLogEntry,
18
+ } from "pico-engine-core";
14
19
  import { PicoFramework } from "pico-framework";
15
20
  import { AuthCookieNames, AuthError, AuthService, authCookieNames } from "./auth";
16
21
  import {
@@ -22,11 +27,27 @@ import {
22
27
  rootHasOAuthMeshRuleset,
23
28
  } from "./oauth";
24
29
  import { uiECIForRoot } from "./provisionRoot";
30
+ import { channelSchemaForEci } from "pico-engine-core";
31
+ import {
32
+ contentTypeForUiPath,
33
+ isXmluiCodeBehindPath,
34
+ isXmluiSpaClientRoute,
35
+ parseComponentXmluiPath,
36
+ viewQueryNameForComponent,
37
+ XMLUI_EMPTY_CODE_BEHIND,
38
+ } from "./xmluiRuntime";
25
39
  import { IdentityService } from "./identity/IdentityService";
26
40
  import { registerWebvhRoutes } from "./identity/webvhRoutes";
27
41
  import { registerDidcommIngressRoutes } from "./identity/didcommIngressRoutes";
28
42
 
29
43
  import { getEngineRuntimeSettings } from "./engineConfig";
44
+ import {
45
+ picoLogEntries,
46
+ resolveEngineLogFilePath,
47
+ resolvePicoLogsReadPath,
48
+ subscribePicoLogRing,
49
+ } from "./logging";
50
+ import { stageKrlContent } from "./stageKrl";
30
51
 
31
52
  const engineVersion = require("../package.json").version;
32
53
 
@@ -131,6 +152,10 @@ export function server(
131
152
  if (req.path === "/oauth/authorize" || req.path === "/oauth/approve") {
132
153
  return helmet({ contentSecurityPolicy: false })(req, res, next);
133
154
  }
155
+ // XMLUI view shells use small inline scripts (__PUBLIC_PATH, startApp).
156
+ if (req.path === "/ui" || req.path.startsWith("/ui/")) {
157
+ return helmet({ contentSecurityPolicy: false })(req, res, next);
158
+ }
134
159
  return defaultHelmet(req, res, next);
135
160
  });
136
161
  app.use(express.static(path.resolve(__dirname, "..", "public")));
@@ -278,6 +303,25 @@ export function server(
278
303
  );
279
304
  }
280
305
 
306
+ app.get("/api/ui-sky-context", function (req, res, next) {
307
+ const eci =
308
+ typeof req.query.eci === "string" ? req.query.eci.trim() : "";
309
+ if (!eci) {
310
+ res.status(400).json({ error: "eci query parameter required" });
311
+ return;
312
+ }
313
+ if (!oauth) {
314
+ res.json({ bearerRequired: false });
315
+ return;
316
+ }
317
+ oauth
318
+ .skyRequiresBearer(eci)
319
+ .then((bearerRequired) => {
320
+ res.json({ bearerRequired });
321
+ })
322
+ .catch(next);
323
+ });
324
+
281
325
  app.get("/api/oauth/mesh-enabled", requireAuthSession, function (_req, res) {
282
326
  const roots = pf.rootPicos();
283
327
  const meshOAuthEnabled =
@@ -339,6 +383,23 @@ export function server(
339
383
  }
340
384
  });
341
385
 
386
+ app.post("/api/stage-krl", function (req, res, next) {
387
+ try {
388
+ const content = req.body?.content;
389
+ const filename =
390
+ typeof req.body?.filename === "string" ? req.body.filename : "staged.krl";
391
+ if (typeof content !== "string" || content.length > 2_000_000) {
392
+ res.status(400).json({ error: "content required (max 2MB)" });
393
+ return;
394
+ }
395
+ const url = stageKrlContent(content, filename);
396
+ res.json({ url });
397
+ } catch (err) {
398
+ const message = err instanceof Error ? err.message : String(err);
399
+ res.status(400).json({ error: message });
400
+ }
401
+ });
402
+
342
403
  app.get(/^\/krl\/(.+\.krl)$/, function (req, res, next) {
343
404
  const suffix = req.params[0];
344
405
  if (typeof suffix !== "string" || !suffix.endsWith(".krl")) {
@@ -388,6 +449,51 @@ export function server(
388
449
  .catch(next);
389
450
  });
390
451
 
452
+ /**
453
+ * Pushes each finished transaction for this pico. Owner session only,
454
+ * same gate as the rest of the developer UI.
455
+ */
456
+ app.get("/api/picos/:eci/logs/live", requireAuthSession, function (req, res) {
457
+ let picoId: string;
458
+ try {
459
+ picoId = pf.getPico(req.params.eci).id;
460
+ } catch (_e) {
461
+ res.status(404).json({ error: "Unknown pico" });
462
+ return;
463
+ }
464
+ res.writeHead(200, {
465
+ "Content-Type": "text/event-stream",
466
+ "Cache-Control": "no-cache, no-transform",
467
+ Connection: "keep-alive",
468
+ "X-Accel-Buffering": "no",
469
+ });
470
+ res.write(": ok\n\n");
471
+ let closed = false;
472
+ const unsubscribe = subscribePicoLogRing((id, txnId) => {
473
+ if (closed || id !== picoId) return;
474
+ const entries = picoLogEntries(picoId).filter(
475
+ (entry) => entry.txnId === txnId
476
+ );
477
+ const [txn] = assembleLogTransactions(entries as RawLogEntry[]);
478
+ if (!txn) return;
479
+ try {
480
+ res.write(`data: ${JSON.stringify(txn)}\n\n`);
481
+ } catch (_err) {
482
+ closed = true;
483
+ unsubscribe();
484
+ }
485
+ });
486
+ const beat = setInterval(() => {
487
+ if (closed) return;
488
+ res.write(": ping\n\n");
489
+ }, 25000);
490
+ req.on("close", () => {
491
+ closed = true;
492
+ clearInterval(beat);
493
+ unsubscribe();
494
+ });
495
+ });
496
+
391
497
  /** Localhost-only context for dev MCP (stdio) and other local tooling. */
392
498
  app.get("/api/dev/local", function (req, res) {
393
499
  if (!localhostChannelBypassEnabled() || !isLocalhostRequest(req)) {
@@ -401,11 +507,29 @@ export function server(
401
507
  if (!baseUrl) {
402
508
  baseUrl = `${req.protocol}://${req.get("host") || "localhost"}`;
403
509
  }
510
+ const settings = getEngineRuntimeSettings();
511
+ const primaryLogFile = resolveEngineLogFilePath(settings.home);
512
+ const picoLogsReadPath = resolvePicoLogsReadPath(settings.home);
513
+ const mirrorDisabled = settings.logToStdout && settings.logMirror === false;
404
514
  res.json({
405
515
  version: engineVersion,
406
516
  hasRoots: roots.length > 0,
407
517
  rootUiEci,
408
518
  baseUrl: baseUrl.replace(/\/$/, ""),
519
+ logging: {
520
+ home: settings.home,
521
+ logToStdout: settings.logToStdout,
522
+ logMirror: settings.logMirror,
523
+ logFileSetting: settings.logFile ?? null,
524
+ primaryLogFile,
525
+ /** File `getPicoLogs` reads (mirrors under stdout-only unless PICO_ENGINE_LOG_MIRROR=0). */
526
+ picoLogsReadPath,
527
+ picoLogsForDeveloperUi: true,
528
+ logMirrorDisabled: mirrorDisabled,
529
+ logRing: true,
530
+ hint:
531
+ "Logging tab reads the in-memory ring (last N transactions per pico, PICO_ENGINE_LOG_RING, default 200). A restart clears it. The log file remains the operator record.",
532
+ },
409
533
  });
410
534
  });
411
535
 
@@ -571,6 +695,129 @@ export function server(
571
695
  .catch(next);
572
696
  });
573
697
 
698
+ const XMLUI_FILE_RID = "io.picolabs.xmlui";
699
+
700
+ function respondXmluiQueryFailure(
701
+ err: unknown,
702
+ res: Response,
703
+ next: express.NextFunction
704
+ ): boolean {
705
+ if (!isRoutineQueryError(err)) {
706
+ return false;
707
+ }
708
+ const message = err + "";
709
+ if (!res.headersSent) {
710
+ if (/channel policy/i.test(message)) {
711
+ res.status(403).type("text/plain").end(message);
712
+ } else {
713
+ res.status(404).type("text/plain").end("Not found");
714
+ }
715
+ }
716
+ return true;
717
+ }
718
+
719
+ async function serveXmluiFile(
720
+ req: Request,
721
+ res: Response,
722
+ next: express.NextFunction,
723
+ eci: string,
724
+ appRid: string,
725
+ filePath: string
726
+ ) {
727
+ const rel = (filePath || "index.html").replace(/^\/+/, "") || "index.html";
728
+ try {
729
+ if (isXmluiCodeBehindPath(rel)) {
730
+ res
731
+ .status(200)
732
+ .setHeader("Content-Type", contentTypeForUiPath(rel))
733
+ .end(XMLUI_EMPTY_CODE_BEHIND);
734
+ return;
735
+ }
736
+
737
+ let data: unknown;
738
+ const componentName = appRid ? parseComponentXmluiPath(rel) : null;
739
+ if (componentName) {
740
+ const { pico } = pf.lookupChannel(eci);
741
+ const channelSchema = channelSchemaForEci(
742
+ pico,
743
+ core.rsRegistry,
744
+ (channelEci) => pf.lookupChannel(channelEci),
745
+ eci
746
+ );
747
+ const viewFn = viewQueryNameForComponent(
748
+ channelSchema.queries,
749
+ appRid,
750
+ componentName
751
+ );
752
+ if (!viewFn) {
753
+ res.status(404).type("text/plain").end("Not found");
754
+ return;
755
+ }
756
+ data = await core.query({
757
+ eci,
758
+ rid: appRid,
759
+ name: viewFn,
760
+ args: {},
761
+ });
762
+ } else {
763
+ data = await core.query({
764
+ eci,
765
+ rid: XMLUI_FILE_RID,
766
+ name: "file",
767
+ args: { rid: appRid, path: rel },
768
+ });
769
+ }
770
+ if (data == null && appRid && isXmluiSpaClientRoute(rel)) {
771
+ data = await core.query({
772
+ eci,
773
+ rid: XMLUI_FILE_RID,
774
+ name: "file",
775
+ args: { rid: appRid, path: "index.html" },
776
+ });
777
+ }
778
+ if (data == null) {
779
+ res.status(404).type("text/plain").end("Not found");
780
+ return;
781
+ }
782
+ if (
783
+ typeof data === "object" &&
784
+ data !== null &&
785
+ "error" in (data as Record<string, unknown>)
786
+ ) {
787
+ const message = String((data as Record<string, unknown>).error);
788
+ res.status(404).type("text/plain").end(message);
789
+ return;
790
+ }
791
+ const servedPath =
792
+ rel === "index.html" || !isXmluiSpaClientRoute(rel) ? rel : "index.html";
793
+ const contentType = contentTypeForUiPath(servedPath);
794
+ res.setHeader("Content-Type", contentType);
795
+ if (contentType.startsWith("application/json") && typeof data === "object") {
796
+ res.json(data);
797
+ return;
798
+ }
799
+ res.end(typeof data === "string" ? data : JSON.stringify(data));
800
+ } catch (err) {
801
+ if (respondXmluiQueryFailure(err, res, next)) {
802
+ return;
803
+ }
804
+ next(err);
805
+ }
806
+ }
807
+
808
+ app.get("/ui/:eci", function (req, res, next) {
809
+ void serveXmluiFile(req, res, next, req.params.eci, "", "index.html");
810
+ });
811
+
812
+ app.get("/ui/:eci/:rid", function (req, res, next) {
813
+ void serveXmluiFile(req, res, next, req.params.eci, req.params.rid, "index.html");
814
+ });
815
+
816
+ app.get("/ui/:eci/:rid/*", function (req, res, next) {
817
+ const rest = (req.params as { 0?: string })[0] || "index.html";
818
+ void serveXmluiFile(req, res, next, req.params.eci, req.params.rid, rest);
819
+ });
820
+
574
821
  app.all("/sky/query/:eci/:rid/:function", requireSkyBearerIfOAuth, handleSkyQuery);
575
822
  // Legacy alias; prefer /sky/query/ per Sky Query API docs.
576
823
  app.all("/sky/cloud/:eci/:rid/:function", requireSkyBearerIfOAuth, handleSkyQuery);
@@ -603,7 +850,8 @@ export function server(
603
850
  let message = err + "";
604
851
  const policyNoise =
605
852
  process.env.NODE_ENV === "test" &&
606
- /not allowed by channel policy/i.test(message);
853
+ (isRoutineQueryError(err) ||
854
+ /not allowed by channel policy/i.test(message));
607
855
  if (!policyNoise) {
608
856
  console.error(err);
609
857
  }
@@ -0,0 +1,26 @@
1
+ import * as fs from "fs";
2
+ import * as path from "path";
3
+ import * as os from "os";
4
+ import { toFileUrl } from "./utils/toFileUrl";
5
+
6
+ const STAGE_DIR = path.join(os.tmpdir(), "pico-engine-staged-krl");
7
+
8
+ /** Write KRL source to a temp file and return a file:// URL the registry can load. */
9
+ export function stageKrlContent(content: string, filename: string): string {
10
+ if (typeof content !== "string" || !/^ruleset\s+/m.test(content)) {
11
+ throw new Error("File must contain a KRL ruleset (starting with ruleset …)");
12
+ }
13
+ let base = path.basename(filename || "staged.krl");
14
+ if (!base.toLowerCase().endsWith(".krl")) {
15
+ base = base + ".krl";
16
+ }
17
+ base = base.replace(/[^\w.-]+/g, "_");
18
+ if (base === ".krl" || base === "") {
19
+ base = "staged.krl";
20
+ }
21
+
22
+ fs.mkdirSync(STAGE_DIR, { recursive: true });
23
+ const dest = path.join(STAGE_DIR, `${Date.now()}-${base}`);
24
+ fs.writeFileSync(dest, content, { encoding: "utf8", flag: "wx" });
25
+ return toFileUrl(dest);
26
+ }
@@ -0,0 +1,66 @@
1
+ /** Pinned XMLUI standalone runtime shipped under `public/xmlui/`. */
2
+ export const XMLUI_RUNTIME_VERSION = "0.12.7";
3
+
4
+ export const XMLUI_RUNTIME_PUBLIC_PATH = `/xmlui/${XMLUI_RUNTIME_VERSION}.js`;
5
+
6
+ /** XMLUI standalone always requests Main.xmlui.xs (and per-component .xmlui.xs). */
7
+ export const XMLUI_EMPTY_CODE_BEHIND = "var __pico_xmlui_codebehind = 0;\n";
8
+
9
+ export function isXmluiCodeBehindPath(relPath: string): boolean {
10
+ if (relPath === "Main.xmlui.xs") return true;
11
+ return /^components\/.+\.xmlui\.xs$/i.test(relPath);
12
+ }
13
+
14
+ /** Map a shared function name to the XMLUI component file name (Hello, ColorView, …). */
15
+ export function viewComponentFileName(fnName: string): string {
16
+ if (!fnName) return fnName;
17
+ return fnName.charAt(0).toUpperCase() + fnName.slice(1);
18
+ }
19
+
20
+ export function parseComponentXmluiPath(relPath: string): string | null {
21
+ const m = /^components\/(.+)\.xmlui$/i.exec(relPath);
22
+ return m ? m[1] : null;
23
+ }
24
+
25
+ /** Client route segment (e.g. list, contact/abc) — not a static XMLUI asset. */
26
+ export function isXmluiSpaClientRoute(relPath: string): boolean {
27
+ const rel = relPath.replace(/^\/+/, "");
28
+ if (!rel || rel === "index.html") return false;
29
+ if (rel === "Main.xmlui" || rel === "config.json") return false;
30
+ if (isXmluiCodeBehindPath(rel)) return false;
31
+ if (parseComponentXmluiPath(rel)) return false;
32
+ const lastSegment = rel.split("/").pop() || "";
33
+ if (lastSegment.includes(".")) return false;
34
+ return true;
35
+ }
36
+
37
+ export interface ChannelSchemaQuery {
38
+ rid: string;
39
+ name: string;
40
+ view?: unknown;
41
+ }
42
+
43
+ export function viewQueryNameForComponent(
44
+ queries: ChannelSchemaQuery[] | undefined,
45
+ appRid: string,
46
+ componentName: string
47
+ ): string | null {
48
+ if (!queries?.length) return null;
49
+ const hit = queries.find(
50
+ (q) =>
51
+ q.rid === appRid &&
52
+ q.view != null &&
53
+ viewComponentFileName(q.name) === componentName
54
+ );
55
+ return hit?.name ?? null;
56
+ }
57
+
58
+ export function contentTypeForUiPath(filePath: string): string {
59
+ const lower = filePath.toLowerCase();
60
+ if (lower.endsWith(".html")) return "text/html; charset=utf-8";
61
+ if (lower.endsWith(".xmlui")) return "application/xml; charset=utf-8";
62
+ if (lower.endsWith(".xs")) return "text/plain; charset=utf-8";
63
+ if (lower.endsWith(".json")) return "application/json; charset=utf-8";
64
+ if (lower.endsWith(".css")) return "text/css; charset=utf-8";
65
+ return "text/plain; charset=utf-8";
66
+ }
@@ -1,9 +0,0 @@
1
- # pico-engine NEXT
2
-
3
- NEXT is a rewrite of pico-engine that introduces major improvements.
4
-
5
- * Ruleset versioning and sharing to facilitate decentralized code sharing.
6
- * A more pico-centric architecture that makes pico's easier to transfer between hosts.
7
- * Better channel policies.
8
- * A new UI written in React and only uses pico channels to render.
9
- * Built on top of [pico-framework](https://github.com/Picolab/pico-framework) and [select-when](https://github.com/Picolab/select-when).
Binary file
@@ -1,6 +0,0 @@
1
- - [Welcome](/)
2
- - [Persistent Compute Objects](/pico-overview)
3
- - [Pico Engine](/pico-engine)
4
- - [Bundled rulesets](/rulesets/)
5
- - [KRL Manual](/krl/)
6
- - [Contributing](contributing)
@@ -1,64 +0,0 @@
1
- # Contributing
2
-
3
-
4
- To run the pico-engine in development mode do the following:
5
-
6
- ```sh
7
- $ git clone https://github.com/Picolab/pico-engine.git
8
- $ cd pico-engine
9
- $ npm run setup
10
- $ npm start
11
- ```
12
-
13
- That will start the server and run the test. `npm start` is simply an alias for `cd packages/pico-engine && npm start`
14
-
15
- **NOTE about dependencies:** generally don't use `npm i`, rather use `npm run setup` from the root. [lerna](https://github.com/lerna/lerna) will link up the packages so when you make changes in one package, it will be used in others.
16
-
17
- ## Improving documentation
18
-
19
- This documentation site is found in the [docs](https://github.com/Picolab/pico-engine/tree/master/docs) folder at the repository root. The pages are simple markdown files. It uses [docsify](https://docsify.js.org/) to serve it.
20
-
21
- To preview changes run the docsify local server using `npm run docs`. Then open your browser to the "Listening at" url.
22
-
23
- ## Making changes
24
-
25
- Use a branch (or fork) to do your work. When you are ready, create a pull request. That way we can review it before merging it into master. (See the git cheatsheet below)
26
-
27
- ### git cheatsheet
28
-
29
- ```sh
30
- # list your checked out branches
31
- git branch
32
-
33
- # list all branches including remote ones you don't have checked out
34
- git branch -a
35
-
36
- # checkout a remote branch
37
- git checkout -t origin/<branch>
38
-
39
- # switch branches
40
- git checkout <branch>
41
- git checkout master
42
-
43
- # create a new branch off master
44
- git checkout -b <branch> master
45
-
46
- # push your local branch to github
47
- git push -u origin <branch>
48
-
49
- # to update your branch with the latest in master
50
- git checkout master
51
- git pull
52
- git checkout <branch>
53
- git merge master
54
-
55
-
56
- # Use github to merge your branch into master using a pull request.
57
- # On github use the "new pull request" button to make a PR for merging.
58
- # Once the PR is merged you can delete the branch using the button on github.
59
-
60
-
61
- # Even though the branch is deleted on github, it won't delete it off your local machine.
62
- # to delete a local branch
63
- git branch -d <branch>
64
- ```
Binary file
@@ -1,29 +0,0 @@
1
- <!DOCTYPE html>
2
- <html lang="en">
3
- <head>
4
- <meta charset="UTF-8" />
5
- <title>pico-engine</title>
6
- <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
7
- <meta name="description" content="Description" />
8
- <meta
9
- name="viewport"
10
- content="width=device-width, user-scalable=no, initial-scale=1.0, maximum-scale=1.0, minimum-scale=1.0"
11
- />
12
- <link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/vue.css" />
13
- </head>
14
- <body>
15
- <div id="app"></div>
16
- <script>
17
- window.$docsify = {
18
- name: "pico-engine",
19
- repo: "https://github.com/Picolab/pico-engine",
20
- logo: "/_media/logo.png",
21
- themeColor: "#1A90CF",
22
- loadSidebar: true,
23
- auto2top: true,
24
- subMaxLevel: 3
25
- };
26
- </script>
27
- <script src="//unpkg.com/docsify/lib/docsify.min.js"></script>
28
- </body>
29
- </html>
@@ -1,3 +0,0 @@
1
- # KRL Manual NEXT
2
-
3
- This is the manual Kinetic Rule Language NEXT
@@ -1,10 +0,0 @@
1
- - [KRL Manual](/krl/)
2
- - [Rulesets](/krl/rulesets)
3
- - [Discovery](/krl/discovery)
4
- - [Standard Library](/krl/stdlib)
5
- - [Modules](/krl/modules)
6
- - [ctx](/krl/modules/ctx)
7
- - [event](/krl/modules/event)
8
- - [http](/krl/modules/http)
9
- - [math](/krl/modules/math)
10
- - [schedule](/krl/modules/schedule)
@@ -1,144 +0,0 @@
1
- # Discovery
2
-
3
- Every pico has a **`discovery`** channel. Integrators send a single event to learn what the pico can do. Each installed ruleset that participates in discovery responds with a **`discovery capability`** directive.
4
-
5
- This is event-based (not a query on a specific ruleset) so the engine can aggregate responses from every ruleset that implements discovery.
6
-
7
- ## Discovery channel
8
-
9
- Wrangler creates a channel tagged `discovery` on every pico. Its policy allows **only** the discovery event:
10
-
11
- | Direction | Allowed |
12
- |-----------|---------|
13
- | Events in | `discovery capabilities` |
14
- | Queries | none |
15
-
16
- Find the channel with `wrangler:discoveryChannel()` or `wrangler:channels(["discovery"])`.
17
-
18
- ## Integrator flow
19
-
20
- 1. Obtain the target pico's discovery channel ECI (via relationship metadata, parent query, etc.).
21
- 2. Send `discovery capabilities` on that channel.
22
- 3. Optionally include an **`eci`** attribute — the channel the integrator will use for subsequent queries and events on this pico.
23
- 4. Collect **`discovery capability`** directives from the event response.
24
-
25
- When `eci` is present, each ruleset filters its bindings so the integrator only sees capabilities that channel's policy **allows**. Denied operations are omitted, not listed and blocked later.
26
-
27
- Example (HTTP):
28
-
29
- ```http
30
- POST /sky/event/{discovery_eci}/discovery/capabilities/wait
31
- Content-Type: application/json
32
-
33
- {"eci": "{caller_eci}"}
34
- ```
35
-
36
- ## Ruleset author pattern
37
-
38
- Discovery is opt-in per ruleset. Add:
39
-
40
- 1. An **`app`** map — short metadata (`name`, `version`, optional `title`, `description`, `iconURL`).
41
- 2. A **`bindings()`** function — the integrator contract (queries, events, notifications).
42
- 3. A **discovery rule** that selects on `discovery capabilities` and sends a directive.
43
-
44
- ```krl
45
- ruleset io.picolabs.myapp {
46
- meta {
47
- use module io.picolabs.wrangler alias wrangler
48
- }
49
- global {
50
- app = {
51
- "name": "myapp",
52
- "title": "My App",
53
- "version": "1.0",
54
- "description": "One sentence explaining what this app does on the pico."
55
- };
56
-
57
- bindings = function() {
58
- {
59
- "version": 1,
60
- "queries": [
61
- {
62
- "name": "getStatus",
63
- "description": "Return the current status map."
64
- }
65
- ],
66
- "events": [
67
- {
68
- "domain": "myapp",
69
- "name": "refresh",
70
- "attrs": [],
71
- "description": "Ask the app to refresh its state."
72
- }
73
- ]
74
- }
75
- }
76
- }
77
-
78
- rule discovery {
79
- select when discovery capabilities
80
- send_directive("discovery capability", {
81
- "app": app,
82
- "rid": meta:rid,
83
- "bindings": wrangler:filterBindingsForCaller(
84
- bindings(),
85
- event:attr("eci"),
86
- meta:rid
87
- ),
88
- "iconURL": "https://example.com/myapp.svg"
89
- });
90
- }
91
- }
92
- ```
93
-
94
- ### Bindings shape
95
-
96
- `bindings()` describes what an integrator may use — not internal rule names.
97
-
98
- | Key | Purpose |
99
- |-----|---------|
100
- | `version` | Bindings schema version (currently `1`) |
101
- | `queries` | `[{"name": "...", "args": [...], "description": "..."}]` callable via `/sky/query/` |
102
- | `events` | `[{"domain": "...", "name": "...", "attrs": [...], "description": "..."}]` sendable to this pico |
103
- | `notifications` | Optional block with `trigger`, `forward`, and `channels` for notification routing |
104
-
105
- ### App metadata
106
-
107
- | Field | Purpose |
108
- |-------|---------|
109
- | `name` | Short id (e.g. `journal`) |
110
- | `title` | Human-readable label (e.g. `Journal`) |
111
- | `version` | App version string |
112
- | `description` | What the app does on this pico — shown to integrators during discovery |
113
-
114
- ### Policy filtering
115
-
116
- Use `wrangler:filterBindingsForCaller(bindings, caller_eci, rid)` in your discovery rule:
117
-
118
- - **`caller_eci`** — from `event:attr("eci")`; pass through when null (unfiltered).
119
- - **`rid`** — `meta:rid` for this ruleset (used to check query policy).
120
-
121
- Filtering uses `wrangler:allowsEventForChannel` and `wrangler:allowsQueryForChannel`, which evaluate the caller channel's policy from `ctx:channels` on this pico.
122
-
123
- ## Directive: `discovery capability`
124
-
125
- Each participating ruleset may emit one directive:
126
-
127
- ```json
128
- {
129
- "name": "discovery capability",
130
- "options": {
131
- "app": {
132
- "name": "myapp",
133
- "title": "My App",
134
- "version": "1.0",
135
- "description": "One sentence explaining what this app does."
136
- },
137
- "rid": "io.picolabs.myapp",
138
- "bindings": { "version": 1, "queries": [], "events": [] },
139
- "iconURL": "https://example.com/myapp.svg"
140
- }
141
- }
142
- ```
143
-
144
- The engine merges directives from all selecting rules. Integrators should handle zero, one, or many capabilities per pico.