@matatbread/matbot-host-node 0.0.0-stage → 0.5.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.
package/LICENSE ADDED
@@ -0,0 +1,201 @@
1
+ Apache License
2
+ Version 2.0, January 2004
3
+ http://www.apache.org/licenses/
4
+
5
+ TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
6
+
7
+ 1. Definitions.
8
+
9
+ "License" shall mean the terms and conditions for use, reproduction,
10
+ and distribution as defined by Sections 1 through 9 of this document.
11
+
12
+ "Licensor" shall mean the copyright owner or entity authorized by
13
+ the copyright owner that is granting the License.
14
+
15
+ "Legal Entity" shall mean the union of the acting entity and all
16
+ other entities that control, are controlled by, or are under common
17
+ control with that entity. For the purposes of this definition,
18
+ "control" means (i) the power, direct or indirect, to cause the
19
+ direction or management of such entity, whether by contract or
20
+ otherwise, or (ii) ownership of fifty percent (50%) or more of the
21
+ outstanding shares, or (iii) beneficial ownership of such entity.
22
+
23
+ "You" (or "Your") shall mean an individual or Legal Entity
24
+ exercising permissions granted by this License.
25
+
26
+ "Source" form shall mean the preferred form for making modifications,
27
+ including but not limited to software source code, documentation
28
+ source, and configuration files.
29
+
30
+ "Object" form shall mean any form resulting from mechanical
31
+ transformation or translation of a Source form, including but
32
+ not limited to compiled object code, generated documentation,
33
+ and conversions to other media types.
34
+
35
+ "Work" shall mean the work of authorship, whether in Source or
36
+ Object form, made available under the License, as indicated by a
37
+ copyright notice that is included in or attached to the work
38
+ (an example is provided in the Appendix below).
39
+
40
+ "Derivative Works" shall mean any work, whether in Source or Object
41
+ form, that is based on (or derived from) the Work and for which the
42
+ editorial revisions, annotations, elaborations, or other modifications
43
+ represent, as a whole, an original work of authorship. For the purposes
44
+ of this License, Derivative Works shall not include works that remain
45
+ separable from, or merely link (or bind by name) to the interfaces of,
46
+ the Work and Derivative Works thereof.
47
+
48
+ "Contribution" shall mean any work of authorship, including
49
+ the original version of the Work and any modifications or additions
50
+ to that Work or Derivative Works thereof, that is intentionally
51
+ submitted to Licensor for inclusion in the Work by the copyright owner
52
+ or by an individual or Legal Entity authorized to submit on behalf of
53
+ the copyright owner. For the purposes of this definition, "submitted"
54
+ means any form of electronic, verbal, or written communication sent
55
+ to the Licensor or its representatives, including but not limited to
56
+ communication on electronic mailing lists, source code control systems,
57
+ and issue tracking systems that are managed by, or on behalf of, the
58
+ Licensor for the purpose of discussing and improving the Work, but
59
+ excluding communication that is conspicuously marked or otherwise
60
+ designated in writing by the copyright owner as "Not a Contribution."
61
+
62
+ "Contributor" shall mean Licensor and any individual or Legal Entity
63
+ on behalf of whom a Contribution has been received by Licensor and
64
+ subsequently incorporated within the Work.
65
+
66
+ 2. Grant of Copyright License. Subject to the terms and conditions of
67
+ this License, each Contributor hereby grants to You a perpetual,
68
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
69
+ copyright license to reproduce, prepare Derivative Works of,
70
+ publicly display, publicly perform, sublicense, and distribute the
71
+ Work and such Derivative Works in Source or Object form.
72
+
73
+ 3. Grant of Patent License. Subject to the terms and conditions of
74
+ this License, each Contributor hereby grants to You a perpetual,
75
+ worldwide, non-exclusive, no-charge, royalty-free, irrevocable
76
+ (except as stated in this section) patent license to make, have made,
77
+ use, offer to sell, sell, import, and otherwise transfer the Work,
78
+ where such license applies only to those patent claims licensable
79
+ by such Contributor that are necessarily infringed by their
80
+ Contribution(s) alone or by combination of their Contribution(s)
81
+ with the Work to which such Contribution(s) was submitted. If You
82
+ institute patent litigation against any entity (including a
83
+ cross-claim or counterclaim in a lawsuit) alleging that the Work
84
+ or a Contribution incorporated within the Work constitutes direct
85
+ or contributory patent infringement, then any patent licenses
86
+ granted to You under this License for that Work shall terminate
87
+ as of the date such litigation is filed.
88
+
89
+ 4. Redistribution. You may reproduce and distribute copies of the
90
+ Work or Derivative Works thereof in any medium, with or without
91
+ modifications, and in Source or Object form, provided that You
92
+ meet the following conditions:
93
+
94
+ (a) You must give any other recipients of the Work or
95
+ Derivative Works a copy of this License; and
96
+
97
+ (b) You must cause any modified files to carry prominent notices
98
+ stating that You changed the files; and
99
+
100
+ (c) You must retain, in the Source form of any Derivative Works
101
+ that You distribute, all copyright, patent, trademark, and
102
+ attribution notices from the Source form of the Work,
103
+ excluding those notices that do not pertain to any part of
104
+ the Derivative Works; and
105
+
106
+ (d) If the Work includes a "NOTICE" text file as part of its
107
+ distribution, then any Derivative Works that You distribute must
108
+ include a readable copy of the attribution notices contained
109
+ within such NOTICE file, excluding those notices that do not
110
+ pertain to any part of the Derivative Works, in at least one
111
+ of the following places: within a NOTICE text file distributed
112
+ as part of the Derivative Works; within the Source form or
113
+ documentation, if provided along with the Derivative Works; or,
114
+ within a display generated by the Derivative Works, if and
115
+ wherever such third-party notices normally appear. The contents
116
+ of the NOTICE file are for informational purposes only and
117
+ do not modify the License. You may add Your own attribution
118
+ notices within Derivative Works that You distribute, alongside
119
+ or as an addendum to the NOTICE text from the Work, provided
120
+ that such additional attribution notices cannot be construed
121
+ as modifying the License.
122
+
123
+ You may add Your own copyright statement to Your modifications and
124
+ may provide additional or different license terms and conditions
125
+ for use, reproduction, or distribution of Your modifications, or
126
+ for any such Derivative Works as a whole, provided Your use,
127
+ reproduction, and distribution of the Work otherwise complies with
128
+ the conditions stated in this License.
129
+
130
+ 5. Submission of Contributions. Unless You explicitly state otherwise,
131
+ any Contribution intentionally submitted for inclusion in the Work
132
+ by You to the Licensor shall be under the terms and conditions of
133
+ this License, without any additional terms or conditions.
134
+ Notwithstanding the above, nothing herein shall supersede or modify
135
+ the terms of any separate license agreement you may have executed
136
+ with Licensor regarding such Contributions.
137
+
138
+ 6. Trademarks. This License does not grant permission to use the trade
139
+ names, trademarks, service marks, or product names of the Licensor,
140
+ except as required for reasonable and customary use in describing the
141
+ origin of the Work and reproducing the content of the NOTICE file.
142
+
143
+ 7. Disclaimer of Warranty. Unless required by applicable law or
144
+ agreed to in writing, Licensor provides the Work (and each
145
+ Contributor provides its Contributions) on an "AS IS" BASIS,
146
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
147
+ implied, including, without limitation, any warranties or conditions
148
+ of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
149
+ PARTICULAR PURPOSE. You are solely responsible for determining the
150
+ appropriateness of using or redistributing the Work and assume any
151
+ risks associated with Your exercise of permissions under this License.
152
+
153
+ 8. Limitation of Liability. In no event and under no legal theory,
154
+ whether in tort (including negligence), contract, or otherwise,
155
+ unless required by applicable law (such as deliberate and grossly
156
+ negligent acts) or agreed to in writing, shall any Contributor be
157
+ liable to You for damages, including any direct, indirect, special,
158
+ incidental, or consequential damages of any character arising as a
159
+ result of this License or out of the use or inability to use the
160
+ Work (including but not limited to damages for loss of goodwill,
161
+ work stoppage, computer failure or malfunction, or any and all
162
+ other commercial damages or losses), even if such Contributor
163
+ has been advised of the possibility of such damages.
164
+
165
+ 9. Accepting Warranty or Additional Liability. While redistributing
166
+ the Work or Derivative Works thereof, You may choose to offer,
167
+ and charge a fee for, acceptance of support, warranty, indemnity,
168
+ or other liability obligations and/or rights consistent with this
169
+ License. However, in accepting such obligations, You may act only
170
+ on Your own behalf and on Your sole responsibility, not on behalf
171
+ of any other Contributor, and only if You agree to indemnify,
172
+ defend, and hold each Contributor harmless for any liability
173
+ incurred by, or claims asserted against, such Contributor by reason
174
+ of your accepting any such warranty or additional liability.
175
+
176
+ END OF TERMS AND CONDITIONS
177
+
178
+ APPENDIX: How to apply the Apache License to your work.
179
+
180
+ To apply the Apache License to your work, attach the following
181
+ boilerplate notice, with the fields enclosed by brackets "[]"
182
+ replaced with your own identifying information. (Don't include
183
+ the brackets!) The text should be enclosed in the appropriate
184
+ comment syntax for the file format. We also recommend that a
185
+ file or class name and description of purpose be included on the
186
+ same "printed page" as the copyright notice for easier
187
+ identification within third-party archives.
188
+
189
+ Copyright 2026 Mat Woolf
190
+
191
+ Licensed under the Apache License, Version 2.0 (the "License");
192
+ you may not use this file except in compliance with the License.
193
+ You may obtain a copy of the License at
194
+
195
+ http://www.apache.org/licenses/LICENSE-2.0
196
+
197
+ Unless required by applicable law or agreed to in writing, software
198
+ distributed under the License is distributed on an "AS IS" BASIS,
199
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
200
+ See the License for the specific language governing permissions and
201
+ limitations under the License.
package/README.md CHANGED
@@ -1,3 +1,32 @@
1
- # Temporary Holding Version
1
+ # @matatbread/matbot-host-node
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ What a Node application needs to embed [matbot](https://github.com/MatAtBread/matbot) that
4
+ `@matatbread/matbot-core` cannot hold, because it uses Node APIs and core must also run in a browser. Not a
5
+ plugin: an application building a machine with `assembleMachine` imports these and passes them in. Nothing
6
+ here assumes a config file, a directory layout or how plugins are acquired; each takes the path or
7
+ directory it works on.
8
+
9
+ **`@matatbread/matbot-host-node/register`** — start the application with
10
+ `node --import @matatbread/matbot-host-node/register app.ts`. matbot's packages are published as TypeScript
11
+ source, so this registers the two module hooks Node needs to load them: a `.js` import resolves to the `.ts`
12
+ file, and types are stripped under `node_modules` too, where Node refuses to. A host with hooks of its own
13
+ registers the pair from **`/typescript-hooks`** (`typescriptHooks()`) beneath them, as the matbot CLI does.
14
+
15
+ **`@matatbread/matbot-host-node`**:
16
+
17
+ - `createAlsPrincipalCarrier`, `createAlsUsageCarrier` — `AsyncLocalStorage` carriers, so concurrent
18
+ requests and turns each keep their own principal and token accounting. Install them before anything
19
+ reads one, then `runAs(principal, …)` at each entry point (a request handler, a message). core's
20
+ `createConstantPrincipalCarrier` is the alternative for a single-principal process.
21
+ - `nodePluginMembers(machine, baseDir)` — `loadPlugin`, `unloadPlugin`, `resolver` and
22
+ `TypeScriptStripper` for a host that loads plugins already on disk: a path (relative to `baseDir`), or a
23
+ package installed where `baseDir` resolves. Nothing is fetched or installed. A host that acquires
24
+ plugins itself resolves each specifier its own way and loads the result with
25
+ `loadPluginsWithDescriptions`; `nodePluginResolver`, `readPluginMeta` and `backfillPluginDescription`
26
+ are the other pieces the matbot CLI builds its own loading from.
27
+ - `EnvFileVault.open(path, env?)` — a vault persisted to an environment file. Values are plaintext,
28
+ readable by anything that can read the file. `parseEnvFile`/`readEnvFile` read the same format.
29
+
30
+ Storage is a plugin's: `@matatbread/matbot-storage-filesystem` exports `FilesystemStorageBackend` for a
31
+ host to boot on, and core's `MemoryStorageBackend` (`@matatbread/matbot-core/storage-base`) persists
32
+ nothing.
package/package.json CHANGED
@@ -1,6 +1,43 @@
1
1
  {
2
2
  "name": "@matatbread/matbot-host-node",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.5.0",
4
+ "engines": {
5
+ "node": ">=24.0.0"
6
+ },
7
+ "files": [
8
+ "src"
9
+ ],
10
+ "description": "What a Node application needs to embed matbot that core cannot hold, being Node-only: AsyncLocalStorage principal and usage carriers, the module hooks that load matbot's TypeScript-source packages, plugin loading from disk, and a .env-file vault.",
11
+ "keywords": [
12
+ "matbot",
13
+ "llm",
14
+ "ai",
15
+ "agent"
16
+ ],
17
+ "license": "Apache-2.0",
18
+ "type": "module",
19
+ "exports": {
20
+ ".": "./src/index.ts",
21
+ "./register": "./src/register.js",
22
+ "./typescript-hooks": "./src/typescript-hooks.js"
23
+ },
24
+ "repository": {
25
+ "type": "git",
26
+ "url": "git+https://github.com/MatAtBread/matbot.git",
27
+ "directory": "host-node"
28
+ },
29
+ "publishConfig": {
30
+ "access": "public"
31
+ },
32
+ "peerDependencies": {
33
+ "@matatbread/matbot-core": "^0.5.0"
34
+ },
35
+ "devDependencies": {
36
+ "@types/node": "^22.0.0",
37
+ "typescript": "^6.0.3",
38
+ "@matatbread/matbot-core": "^0.5.0"
39
+ },
40
+ "scripts": {
41
+ "typecheck": "tsc --noEmit"
42
+ }
6
43
  }
@@ -0,0 +1,89 @@
1
+ import { VaultImpl } from '@matatbread/matbot-core';
2
+ import { readFile, writeFile } from 'node:fs/promises';
3
+
4
+ /**
5
+ * A vault persisted to an environment file (`NAME=value` lines): secrets stored at runtime survive a
6
+ * restart. The values are plaintext, readable by anything that can read the file — a shell tool included.
7
+ *
8
+ * It reads and writes its own file, so the two cannot disagree about the format: a value is written in the
9
+ * form {@link parseEnvFile} reads back unchanged, quoted where it would otherwise be reinterpreted (a ` #`
10
+ * read as a comment, surrounding quotes or whitespace stripped), and one it cannot represent (a line break)
11
+ * is refused rather than written broken.
12
+ *
13
+ * Persistence hooks the write primitive, not createSecret — so the reference and dedup paths of
14
+ * createSecret (which never call writeSecret) never append a dead line to the file.
15
+ *
16
+ * The file may also be read as an environment file by whatever starts the process (a systemd
17
+ * `EnvironmentFile=`), so the name policy is narrower than the base vault's: anything else is written,
18
+ * accepted, and then dropped by such a reader with at most a log line nobody sees.
19
+ */
20
+ export class EnvFileVault extends VaultImpl {
21
+ private readonly envPath: string;
22
+
23
+ /** The vault over `envPath`, holding what the file holds; `env` (say `process.env`) wins over it. */
24
+ static async open(envPath: string, env?: Record<string, string | undefined>): Promise<EnvFileVault> {
25
+ return new EnvFileVault(envPath, { ...await readEnvFile(envPath), ...env });
26
+ }
27
+
28
+ /** Over `envPath`, holding exactly `env`: the file is written to, never read. {@link open} reads it. */
29
+ constructor(envPath: string, env?: Record<string, string | undefined>) {
30
+ super({}, env);
31
+ this.envPath = envPath;
32
+ }
33
+
34
+ override unstorableKey(name: string): string | undefined {
35
+ return /^[A-Za-z_][A-Za-z0-9_]*$/.test(name)
36
+ ? undefined
37
+ : 'this vault persists to a .env file, so a secret name must be a valid environment-variable name: a letter or underscore, then letters, digits or underscores only (e.g. ACME_EMAIL_PASSWORD)';
38
+ }
39
+
40
+ override async writeSecret(name: string, value: string): Promise<void> {
41
+ if (/[\r\n]/.test(value)) throw new Error(`Secret "${name}" contains a line break, which a .env file cannot hold`);
42
+ await super.writeSecret(name, value);
43
+
44
+ let existing = '';
45
+ try { existing = await readFile(this.envPath, 'utf8'); } catch { /* no file yet */ }
46
+ const lines = existing
47
+ ? existing.split('\n').filter(l => l !== '' && !l.startsWith(`${name}=`))
48
+ : [];
49
+ if (value !== '') lines.push(`${name}=${envValue(value)}`);
50
+ await writeFile(this.envPath, lines.length ? lines.join('\n') + '\n' : '', 'utf8');
51
+ }
52
+ }
53
+
54
+ // Bare where the reader would return it unchanged; otherwise quoted, which the reader strips and nothing else.
55
+ function envValue(value: string): string {
56
+ const bare = value === value.trim() && !/\s#/.test(value) && !/^(["']).*\1$/s.test(value);
57
+ if (bare) return value;
58
+ return value.includes("'") ? `"${value}"` : `'${value}'`;
59
+ }
60
+
61
+ /** The `NAME=value` lines of an environment file: `#` comments, an optional `export `, and a value either
62
+ * quoted (the quotes stripped) or bare (a trailing ` # comment` and surrounding whitespace dropped). */
63
+ export function parseEnvFile(text: string): Record<string, string> {
64
+ const out: Record<string, string> = {};
65
+ for (const raw of text.split('\n')) {
66
+ const line = raw.trim();
67
+ if (!line || line.startsWith('#')) continue;
68
+ const stripped = line.startsWith('export ') ? line.slice(7).trimStart() : line;
69
+ const eq = stripped.indexOf('=');
70
+ if (eq === -1) continue;
71
+ const key = stripped.slice(0, eq).trimEnd();
72
+ if (!key) continue;
73
+ let val = stripped.slice(eq + 1);
74
+ if (val.length >= 2 && ((val.startsWith('"') && val.endsWith('"')) || (val.startsWith("'") && val.endsWith("'")))) {
75
+ val = val.slice(1, -1);
76
+ } else {
77
+ const commentIdx = val.search(/\s+#/);
78
+ if (commentIdx !== -1) val = val.slice(0, commentIdx);
79
+ val = val.trim();
80
+ }
81
+ out[key] = val;
82
+ }
83
+ return out;
84
+ }
85
+
86
+ /** {@link parseEnvFile} of the file at `envPath`; an absent or unreadable file holds nothing. */
87
+ export async function readEnvFile(envPath: string): Promise<Record<string, string>> {
88
+ try { return parseEnvFile(await readFile(envPath, 'utf8')); } catch { return {}; }
89
+ }
package/src/index.ts ADDED
@@ -0,0 +1,7 @@
1
+ export { createAlsPrincipalCarrier } from './principal-als.js';
2
+ export { createAlsUsageCarrier } from './usage-als.js';
3
+ export { EnvFileVault, parseEnvFile, readEnvFile } from './env-vault.js';
4
+ export { nodePluginResolver } from './plugin-resolver.js';
5
+ export { loadPluginsWithDescriptions, readPluginMeta, backfillPluginDescription } from './plugin-description.js';
6
+ export type { PluginLoadRequest } from './plugin-description.js';
7
+ export { nodePluginMembers, nodeTypeScriptStripper } from './plugin-members.js';
@@ -0,0 +1,125 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { fileURLToPath, pathToFileURL } from 'node:url';
3
+ import { createRequire } from 'node:module';
4
+ import path from 'node:path';
5
+ import { loadPlugins } from '@matatbread/matbot-core';
6
+ import type { MatbotPlugin, PluginManifest, MatbotMachine, PromptFn, Runtime } from '@matatbread/matbot-core';
7
+
8
+ /**
9
+ * A fully host-resolved plugin load request. The CLI resolves a config/human specifier (`spec`) to
10
+ * the URL it actually imports (`importSpec`) and reads the resolved package.json for `name`/`runtimes`,
11
+ * so the loader records `spec` as `plugin.specifier` (matching matbot.yaml) while importing `importSpec`.
12
+ */
13
+ export interface PluginLoadRequest {
14
+ spec: string;
15
+ importSpec: string;
16
+ name?: string;
17
+ version?: string;
18
+ runtimes?: readonly Runtime[];
19
+ /** Resolution-time findings the loader appends to a failure it records for this spec. */
20
+ notes?: readonly string[];
21
+ }
22
+
23
+ // Where to begin the upward package.json search for a load specifier. Specifiers that
24
+ // reach the runtime are file: URLs (resolved by the CLI before registration); install-time
25
+ // specifiers may be relative paths or bare npm names. A bare name is resolved through the
26
+ // project's module graph, which only works once the package is actually on disk.
27
+ export function startDir(specifier: string, baseDir: string): string | undefined {
28
+ const bare = (specifier.split('?')[0]) ?? specifier;
29
+ if (bare.startsWith('file://')) return path.dirname(fileURLToPath(bare));
30
+ if (bare.startsWith('./') || bare.startsWith('../') || path.isAbsolute(bare)) {
31
+ return path.resolve(baseDir, bare);
32
+ }
33
+ try {
34
+ const require = createRequire(pathToFileURL(path.join(baseDir, 'index.js')).href);
35
+ return path.dirname(require.resolve(bare));
36
+ } catch {
37
+ return undefined;
38
+ }
39
+ }
40
+
41
+ async function descriptionFromPackageJson(specifier: string, baseDir: string): Promise<string | undefined> {
42
+ let dir = startDir(specifier, baseDir);
43
+ if (dir === undefined) return undefined;
44
+ while (true) {
45
+ try {
46
+ const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { description?: string };
47
+ if (pkg.description) return pkg.description;
48
+ } catch { /* no package.json here, keep walking up */ }
49
+ const parent = path.dirname(dir);
50
+ if (parent === dir) return undefined;
51
+ dir = parent;
52
+ }
53
+ }
54
+
55
+ /**
56
+ * Read the canonical name (+ optional version and matbotRuntime) from the package.json governing a
57
+ * resolved import URL — the node analogue of the web assembler's specNames. Walks up to the first
58
+ * package.json carrying a `name` (a nameless intermediate is not the plugin's manifest), so the CLI can
59
+ * hand the loader a precomputed identity and `plugin.specifier` can stay the human/config specifier.
60
+ *
61
+ * The version comes from here for the same reason the name does: the resolver's own lookup starts from
62
+ * the config specifier, which for a bare name, a URL or a version range reaches no manifest.
63
+ */
64
+ export async function readPluginMeta(specifier: string, baseDir: string): Promise<{ name?: string; version?: string; runtimes?: Runtime[] }> {
65
+ let dir = startDir(specifier, baseDir);
66
+ if (dir === undefined) return {};
67
+ while (true) {
68
+ try {
69
+ const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { name?: string; version?: unknown; matbotRuntime?: unknown };
70
+ if (typeof pkg.name === 'string') {
71
+ const runtimes = Array.isArray(pkg.matbotRuntime)
72
+ ? pkg.matbotRuntime.filter((r): r is Runtime => typeof r === 'string')
73
+ : undefined;
74
+ return {
75
+ name: pkg.name,
76
+ ...(typeof pkg.version === 'string' ? { version: pkg.version } : {}),
77
+ ...(runtimes !== undefined ? { runtimes } : {}),
78
+ };
79
+ }
80
+ } catch { /* no package.json here, keep walking up */ }
81
+ const parent = path.dirname(dir);
82
+ if (parent === dir) return {};
83
+ dir = parent;
84
+ }
85
+ }
86
+
87
+ // Fill in plugin.manifest.description from the plugin's package.json, unless the plugin
88
+ // already declares a description. Presence is checked with `in` so a getter (a description
89
+ // computed at read time from some condition) counts as declared and is left untouched —
90
+ // we never read it, only observe that it exists.
91
+ export async function backfillPluginDescription(
92
+ plugin: MatbotPlugin,
93
+ specifier: string,
94
+ baseDir: string,
95
+ ): Promise<void> {
96
+ if (plugin.manifest !== undefined && 'description' in plugin.manifest) return;
97
+ const description = await descriptionFromPackageJson(specifier, baseDir);
98
+ if (description === undefined) return;
99
+ if (plugin.manifest !== undefined) {
100
+ (plugin.manifest as { description?: string }).description = description;
101
+ } else {
102
+ (plugin as { manifest?: PluginManifest }).manifest = { description };
103
+ }
104
+ }
105
+
106
+ // loadPlugins lives in the platform-neutral runner and so cannot read package.json itself.
107
+ // This wrapper is the Node entry point: every CLI plugin load goes through it, so a freshly
108
+ // loaded plugin always has its package.json description folded into its manifest. baseDir is
109
+ // the project directory (where package.json paths and node_modules resolve from).
110
+ export async function loadPluginsWithDescriptions(
111
+ requests: readonly PluginLoadRequest[],
112
+ services: MatbotMachine,
113
+ baseDir: string,
114
+ bustCache = false,
115
+ prompt?: PromptFn,
116
+ onLoadError: 'skip' | 'throw' = 'skip',
117
+ ): Promise<MatbotPlugin[]> {
118
+ const plugins = await loadPlugins(requests, services, bustCache, prompt, onLoadError);
119
+ // plugin.specifier is the config-level `spec`; the package.json lives at the resolved importSpec.
120
+ const importByCfg = new Map(requests.map(r => [r.spec, r.importSpec]));
121
+ for (const plugin of plugins) {
122
+ await backfillPluginDescription(plugin, importByCfg.get(plugin.specifier) ?? plugin.specifier, baseDir);
123
+ }
124
+ return plugins;
125
+ }
@@ -0,0 +1,112 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import { createRequire, stripTypeScriptTypes } from 'node:module';
3
+ import { fileURLToPath, pathToFileURL } from 'node:url';
4
+ import path from 'node:path';
5
+ import { getPluginNameForSpecifier, getRegisteredPlugins, unloadPlugin } from '@matatbread/matbot-core';
6
+ import type { HostMembers, MatbotMachine, MatbotPlugin, PromptFn } from '@matatbread/matbot-core';
7
+ import { loadPluginsWithDescriptions, readPluginMeta, type PluginLoadRequest } from './plugin-description.js';
8
+ import { nodePluginResolver } from './plugin-resolver.js';
9
+
10
+ /**
11
+ * Given a package exports field (or any nested value), return the first
12
+ * string entry point, preferring "import" > "default" > first value.
13
+ */
14
+ function resolveExportsEntry(value: unknown): string | undefined {
15
+ if (typeof value === 'string') return value;
16
+ if (typeof value !== 'object' || value === null) return undefined;
17
+ const obj = value as Record<string, unknown>;
18
+ // Subpath map: { ".": ... } → unwrap the "." entry
19
+ if ('.' in obj) return resolveExportsEntry(obj['.']);
20
+ // Condition map: prefer import > default > first
21
+ for (const key of ['import', 'default', ...Object.keys(obj)]) {
22
+ if (key in obj) return resolveExportsEntry(obj[key]);
23
+ }
24
+ return undefined;
25
+ }
26
+
27
+ /** The import URL of a package directory: its `exports["."]` entry, else the directory itself. So config
28
+ * can name the package folder rather than a deep `src/` path. */
29
+ export async function packageEntry(dir: string): Promise<string> {
30
+ try {
31
+ const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as Record<string, unknown>;
32
+ const main = resolveExportsEntry(pkg['exports']);
33
+ if (typeof main === 'string') return pathToFileURL(path.resolve(dir, main)).href;
34
+ } catch { /* no package.json or unparseable — import the directory */ }
35
+ return pathToFileURL(dir).href;
36
+ }
37
+
38
+ /** The import URL of an installed package, resolved from each of `fromDirs` in turn; undefined when none
39
+ * has it on disk. */
40
+ export function installedEntry(spec: string, fromDirs: readonly string[]): string | undefined {
41
+ for (const dir of fromDirs) {
42
+ try { return pathToFileURL(createRequire(path.join(dir, '_')).resolve(spec)).href; } catch { /* try the next */ }
43
+ }
44
+ return undefined;
45
+ }
46
+
47
+ /** A load request for `importSpec`, carrying the name, version and runtimes its package.json declares. */
48
+ export async function loadRequest(spec: string, importSpec: string, baseDir: string): Promise<PluginLoadRequest> {
49
+ const meta = await readPluginMeta(importSpec, baseDir);
50
+ return {
51
+ spec,
52
+ importSpec,
53
+ ...(meta.name !== undefined ? { name: meta.name } : {}),
54
+ ...(meta.version !== undefined ? { version: meta.version } : {}),
55
+ ...(meta.runtimes !== undefined ? { runtimes: meta.runtimes } : {}),
56
+ };
57
+ }
58
+
59
+ /**
60
+ * Resolve a plugin that is already where Node can import it: a path (relative to `baseDir`), or a package
61
+ * installed where `baseDir` resolves. Nothing is fetched or installed — that is acquisition, which is the
62
+ * host's own (the CLI's is in `apps/cli/src/plugins`). A specifier that resolves to nothing passes
63
+ * through, so the loader reports it.
64
+ */
65
+ export async function resolveInstalledPlugin(spec: string, baseDir: string): Promise<PluginLoadRequest> {
66
+ const bare = (spec.split('?')[0]) ?? spec;
67
+ if (bare.startsWith('file://') || bare.startsWith('./') || bare.startsWith('../') || path.isAbsolute(bare)) {
68
+ const dir = bare.startsWith('file://') ? fileURLToPath(bare) : path.resolve(baseDir, bare);
69
+ return loadRequest(spec, await packageEntry(dir), baseDir);
70
+ }
71
+ const entry = installedEntry(spec, [baseDir]);
72
+ return entry !== undefined ? loadRequest(spec, entry, baseDir) : { spec, importSpec: spec };
73
+ }
74
+
75
+ /** Unload by the specifier a plugin was loaded with, or by its canonical name. */
76
+ export async function unloadNodePlugin(specifier: string, machine: MatbotMachine): Promise<boolean> {
77
+ const name = getPluginNameForSpecifier(specifier)
78
+ ?? (getRegisteredPlugins().some(p => p.name === specifier) ? specifier : undefined);
79
+ if (name === undefined) {
80
+ console.warn(`[matbot] No loaded plugin found for "${specifier}"`);
81
+ return false;
82
+ }
83
+ return unloadPlugin(name, machine);
84
+ }
85
+
86
+ /** Node's own type stripper: blanks types in place, so line numbers survive. */
87
+ export const nodeTypeScriptStripper: NonNullable<HostMembers['TypeScriptStripper']> = {
88
+ strip: (source: string) => stripTypeScriptTypes(source),
89
+ };
90
+
91
+ /**
92
+ * The plugin-loading members of a Node host that loads only what is already on disk — a matbot embedded
93
+ * in an application, with a fixed set of plugins and no `plugin` tool. A host that acquires plugins (the
94
+ * CLI) resolves through acquisition instead, and builds its own `loadPlugin` from the same pieces.
95
+ */
96
+ export function nodePluginMembers(
97
+ machine: () => MatbotMachine, baseDir: string,
98
+ ): Pick<HostMembers, 'loadPlugin' | 'unloadPlugin' | 'resolver' | 'TypeScriptStripper' | 'projectDir'> {
99
+ return {
100
+ async loadPlugin(specifier: string, prompt?: PromptFn): Promise<MatbotPlugin> {
101
+ const request = await resolveInstalledPlugin(specifier, baseDir);
102
+ const plugin = (await loadPluginsWithDescriptions([request], machine(), baseDir, /* bustCache */ false, prompt, /* onLoadError */ 'throw'))[0];
103
+ if (plugin === undefined) throw new Error(`No plugin loaded for specifier "${specifier}"`);
104
+ return plugin;
105
+ },
106
+ unloadPlugin: (specifier: string) => unloadNodePlugin(specifier, machine()),
107
+ resolver: nodePluginResolver(baseDir),
108
+ TypeScriptStripper: nodeTypeScriptStripper,
109
+ // What relative specifiers resolve from is what a plugin writing code for this host to load needs.
110
+ projectDir: baseDir,
111
+ };
112
+ }
@@ -0,0 +1,89 @@
1
+ import { readFile } from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import type { PluginResolver, Runtime } from '@matatbread/matbot-core';
4
+ import { startDir } from './plugin-description.js';
5
+
6
+ const VALID_RUNTIMES: readonly Runtime[] = ['node', 'browser'];
7
+
8
+ /** Coerce a raw package.json `matbotRuntime` value into a runtime list, or undefined if absent/malformed. */
9
+ function normalizeRuntimes(raw: unknown, pkgName: string): readonly Runtime[] | undefined {
10
+ if (raw === undefined) return undefined;
11
+ if (!Array.isArray(raw)) {
12
+ console.warn(`[matbot] Ignoring matbotRuntime in "${pkgName}": expected an array of ${VALID_RUNTIMES.join('/')}, got ${typeof raw}.`);
13
+ return undefined;
14
+ }
15
+ const valid = raw.filter((r): r is Runtime => VALID_RUNTIMES.includes(r as Runtime));
16
+ for (const r of raw) {
17
+ if (!VALID_RUNTIMES.includes(r as Runtime)) {
18
+ console.warn(`[matbot] Ignoring unknown matbotRuntime "${String(r)}" in "${pkgName}" (known: ${VALID_RUNTIMES.join(', ')}).`);
19
+ }
20
+ }
21
+ return valid;
22
+ }
23
+
24
+ /**
25
+ * Node host PluginResolver: derives a plugin's canonical name (its package.json `name`) from the
26
+ * specifier it was loaded with. This is the single source of plugin identity on the node host —
27
+ * the loader calls identify() to stamp `MatbotPlugin.name`, so authors no longer hand-declare it.
28
+ *
29
+ * A bare npm name is already the package name and passes through. A path / file: URL is resolved to
30
+ * a start directory and the nearest package.json walked up to; its `name` wins, falling back to the
31
+ * directory's basename if no package.json carries one.
32
+ */
33
+ export function nodePluginResolver(baseDir: string): PluginResolver {
34
+ return {
35
+ async identify(specifier: string): Promise<string> {
36
+ const bare = (specifier.split('?')[0]) ?? specifier;
37
+ const isPathLike = bare.startsWith('file://') || bare.startsWith('./') ||
38
+ bare.startsWith('../') || path.isAbsolute(bare);
39
+ if (!isPathLike) return specifier; // bare npm name — already the package name
40
+
41
+ let dir = startDir(specifier, baseDir);
42
+ if (dir === undefined) return specifier;
43
+ const fallback = path.basename(dir);
44
+
45
+ while (true) {
46
+ try {
47
+ const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { name?: string };
48
+ if (pkg.name) return pkg.name;
49
+ } catch { /* no package.json here, keep walking up */ }
50
+ const parent = path.dirname(dir);
51
+ if (parent === dir) return fallback; // filesystem root reached without a named package.json
52
+ dir = parent;
53
+ }
54
+ },
55
+
56
+ // Read `version` off the plugin's package.json — the nearest named one, the same boundary
57
+ // identify() uses. Undefined when unreadable (no package.json / no version field).
58
+ async version(specifier: string): Promise<string | undefined> {
59
+ let dir = startDir(specifier, baseDir);
60
+ if (dir === undefined) return undefined;
61
+ while (true) {
62
+ try {
63
+ const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { name?: string; version?: string };
64
+ if (pkg.name) return pkg.version;
65
+ } catch { /* no package.json here, keep walking up */ }
66
+ const parent = path.dirname(dir);
67
+ if (parent === dir) return undefined;
68
+ dir = parent;
69
+ }
70
+ },
71
+
72
+ // Read `matbotRuntime` off the plugin's package.json — the nearest one with a `name`, the same
73
+ // boundary identify() uses — so a declaration on the plugin (not an enclosing monorepo root) wins.
74
+ // Undefined means "not declared": the loader then imports and falls back to load/rollback.
75
+ async runtimes(specifier: string): Promise<readonly Runtime[] | undefined> {
76
+ let dir = startDir(specifier, baseDir);
77
+ if (dir === undefined) return undefined;
78
+ while (true) {
79
+ try {
80
+ const pkg = JSON.parse(await readFile(path.join(dir, 'package.json'), 'utf8')) as { name?: string; matbotRuntime?: unknown };
81
+ if (pkg.name) return normalizeRuntimes(pkg.matbotRuntime, pkg.name);
82
+ } catch { /* no package.json here, keep walking up */ }
83
+ const parent = path.dirname(dir);
84
+ if (parent === dir) return undefined;
85
+ dir = parent;
86
+ }
87
+ },
88
+ };
89
+ }
@@ -0,0 +1,29 @@
1
+ import { AsyncLocalStorage } from 'node:async_hooks';
2
+ import type { Principal, PrincipalCarrier } from '@matatbread/matbot-core';
3
+
4
+ /**
5
+ * Node `PrincipalCarrier` backed by `AsyncLocalStorage`. Each `run`/`enter` scope is isolated per
6
+ * async flow, so the many concurrent per-session `pump` loops (and per-request frontend handlers)
7
+ * each carry their own principal without leaking into one another — the multi-user case ALS exists
8
+ * for. The browser counterpart is `createConstantPrincipalCarrier` (single principal, no isolation).
9
+ */
10
+ export function createAlsPrincipalCarrier(): PrincipalCarrier {
11
+ const als = new AsyncLocalStorage<Principal>();
12
+ return {
13
+ current(): Principal {
14
+ const p = als.getStore();
15
+ if (p === undefined) {
16
+ throw new Error('No principal in context — currentPrincipal() called outside any runAs/enter scope.');
17
+ }
18
+ return p;
19
+ },
20
+ tryCurrent: () => als.getStore(),
21
+ run: (principal, fn) => als.run(principal, fn),
22
+ enter(principal): void {
23
+ if (als.getStore() !== undefined) {
24
+ throw new Error('A principal is already established — enter() is for entry points; use runAs for nested/delegated scopes.');
25
+ }
26
+ als.enterWith(principal);
27
+ },
28
+ };
29
+ }
@@ -0,0 +1,9 @@
1
+ // `node --import @matatbread/matbot-host-node/register app.ts` — what an application needs before it can
2
+ // import matbot's packages, which are published as TypeScript source. See typescript-hooks.js.
3
+ //
4
+ // In-thread, through `registerHooks()`: `register()` runs hooks on a thread of their own, which since Node
5
+ // 24.12 costs a round trip for every resolve and load, and is deprecated (DEP0205).
6
+ import { registerHooks } from 'node:module';
7
+ import { typescriptHooks } from './typescript-hooks.js';
8
+
9
+ registerHooks(typescriptHooks());
@@ -0,0 +1,5 @@
1
+ import type { ResolveHookSync, LoadHookSync } from 'node:module';
2
+
3
+ /** The resolve (`.js` import → `.ts` file) and load (strip types, under node_modules too) hooks that loading
4
+ * matbot's TypeScript-source packages needs, for a host registering them alongside hooks of its own. */
5
+ export function typescriptHooks(): { resolve: ResolveHookSync; load: LoadHookSync };
@@ -0,0 +1,46 @@
1
+ // The two Node module hooks that loading matbot's packages needs. They are published as TypeScript source
2
+ // importing `./x.js` where the file on disk is `./x.ts`, and Node, which strips types itself, does neither
3
+ // half of that: it does not try `.ts` for a `.js` import, and it refuses to strip anything under
4
+ // node_modules (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING), which is where every package lives once
5
+ // installed. `register.js` beside this registers them; a host composing hooks of its own takes them here.
6
+ //
7
+ // Plain JavaScript with declarations beside it, for the same reason as cache-layout.js: this IS the type
8
+ // stripper, so it cannot itself be a `.ts`.
9
+ //
10
+ // Which of the two is tried first depends on who is importing. From a `.ts` file, `./x.js` is TypeScript's
11
+ // spelling of the sibling `./x.ts`, so that is tried first — matbot's own source is hundreds of such imports,
12
+ // and failing a `.js` lookup before each is a measurable share of a boot. From anything else the `.js` is
13
+ // tried first, so a package that ships compiled output is never shadowed by source it also ships.
14
+ // `require()` passes through untouched: CommonJS has its own rules, and a `.ts` it loads is not an ES
15
+ // module by fiat. A query string (a reload's cache-buster) is not part of the file name.
16
+ import { stripTypeScriptTypes } from 'node:module';
17
+ import { readFileSync } from 'node:fs';
18
+ import { fileURLToPath } from 'node:url';
19
+
20
+ const isRequire = context => context.conditions?.includes('require') ?? false;
21
+ const TS_FILE = /^file:[^?#]*\.[cm]?ts(?:[?#].*)?$/;
22
+
23
+ export function typescriptHooks() {
24
+ return {
25
+ resolve(specifier, context, nextResolve) {
26
+ if (isRequire(context) || !specifier.endsWith('.js')) return nextResolve(specifier, context);
27
+ const ts = specifier.slice(0, -3) + '.ts';
28
+ if (TS_FILE.test(context.parentURL ?? '')) {
29
+ try { return nextResolve(ts, context); }
30
+ catch { return nextResolve(specifier, context); }
31
+ }
32
+ try {
33
+ return nextResolve(specifier, context);
34
+ } catch (e) {
35
+ if (e?.code !== 'ERR_MODULE_NOT_FOUND') throw e;
36
+ try { return nextResolve(ts, context); }
37
+ catch { throw e; }
38
+ }
39
+ },
40
+ load(url, context, nextLoad) {
41
+ if (isRequire(context) || !TS_FILE.test(url)) return nextLoad(url, context);
42
+ const source = readFileSync(fileURLToPath(url.replace(/[?#].*$/, '')), 'utf8');
43
+ return { format: 'module', source: stripTypeScriptTypes(source, { mode: 'strip', sourceUrl: url }), shortCircuit: true };
44
+ },
45
+ };
46
+ }
@@ -0,0 +1,16 @@
1
+ import { AsyncLocalStorage } from 'node:async_hooks';
2
+ import type { UsageCarrier, UsageScope } from '@matatbread/matbot-core';
3
+
4
+ /**
5
+ * Node `UsageCarrier` backed by `AsyncLocalStorage`. Each turn's `withUsageScope` runs in its own
6
+ * isolated scope, so the concurrent per-session `pump` loops accrue token accounting independently —
7
+ * a completion run inside one turn's tool never lands in another's tally. The browser counterpart is
8
+ * `createSerialUsageCarrier` (single scope, no async isolation).
9
+ */
10
+ export function createAlsUsageCarrier(): UsageCarrier {
11
+ const als = new AsyncLocalStorage<UsageScope>();
12
+ return {
13
+ run: (scope, fn) => als.run(scope, fn),
14
+ tryCurrent: () => als.getStore(),
15
+ };
16
+ }