pico-engine 1.9.2 → 1.9.4

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.
package/README.md CHANGED
@@ -2,7 +2,7 @@
2
2
 
3
3
  [![Node version](https://img.shields.io/node/v/pico-engine.svg)](https://nodejs.org/en/download/)
4
4
 
5
- An implementation of the [pico-engine](http://www.windley.com/archives/2016/03/rebuilding_krl.shtml) hosted on node.js
5
+ The Node.js runtime for **picos** (persistent compute objects): actors with their own identity, state, and channels that communicate by events and queries. Pico behavior is written in **KRL**, which the engine compiles to JavaScript. Documentation: https://docs.picolabs.io/
6
6
 
7
7
  ## Quick start
8
8
 
@@ -11,9 +11,9 @@ npm install -g pico-engine
11
11
  pico-engine
12
12
  ```
13
13
 
14
- Open `http://localhost:3000` — a root pico and UI channel are created on first run. Operator settings (port, data dir, policy ceiling) live in **`~/.config/pico-engine/config.json`**; copy [`config.example.json`](config.example.json). See [`docs/pico-engine.md`](../../docs/pico-engine.md) (published at https://docs.picolabs.io/).
14
+ Open `http://localhost:3000` — a root pico and UI channel are created on first run. Operator settings (port, data dir, policy ceiling) live in **`~/.config/pico-engine/config.json`**; copy [`config.example.json`](https://github.com/Picolab/pico-engine/blob/master/packages/pico-engine/config.example.json). See the [engine guide](https://docs.picolabs.io/#/pico-engine).
15
15
 
16
- **Agents (local dev):** [`CLAUDE.md`](../../CLAUDE.md) at repo root + `pico-engine mcp --stdio` (stdio MCP to the same engine). Machine-readable docs: [`docs/llms.txt`](../../docs/llms.txt).
16
+ **AI coding assistants:** `pico-engine mcp --stdio` runs an MCP server against the same engine (status, picos, channels, events, queries, KRL validation). Machine-readable docs: [`llms.txt`](https://docs.picolabs.io/llms.txt) and [`llms-full.txt`](https://docs.picolabs.io/llms-full.txt). Repo conventions for agents: [`CLAUDE.md`](https://github.com/Picolab/pico-engine/blob/master/CLAUDE.md).
17
17
 
18
18
  ## Getting Started
19
19
 
@@ -390,7 +390,7 @@ Every pico has a portable **did:webvh** identity. **DID-based relationships** (L
390
390
 
391
391
  **Deprecated:** `io.picolabs.did-o` and `dido:prepareQuery` — use **`wrangler:picoQuery`** and **`event:send({ did: … })`**.
392
392
 
393
- Full guide: [docs/guides/layer2-subscriptions.md](../../docs/guides/layer2-subscriptions.md) · Release notes: [docs/release/1.6.md](../../docs/release/1.6.md) · [CHANGELOG.md](../../CHANGELOG.md) (1.6.4 mesh-oauth-exempt + KRL directory UI; 1.6.3 fixes)
393
+ Full guide: [Layer 2 relationships](https://docs.picolabs.io/#/guides/layer2-subscriptions) · Release notes: [1.6](https://docs.picolabs.io/#/release/1.6) · [CHANGELOG.md](https://github.com/Picolab/pico-engine/blob/master/CHANGELOG.md) (1.6.4 mesh-oauth-exempt + KRL directory UI; 1.6.3 fixes)
394
394
 
395
395
  **Dependency:** pico-engine 1.6 requires **pico-framework `^0.8.1`** (npm). When developing engine + framework together, use `npm run link-framework` from the repo root.
396
396
 
@@ -416,7 +416,7 @@ PICO_ENGINE_HOME=/tmp/pico-engine-a PORT=3001 npm start
416
416
  PICO_ENGINE_HOME=/tmp/pico-engine-b PORT=3002 npm start
417
417
  ```
418
418
 
419
- Open http://localhost:3001 and http://localhost:3002 — register on both, then form a Layer 2 relationship A→B. See [docs/guides/layer2-subscriptions.md](../../docs/guides/layer2-subscriptions.md). Test/demo homes live under **`/tmp`** (not `~/.pico-engine`).
419
+ Open http://localhost:3001 and http://localhost:3002 — register on both, then form a Layer 2 relationship A→B. See [Layer 2 relationships](https://docs.picolabs.io/#/guides/layer2-subscriptions). Test/demo homes live under **`/tmp`** (not `~/.pico-engine`).
420
420
 
421
421
  ## Contributing
422
422
 
package/dist/server.js CHANGED
@@ -635,15 +635,15 @@ function server(core, uiECI, auth, oauth, identity) {
635
635
  if (componentName) {
636
636
  const { pico } = pf.lookupChannel(eci);
637
637
  const channelSchema = (0, pico_engine_core_2.channelSchemaForEci)(pico, core.rsRegistry, (channelEci) => pf.lookupChannel(channelEci), eci);
638
- const viewFn = (0, xmluiRuntime_1.viewQueryNameForComponent)(channelSchema.queries, appRid, componentName);
639
- if (!viewFn) {
638
+ const source = (0, xmluiRuntime_1.queryForComponentFile)(channelSchema.queries, appRid, componentName);
639
+ if (!source) {
640
640
  res.status(404).type("text/plain").end("Not found");
641
641
  return;
642
642
  }
643
643
  data = await core.query({
644
644
  eci,
645
- rid: appRid,
646
- name: viewFn,
645
+ rid: source.rid,
646
+ name: source.name,
647
647
  args: {},
648
648
  });
649
649
  }
@@ -1,12 +1,17 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.XMLUI_EMPTY_CODE_BEHIND = exports.XMLUI_RUNTIME_PUBLIC_PATH = exports.XMLUI_RUNTIME_VERSION = void 0;
3
+ exports.XMLUI_RID = exports.XMLUI_EMPTY_CODE_BEHIND = exports.XMLUI_RUNTIME_PUBLIC_PATH = exports.XMLUI_RUNTIME_VERSION = void 0;
4
+ exports.isXmluiBuiltin = isXmluiBuiltin;
4
5
  exports.isXmluiCodeBehindPath = isXmluiCodeBehindPath;
5
6
  exports.viewComponentFileName = viewComponentFileName;
6
7
  exports.parseComponentXmluiPath = parseComponentXmluiPath;
7
8
  exports.isXmluiSpaClientRoute = isXmluiSpaClientRoute;
8
- exports.viewQueryNameForComponent = viewQueryNameForComponent;
9
+ exports.queryForComponentFile = queryForComponentFile;
9
10
  exports.contentTypeForUiPath = contentTypeForUiPath;
11
+ const { xmluiBuiltins } = require("krl-compiler");
12
+ function isXmluiBuiltin(componentName) {
13
+ return xmluiBuiltins.isBuiltin(componentName);
14
+ }
10
15
  /** Pinned XMLUI standalone runtime shipped under `public/xmlui/`. */
11
16
  exports.XMLUI_RUNTIME_VERSION = "0.14.28";
12
17
  exports.XMLUI_RUNTIME_PUBLIC_PATH = `/xmlui/${exports.XMLUI_RUNTIME_VERSION}.js`;
@@ -43,14 +48,28 @@ function isXmluiSpaClientRoute(relPath) {
43
48
  return false;
44
49
  return true;
45
50
  }
46
- function viewQueryNameForComponent(queries, appRid, componentName) {
47
- var _a;
48
- if (!(queries === null || queries === void 0 ? void 0 : queries.length))
51
+ exports.XMLUI_RID = "io.picolabs.xmlui";
52
+ /**
53
+ * The query that answers components/<componentName>.xmlui on a channel:
54
+ * the app ruleset's @view or @component, then io.picolabs.xmlui's
55
+ * @component, then the one other ruleset's @component. Two other rulesets
56
+ * with the same component name, or a built-in XMLUI name, answer nothing.
57
+ */
58
+ function queryForComponentFile(queries, appRid, componentName) {
59
+ if (!(queries === null || queries === void 0 ? void 0 : queries.length) || isXmluiBuiltin(componentName))
60
+ return null;
61
+ const named = queries.filter((q) => viewComponentFileName(q.name) === componentName);
62
+ const fromApp = named.find((q) => q.rid === appRid && (q.view != null || q.component != null));
63
+ if (fromApp)
64
+ return { rid: fromApp.rid, name: fromApp.name };
65
+ const components = named.filter((q) => q.rid !== appRid && q.component != null);
66
+ const fromXmlui = components.find((q) => q.rid === exports.XMLUI_RID);
67
+ if (fromXmlui)
68
+ return { rid: fromXmlui.rid, name: fromXmlui.name };
69
+ const others = components.filter((q) => q.rid !== exports.XMLUI_RID);
70
+ if (others.length !== 1)
49
71
  return null;
50
- const hit = queries.find((q) => q.rid === appRid &&
51
- q.view != null &&
52
- viewComponentFileName(q.name) === componentName);
53
- return (_a = hit === null || hit === void 0 ? void 0 : hit.name) !== null && _a !== void 0 ? _a : null;
72
+ return { rid: others[0].rid, name: others[0].name };
54
73
  }
55
74
  function contentTypeForUiPath(filePath) {
56
75
  const lower = filePath.toLowerCase();
@@ -7,7 +7,8 @@ ruleset io.picolabs.xmlui {
7
7
  use module io.picolabs.wrangler alias wrangler
8
8
 
9
9
  provides query_url, event_url, query, event, escape, app_url, create_app_channel, rotate_app_channel, xmluiRuntimePath
10
- shares file, query_url, event_url, query, event, escape, app_url, xmluiRuntimePath
10
+ shares file, query_url, event_url, query, event, escape, app_url, xmluiRuntimePath,
11
+ picoTheme, picoSettings, picoThemeField, picoAccessTokenField
11
12
  }
12
13
 
13
14
  global {
@@ -115,12 +116,62 @@ ruleset io.picolabs.xmlui {
115
116
  })
116
117
  }
117
118
 
119
+ componentNamesFor = function(rid) {
120
+ wrangler:rulesetSchema(rid){"queries"}
121
+ .defaultsTo([])
122
+ .filter(function(q) {
123
+ not q{"component"}.isnull()
124
+ })
125
+ .map(function(q) {
126
+ q{"name"}
127
+ })
128
+ }
129
+
130
+ // The app's named queries, every @component of the app ruleset and of
131
+ // this ruleset, and file. A channel that omits a component cannot load it.
118
132
  queryPolicyForApp = function(app_rid, queries) {
119
133
  (queries.isnull() => shareNamesForApp(app_rid) | queries)
134
+ .append(componentNamesFor(app_rid))
120
135
  .map(function(q) {
121
136
  { "rid": app_rid, "name": q }
122
137
  })
138
+ .append(componentNamesFor(xmluiFileRid).map(function(q) {
139
+ { "rid": xmluiFileRid, "name": q }
140
+ }))
123
141
  .append([{ "rid": xmluiFileRid, "name": "file" }])
142
+ .reduce(function(acc, entry) {
143
+ acc.filter(function(r) {
144
+ r{"rid"} == entry{"rid"} && r{"name"} == entry{"name"}
145
+ }).length() > 0 => acc | acc.append([entry])
146
+ }, [])
147
+ }
148
+
149
+ allowsRule = function(allow, rid, name) {
150
+ allow.filter(function(r) {
151
+ r{"rid"} == rid && r{"name"} == name
152
+ }).length() > 0
153
+ }
154
+
155
+ // App channels are the ones the UI route can serve from.
156
+ appChannels = function() {
157
+ wrangler:channels().filter(function(c) {
158
+ allowsRule(c{["queryPolicy", "allow"]}.defaultsTo([]), xmluiFileRid, "file")
159
+ })
160
+ }
161
+
162
+ // Component queries the channel lacks: every @component of each ruleset
163
+ // the channel already allows, and of this ruleset. Never a new ruleset.
164
+ missingComponentRules = function(channel) {
165
+ have = channel{["queryPolicy", "allow"]}.defaultsTo([])
166
+ rids = have.map(function(r) { r{"rid"} })
167
+ .filter(function(rid) { rid != xmluiFileRid })
168
+ .reduce(function(acc, rid) { acc >< rid => acc | acc.append(rid) }, [])
169
+ rids.append([xmluiFileRid])
170
+ .map(function(rid) {
171
+ componentNamesFor(rid).map(function(name) { {"rid": rid, "name": name} })
172
+ })
173
+ .reduce(function(acc, rules) { acc.append(rules) }, [])
174
+ .filter(function(entry) { not allowsRule(have, entry{"rid"}, entry{"name"}) })
124
175
  }
125
176
 
126
177
  eventPolicyForDomains = function(domains) {
@@ -302,6 +353,102 @@ ruleset io.picolabs.xmlui {
302
353
  path.defaultsTo("index.html") == "config.json" => configJson(rid) |
303
354
  null
304
355
  }
356
+
357
+ /**
358
+ * Applies the theme stored in this browser tab (sessionStorage
359
+ * picoViewTheme: default, dark, green, green-dark, gray, gray-dark) to
360
+ * its children, on the theme's page background so rows stay readable
361
+ * in dark tones.
362
+ * @component
363
+ */
364
+ picoTheme = function() {
365
+ <<
366
+ <Component name="PicoTheme">
367
+ <Theme
368
+ themeId="{['green', 'green-dark'].includes(sessionStorage.getItem('picoViewTheme') || 'default') ? 'xmlui-green' : ['gray', 'gray-dark'].includes(sessionStorage.getItem('picoViewTheme') || 'default') ? 'xmlui-gray' : 'xmlui'}"
369
+ tone="{(sessionStorage.getItem('picoViewTheme') || 'default').endsWith('dark') ? 'dark' : 'light'}">
370
+ <VStack gap="$space-2" backgroundColor="$backgroundColor">
371
+ <Slot />
372
+ </VStack>
373
+ </Theme>
374
+ </Component>
375
+ >>
376
+ }
377
+
378
+ /**
379
+ * Settings dialog with no fields of its own. The caller adds fields as
380
+ * children. Save stores each field in sessionStorage as picoView<Field>
381
+ * (theme becomes picoViewTheme) and reloads the page.
382
+ * Props: title, note. Method: open(). Event: saved(data).
383
+ * @component
384
+ */
385
+ picoSettings = function() {
386
+ <<
387
+ <Component name="PicoSettings" method.open="() => dialog.open()">
388
+ <ModalDialog id="dialog" title="{$props.title ?? 'Settings'}">
389
+ <Form saveLabel="Save"
390
+ onSubmit="(data) => { Object.keys(data).forEach(k => sessionStorage.setItem('picoView' + k.charAt(0).toUpperCase() + k.slice(1), String(data[k] ?? '').trim())); emitEvent('saved', data); location.reload(); }">
391
+ <Slot />
392
+ <Text value="{($props.note ?? '') + ' This browser tab keeps these settings.'}" />
393
+ </Form>
394
+ </ModalDialog>
395
+ </Component>
396
+ >>
397
+ }
398
+
399
+ /**
400
+ * Theme picker for PicoSettings. Pairs with PicoTheme.
401
+ * @component
402
+ */
403
+ picoThemeField = function() {
404
+ <<
405
+ <Component name="PicoThemeField">
406
+ <FormItem bindTo="theme" label="Theme" type="select"
407
+ initialValue="{sessionStorage.getItem('picoViewTheme') || 'default'}">
408
+ <Option value="default" label="Default" />
409
+ <Option value="dark" label="Dark" />
410
+ <Option value="green" label="Green" />
411
+ <Option value="green-dark" label="Green, dark" />
412
+ <Option value="gray" label="Gray" />
413
+ <Option value="gray-dark" label="Gray, dark" />
414
+ </FormItem>
415
+ </Component>
416
+ >>
417
+ }
418
+
419
+ /**
420
+ * Access token field for PicoSettings, for views on an OAuth mesh. It is
421
+ * stored as picoViewBearer, which the view shell sends as the bearer on
422
+ * Sky calls from this tab.
423
+ * @component
424
+ */
425
+ picoAccessTokenField = function() {
426
+ <<
427
+ <Component name="PicoAccessTokenField">
428
+ <FormItem bindTo="bearer" label="Access token" type="password"
429
+ initialValue="{sessionStorage.getItem('picoViewBearer') || ''}" />
430
+ </Component>
431
+ >>
432
+ }
305
433
  }
306
434
 
435
+ // When rulesets change, give each app channel the component queries it
436
+ // lacks, so a channel created before a component existed can load it.
437
+ rule allow_components_on_app_channels {
438
+ select when wrangler schema_updated
439
+ foreach appChannels() setting(channel)
440
+ pre {
441
+ missing = missingComponentRules(channel)
442
+ }
443
+ if missing.length() > 0 then
444
+ wrangler:updateChannel(
445
+ channel{"id"},
446
+ channel{"tags"},
447
+ channel{"eventPolicy"},
448
+ {
449
+ "allow": channel{["queryPolicy", "allow"]}.defaultsTo([]).append(missing),
450
+ "deny": channel{["queryPolicy", "deny"]}.defaultsTo([])
451
+ }
452
+ )
453
+ }
307
454
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "pico-engine",
3
- "version": "1.9.2",
4
- "description": "An implementation of the pico-engine targeting node.js",
3
+ "version": "1.9.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",
7
7
  "url": "git+https://github.com/Picolab/pico-engine.git"
@@ -11,12 +11,22 @@
11
11
  "bugs": {
12
12
  "url": "https://github.com/Picolab/pico-engine/issues"
13
13
  },
14
- "homepage": "https://github.com/Picolab/pico-engine#readme",
14
+ "homepage": "https://docs.picolabs.io/",
15
15
  "keywords": [
16
+ "pico",
17
+ "picos",
16
18
  "pico-engine",
17
19
  "krl",
18
- "KRE",
19
- "IoT"
20
+ "actor",
21
+ "actor-model",
22
+ "persistent-compute-objects",
23
+ "event-driven",
24
+ "rules-engine",
25
+ "iot",
26
+ "decentralized-identity",
27
+ "did",
28
+ "mcp",
29
+ "model-context-protocol"
20
30
  ],
21
31
  "files": [
22
32
  "bin",
@@ -67,7 +77,7 @@
67
77
  "test:relationship-lifecycle": "ava reset-cache && ava --serial ./test/relationshipLifecycle.ts --timeout=2m",
68
78
  "test:epic9": "ava reset-cache && ava --serial ./test/epic9Matrix.ts --timeout=3m",
69
79
  "test:peer-did4": "ava reset-cache && ava --serial ./test/peerDid4.ts --timeout=2m",
70
- "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 --timeout=2m",
80
+ "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",
71
81
  "vendor:xmlui": "node scripts/copy-xmlui-runtime.mjs"
72
82
  },
73
83
  "dependencies": {
@@ -93,13 +103,13 @@
93
103
  "express": "^4.16.4",
94
104
  "helmet": "^7.1.0",
95
105
  "home-dir": "^1.0.0",
96
- "krl-compiler": "^1.9.0",
106
+ "krl-compiler": "^1.9.4",
97
107
  "krl-stdlib": "^1.9.0",
98
108
  "level-json-coerce-null": "^1.0.1",
99
109
  "lodash": "^4.17.11",
100
110
  "make-dir": "^4.0.0",
101
111
  "minimist": "^1.2.5",
102
- "pico-engine-core": "^1.9.0",
112
+ "pico-engine-core": "^1.9.4",
103
113
  "pico-framework": "^0.8.2",
104
114
  "rotating-file-stream": "^1.4.1",
105
115
  "zod": "^3.25.76"
package/src/server.ts CHANGED
@@ -33,7 +33,7 @@ import {
33
33
  isXmluiCodeBehindPath,
34
34
  isXmluiSpaClientRoute,
35
35
  parseComponentXmluiPath,
36
- viewQueryNameForComponent,
36
+ queryForComponentFile,
37
37
  XMLUI_EMPTY_CODE_BEHIND,
38
38
  } from "./xmluiRuntime";
39
39
  import { IdentityService } from "./identity/IdentityService";
@@ -744,19 +744,19 @@ export function server(
744
744
  (channelEci) => pf.lookupChannel(channelEci),
745
745
  eci
746
746
  );
747
- const viewFn = viewQueryNameForComponent(
747
+ const source = queryForComponentFile(
748
748
  channelSchema.queries,
749
749
  appRid,
750
750
  componentName
751
751
  );
752
- if (!viewFn) {
752
+ if (!source) {
753
753
  res.status(404).type("text/plain").end("Not found");
754
754
  return;
755
755
  }
756
756
  data = await core.query({
757
757
  eci,
758
- rid: appRid,
759
- name: viewFn,
758
+ rid: source.rid,
759
+ name: source.name,
760
760
  args: {},
761
761
  });
762
762
  } else {
@@ -1,3 +1,9 @@
1
+ const { xmluiBuiltins } = require("krl-compiler");
2
+
3
+ export function isXmluiBuiltin(componentName: string): boolean {
4
+ return xmluiBuiltins.isBuiltin(componentName);
5
+ }
6
+
1
7
  /** Pinned XMLUI standalone runtime shipped under `public/xmlui/`. */
2
8
  export const XMLUI_RUNTIME_VERSION = "0.14.28";
3
9
 
@@ -38,21 +44,38 @@ export interface ChannelSchemaQuery {
38
44
  rid: string;
39
45
  name: string;
40
46
  view?: unknown;
47
+ component?: unknown;
41
48
  }
42
49
 
43
- export function viewQueryNameForComponent(
50
+ export const XMLUI_RID = "io.picolabs.xmlui";
51
+
52
+ /**
53
+ * The query that answers components/<componentName>.xmlui on a channel:
54
+ * the app ruleset's @view or @component, then io.picolabs.xmlui's
55
+ * @component, then the one other ruleset's @component. Two other rulesets
56
+ * with the same component name, or a built-in XMLUI name, answer nothing.
57
+ */
58
+ export function queryForComponentFile(
44
59
  queries: ChannelSchemaQuery[] | undefined,
45
60
  appRid: string,
46
61
  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
62
+ ): { rid: string; name: string } | null {
63
+ if (!queries?.length || isXmluiBuiltin(componentName)) return null;
64
+ const named = queries.filter(
65
+ (q) => viewComponentFileName(q.name) === componentName
66
+ );
67
+ const fromApp = named.find(
68
+ (q) => q.rid === appRid && (q.view != null || q.component != null)
69
+ );
70
+ if (fromApp) return { rid: fromApp.rid, name: fromApp.name };
71
+ const components = named.filter(
72
+ (q) => q.rid !== appRid && q.component != null
54
73
  );
55
- return hit?.name ?? null;
74
+ const fromXmlui = components.find((q) => q.rid === XMLUI_RID);
75
+ if (fromXmlui) return { rid: fromXmlui.rid, name: fromXmlui.name };
76
+ const others = components.filter((q) => q.rid !== XMLUI_RID);
77
+ if (others.length !== 1) return null;
78
+ return { rid: others[0].rid, name: others[0].name };
56
79
  }
57
80
 
58
81
  export function contentTypeForUiPath(filePath: string): string {