@axiom-lattice/core 13.0.0 → 13.0.2

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/dist/index.mjs CHANGED
@@ -54462,11 +54462,25 @@ var PLUGIN_JSON_TEMPLATE = `{
54462
54462
  `;
54463
54463
  var HANDLER_TEMPLATE = `const fs = require("fs");
54464
54464
 
54465
- const input = process.env.PLUGIN_INPUT
54466
- ? JSON.parse(Buffer.from(process.env.PLUGIN_INPUT, "base64").toString("utf8"))
54467
- : process.env.PLUGIN_INPUT_FILE
54468
- ? JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"))
54469
- : undefined;
54465
+ function readInput() {
54466
+ if (process.env.PLUGIN_INPUT_FILE) {
54467
+ // Large input: the executor writes plain JSON to a file.
54468
+ return JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"));
54469
+ }
54470
+ const raw = process.env.PLUGIN_INPUT;
54471
+ if (!raw) return {};
54472
+ try {
54473
+ return JSON.parse(raw); // manual/debug plaintext
54474
+ } catch (plainErr) {
54475
+ try {
54476
+ return JSON.parse(Buffer.from(raw, "base64").toString("utf8")); // executor
54477
+ } catch (base64Err) {
54478
+ throw new Error("cannot parse PLUGIN_INPUT as JSON or base64 JSON: " + plainErr.message);
54479
+ }
54480
+ }
54481
+ }
54482
+
54483
+ const input = readInput();
54470
54484
  const data = process.env.PLUGIN_CONNECTION_FILE
54471
54485
  ? JSON.parse(fs.readFileSync(process.env.PLUGIN_CONNECTION_FILE, "utf8"))
54472
54486
  : {};
@@ -55112,6 +55126,45 @@ const client = new OpenMcpClient({
55112
55126
  \`OPEN_API_TOKEN\` is **not** injected for plugin handlers. If you find yourself
55113
55127
  calling \`fromEnv()\` in a plugin handler, stop and switch to the connection key.
55114
55128
 
55129
+ ## \`OPEN_API_TOKEN\` is empty on purpose
55130
+
55131
+ The executor clears \`OPEN_API_TOKEN\` before running a plugin handler. An empty
55132
+ value is the expected contract, not a misconfiguration: never read it, never
55133
+ \`fromEnv()\`, and never ask a human to "restore" it. The handler's only platform
55134
+ credential is the password field from \`connection.fields\`.
55135
+ (\`code_eval\` / the builder's own \`shell_exec\` may receive a short-lived,
55136
+ self-bound \`OPEN_API_TOKEN\`; it is not a plugin key and must not be reused.)
55137
+
55138
+ ## \`API_GATEWAY_URL\` is injected, but may be empty
55139
+
55140
+ \`API_GATEWAY_URL\` is **not** tied to \`OPEN_API_TOKEN\`: the Gateway injects it into
55141
+ every plugin handler (short-process and resident) from the deployment's
55142
+ \`PUBLIC_GATEWAY_URL\`. It exists only when the Gateway process has that env set.
55143
+ \`shell_exec\` / \`code_eval\` use the same \`PUBLIC_GATEWAY_URL\` seam.
55144
+
55145
+ If it is empty, stop and ask a human \u2014 do **not** loop, guess a host, or blindly
55146
+ try \`localhost\`:
55147
+
55148
+ \`\`\`js
55149
+ if (!process.env.API_GATEWAY_URL) {
55150
+ process.stdout.write(JSON.stringify({
55151
+ ok: false,
55152
+ error: "API_GATEWAY_URL is empty: ask a human to set PUBLIC_GATEWAY_URL on the Gateway",
55153
+ }));
55154
+ return;
55155
+ }
55156
+ \`\`\`
55157
+
55158
+ Recovery order:
55159
+ 1. Ask the platform operator to set \`PUBLIC_GATEWAY_URL\` on the Gateway to a URL
55160
+ the sandbox can reach (LB/public domain; \`host.docker.internal:<port>\` for
55161
+ local containers; \`localhost:<port>\` only when the sandbox shares the host
55162
+ network), then restart the Gateway.
55163
+ 2. Only if the deployment will not set it, add a \`gatewayUrl\` string field to
55164
+ \`connection.fields\` and use
55165
+ \`const base = process.env.API_GATEWAY_URL || conn.gatewayUrl;\`.
55166
+ Treat this as a workaround, not the default, and never invent the value.
55167
+
55115
55168
  ## Probe first (recommended)
55116
55169
 
55117
55170
  The platform key belongs to a human. Before writing the real handler:
@@ -55141,6 +55194,109 @@ is used, or when a tool schema takes a \`connectionKey\` and multiple connection
55141
55194
  are possible. A key may intentionally point at another project/tenant \u2014 that is a
55142
55195
  feature, not an error. Do not guess a connection key.
55143
55196
 
55197
+ ## \`callTool\` returns an envelope, not your payload
55198
+
55199
+ \`OpenToolResult\` is \`{ isError, content, text(), json() }\`. \`content[0].text\`
55200
+ often holds a JSON **string** (for example a large array). If you call
55201
+ \`JSON.stringify(result)\` \u2014 or put the whole result into your own output envelope
55202
+ \u2014 that text is embedded again and a parser fails with
55203
+ \`Unexpected non-whitespace character after JSON at position N\`.
55204
+
55205
+ Always unwrap:
55206
+
55207
+ \`\`\`js
55208
+ function unwrapToolResult(result) {
55209
+ if (result.isError) throw new Error(result.text() || "tool failed");
55210
+ try {
55211
+ return result.json(); // JSON.parse(first text block)
55212
+ } catch {
55213
+ return result.text(); // plain-text or non-JSON payload
55214
+ }
55215
+ }
55216
+ const data = unwrapToolResult(
55217
+ await client.callTool("collection_search_collection", args),
55218
+ );
55219
+ \`\`\`
55220
+
55221
+ Never print the envelope itself \u2014 print only the unwrapped \`result\`.
55222
+
55223
+ ## Canonical handler skeleton
55224
+
55225
+ Copy this four-step shape; fill in only the tool name and arguments.
55226
+
55227
+ \`\`\`js
55228
+ const fs = require("fs");
55229
+ const { OpenMcpClient } = require("@axiom-lattice/open-mcp-client");
55230
+
55231
+ // 1. Input: plain JSON first, base64 fallback. Surface a bad payload.
55232
+ function parseMaybeBase64(raw) {
55233
+ try {
55234
+ return JSON.parse(raw);
55235
+ } catch (plainErr) {
55236
+ try {
55237
+ return JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
55238
+ } catch {
55239
+ throw new Error("cannot parse input as JSON or base64 JSON: " + plainErr.message);
55240
+ }
55241
+ }
55242
+ }
55243
+ function readInput() {
55244
+ if (process.env.PLUGIN_INPUT_FILE) {
55245
+ return JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"));
55246
+ }
55247
+ const raw = process.env.PLUGIN_INPUT;
55248
+ return raw ? parseMaybeBase64(raw) : {};
55249
+ }
55250
+
55251
+ // 2. Unwrap the MCP envelope: payload only, check isError.
55252
+ function unwrap(result) {
55253
+ if (result.isError) throw new Error(result.text() || "tool failed");
55254
+ try {
55255
+ return result.json();
55256
+ } catch {
55257
+ return result.text();
55258
+ }
55259
+ }
55260
+
55261
+ async function main() {
55262
+ // 3. Connection: first, or the one named by input.connectionKey.
55263
+ const input = readInput();
55264
+ const data = JSON.parse(fs.readFileSync(process.env.PLUGIN_CONNECTION_FILE, "utf8"));
55265
+ const conn = input.connectionKey
55266
+ ? (data.connections ?? []).find((c) => c.key === input.connectionKey)?.config
55267
+ : data.connection;
55268
+ if (!conn) {
55269
+ throw new Error(
55270
+ input.connectionKey
55271
+ ? "connection not found: " + input.connectionKey
55272
+ : "no connection selected; configure one or pass connectionKey",
55273
+ );
55274
+ }
55275
+
55276
+ // 4. Client: connection fields, never fromEnv() in a plugin handler.
55277
+ const client = new OpenMcpClient({
55278
+ url: process.env.API_GATEWAY_URL || conn.gatewayUrl,
55279
+ token: conn.platformApiKey,
55280
+ });
55281
+
55282
+ const rows = unwrap(await client.callTool("collection_search_collection", {
55283
+ collection: "docs",
55284
+ query: input.q,
55285
+ }));
55286
+ process.stdout.write(JSON.stringify({ ok: true, result: rows }));
55287
+ }
55288
+ main().catch((err) => {
55289
+ process.stdout.write(JSON.stringify({
55290
+ ok: false,
55291
+ error: String(err && err.message ? err.message : err),
55292
+ }));
55293
+ });
55294
+ \`\`\`
55295
+
55296
+ If you use \`conn.gatewayUrl\`, declare it in \`connection.fields\`; otherwise the
55297
+ injected \`API_GATEWAY_URL\` is enough. Do not replace the fallback order with
55298
+ \`conn.gatewayUrl\` alone.
55299
+
55144
55300
  ## Worked example
55145
55301
 
55146
55302
 
@@ -55169,10 +55325,34 @@ feature, not an error. Do not guess a connection key.
55169
55325
  const fs = require("fs");
55170
55326
  const { OpenMcpClient } = require("@axiom-lattice/open-mcp-client");
55171
55327
 
55328
+ function readInput() {
55329
+ if (process.env.PLUGIN_INPUT_FILE) {
55330
+ return JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"));
55331
+ }
55332
+ const raw = process.env.PLUGIN_INPUT;
55333
+ if (!raw) return {};
55334
+ try {
55335
+ return JSON.parse(raw); // manual/debug plaintext
55336
+ } catch (plainErr) {
55337
+ try {
55338
+ return JSON.parse(Buffer.from(raw, "base64").toString("utf8")); // executor
55339
+ } catch (base64Err) {
55340
+ throw new Error("cannot parse PLUGIN_INPUT: " + plainErr.message);
55341
+ }
55342
+ }
55343
+ }
55344
+
55345
+ function unwrapToolResult(result) {
55346
+ if (result.isError) throw new Error(result.text() || "tool failed");
55347
+ try {
55348
+ return result.json();
55349
+ } catch {
55350
+ return result.text();
55351
+ }
55352
+ }
55353
+
55172
55354
  async function main() {
55173
- const input = process.env.PLUGIN_INPUT_FILE
55174
- ? JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"))
55175
- : JSON.parse(process.env.PLUGIN_INPUT || "{}");
55355
+ const input = readInput();
55176
55356
  const conn = JSON.parse(
55177
55357
  fs.readFileSync(process.env.PLUGIN_CONNECTION_FILE, "utf8"),
55178
55358
  ).connection;
@@ -55181,8 +55361,11 @@ async function main() {
55181
55361
  url: process.env.API_GATEWAY_URL,
55182
55362
  token: conn.platformApiKey,
55183
55363
  });
55184
- const tools = await client.listTools(); // exactly what this handler may call
55185
- const kb = await client.callTool("collection_search_collection", { collection: "docs", query: input.q });
55364
+ await client.listTools(); // inspect the key's callable set first
55365
+ const kb = unwrapToolResult(await client.callTool(
55366
+ "collection_search_collection",
55367
+ { collection: "docs", query: input.q },
55368
+ ));
55186
55369
 
55187
55370
  process.stdout.write(JSON.stringify({ ok: true, result: kb }));
55188
55371
  }
@@ -55220,6 +55403,11 @@ output (e.g. the tool result), not on echoing the key.
55220
55403
  - [ ] \`connection.fields\` declares a password field for the platform key.
55221
55404
  - [ ] handler reads \`PLUGIN_CONNECTION_FILE.connection.<field>\`.
55222
55405
  - [ ] handler constructs \`OpenMcpClient\` with \`API_GATEWAY_URL\` + that field.
55406
+ - [ ] handler fails with a clear message when \`API_GATEWAY_URL\` is empty.
55407
+ - [ ] handler never reads \`OPEN_API_TOKEN\` (it is cleared on purpose).
55408
+ - [ ] \`require.resolve\` works from the plugin dir (dependency in \`<plugin>/node_modules\`).
55409
+ - [ ] \`callTool\` results are unwrapped (\`isError\` \u2192 \`json()\`/\`text()\`); the envelope is never serialized.
55410
+ - [ ] \`PLUGIN_INPUT\` is decoded as base64 (plaintext fallback); parse failures are visible.
55223
55411
  - [ ] \`listTools()\` is called before \`callTool()\`.
55224
55412
  - [ ] the handler never logs or writes the platform key.
55225
55413
  - [ ] the key is least-privilege and does not grant the plugin's own domain.
@@ -55286,12 +55474,29 @@ apply.
55286
55474
 
55287
55475
  ## Client availability
55288
55476
 
55289
- The sandbox image provides \`@axiom-lattice/open-mcp-client\`; use the bare module.
55477
+ Some sandbox images preinstall \`@axiom-lattice/open-mcp-client\`, but **do not rely
55478
+ on it**: module resolution starts at the plugin's \`handlers/\` directory. If
55479
+ \`require.resolve("@axiom-lattice/open-mcp-client")\` fails there, install it inside
55480
+ the plugin:
55481
+
55482
+ \`\`\`sh
55483
+ cd /home/appuser/.agents/plugins/<type>
55484
+ npm init -y
55485
+ npm install @axiom-lattice/open-mcp-client
55486
+ \`\`\`
55487
+
55488
+ \`/project/node_modules\` and a global \`NODE_PATH\` are not on the handler's
55489
+ resolution path. See \`sandbox-plugins-handlers\` \u2192 "Dependencies".
55290
55490
 
55291
55491
  ## Error handling
55292
55492
 
55293
55493
  | Symptom | Meaning | Action |
55294
55494
  |---|---|---|
55495
+ | \`Cannot find module '@axiom-lattice/open-mcp-client'\` | dependency is not in \`<plugin>/node_modules\` | install it in the plugin dir; verify \`require.resolve\` from \`handlers/\` |
55496
+ | \`Unexpected non-whitespace character after JSON at position N\` | you serialized the \`callTool\` envelope, so \`content[0].text\` is embedded twice | unwrap with \`isError\` + \`json()\`/\`text()\`; print only the payload |
55497
+ | every input field missing / \`{}\` | parsed base64 \`PLUGIN_INPUT\` as plaintext and swallowed the error | decode base64 with a plaintext fallback; fail visibly |
55498
+ | \`API_GATEWAY_URL\` empty | Gateway has no \`PUBLIC_GATEWAY_URL\` | ask a human to set it; do not guess a host |
55499
+ | \`OPEN_API_TOKEN\` empty | expected in plugin handlers (cleared by design) | use the connection password field, never the env token |
55295
55500
  | \`token is required\` / \`OpenMcpConfigError\` | connection has no platform key | ask the human to configure it |
55296
55501
  | \`OpenMcpAuthError\` / 401 | key disabled, rotated, or invalid | ask the human to rotate/configure |
55297
55502
  | tool-not-found | key has no such domain/action | do not retry; fix the key grant |
@@ -55322,6 +55527,13 @@ If the plugin previously called \`OpenMcpClient.fromEnv()\`:
55322
55527
  const { OpenMcpClient } = require("@axiom-lattice/open-mcp-client");
55323
55528
 
55324
55529
  async function main() {
55530
+ if (!process.env.API_GATEWAY_URL) {
55531
+ process.stdout.write(JSON.stringify({
55532
+ ok: false,
55533
+ error: "API_GATEWAY_URL is empty: ask a human to set PUBLIC_GATEWAY_URL on the Gateway",
55534
+ }));
55535
+ return;
55536
+ }
55325
55537
  const conn = JSON.parse(
55326
55538
  fs.readFileSync(process.env.PLUGIN_CONNECTION_FILE, "utf8"),
55327
55539
  ).connection;
@@ -55366,14 +55578,50 @@ sandbox. Node never evaluates them in the gateway process.
55366
55578
  ## Reading input
55367
55579
  \`\`\`js
55368
55580
  const fs = require("fs");
55369
- const input = process.env.PLUGIN_INPUT
55370
- ? JSON.parse(Buffer.from(process.env.PLUGIN_INPUT, "base64").toString("utf8"))
55371
- : process.env.PLUGIN_INPUT_FILE
55372
- ? JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"))
55373
- : undefined;
55581
+ function readInput() {
55582
+ if (process.env.PLUGIN_INPUT_FILE) {
55583
+ // Large input: plain JSON written to a file.
55584
+ return JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"));
55585
+ }
55586
+ const raw = process.env.PLUGIN_INPUT;
55587
+ if (!raw) return {};
55588
+ try {
55589
+ return JSON.parse(raw); // manual/debug plaintext
55590
+ } catch (plainErr) {
55591
+ try {
55592
+ return JSON.parse(Buffer.from(raw, "base64").toString("utf8")); // executor
55593
+ } catch (base64Err) {
55594
+ throw new Error("cannot parse PLUGIN_INPUT as JSON or base64 JSON: " + plainErr.message);
55595
+ }
55596
+ }
55597
+ }
55598
+ const input = readInput();
55599
+ \`\`\`
55600
+ **Small inputs arrive base64-encoded in \`PLUGIN_INPUT\`; large inputs are written
55601
+ as plain JSON to \`PLUGIN_INPUT_FILE\`.** Never silently catch a parse failure and
55602
+ fall back to \`{}\` \u2014 that makes every input disappear and sends you debugging the
55603
+ wrong layer.
55604
+
55605
+ ## Dependencies (the plugin is self-contained)
55606
+ Node resolves \`require(...)\` by walking up from \`handlers/*.js\`:
55607
+ \`<plugin>/node_modules\` \u2192 \`.agents/node_modules\` \u2192 \`/home/appuser\` \u2192 \`/\`.
55608
+ \`/project/node_modules\` and a global \`NODE_PATH\` are **not** guaranteed to be on
55609
+ that path. Install every dependency **inside the plugin directory**:
55610
+
55611
+ \`\`\`sh
55612
+ cd /home/appuser/.agents/plugins/<type>
55613
+ npm init -y # only if there is no package.json
55614
+ npm install @axiom-lattice/open-mcp-client
55615
+ # or: npm install --prefix /home/appuser/.agents/plugins/<type> <pkg>
55616
+ \`\`\`
55617
+
55618
+ Verify from the plugin directory (must print a path under \`<plugin>/node_modules\`):
55619
+ \`\`\`sh
55620
+ node -e "console.log(require.resolve('@axiom-lattice/open-mcp-client'))"
55374
55621
  \`\`\`
55375
- Small inputs arrive as base64 in \`PLUGIN_INPUT\`; large inputs are written to
55376
- \`PLUGIN_INPUT_FILE\`.
55622
+
55623
+ Do not use \`npm install -g\`. Backups and migrations must keep
55624
+ \`<plugin>/node_modules\` with the plugin (or reinstall after copying).
55377
55625
 
55378
55626
  ## Reading the connection
55379
55627
  \`\`\`js
@@ -55493,6 +55741,20 @@ Use the \`manage_plugin\` tool. The loop:
55493
55741
  \`[redacted]\`. Never rely on echoing credentials to verify a handler \u2014 assert on
55494
55742
  functional output instead.
55495
55743
 
55744
+ ## Debugging: change the hypothesis, not just the code
55745
+ - Read the error position. \`Unexpected non-whitespace character after JSON at
55746
+ position N\`: if N is larger than your handler's own stdout, the bad bytes are
55747
+ **not** in your output \u2014 check input decoding and \`callTool\` envelope
55748
+ unwrapping instead.
55749
+ - The same error after one rewrite means the hypothesis is wrong. Stop editing
55750
+ the output format; check a different layer (module resolution, input encoding,
55751
+ envelope shape).
55752
+ - A \`dbg\` tool should print evidence, not guesses: \`typeof PLUGIN_INPUT\`, its
55753
+ decoded prefix, \`typeof result\`, \`Object.keys(result)\`, \`result.isError\`,
55754
+ \`result.content[0].text.slice(0, 200)\`.
55755
+ - Never swallow a parse error and return \`{}\`; throw with the actual shape so the
55756
+ next test shows what arrived.
55757
+
55496
55758
  ## Common failures
55497
55759
  | Symptom | Cause |
55498
55760
  |---|---|
@@ -55502,6 +55764,9 @@ Use the \`manage_plugin\` tool. The loop:
55502
55764
  | non-zero exit | handler threw; read stdout/stderr from \`test\` |
55503
55765
  | old behaviour after edit | the catalog caches by content hash/TTL \u2014 call \`reload\` |
55504
55766
  | empty connection in handler | no \`connectionKey\` passed, or no connection configured for this type |
55767
+ | \`Cannot find module '<pkg>'\` | dependency is not in \`<plugin>/node_modules\` (not \`/project\`, not global) |
55768
+ | \`... after JSON at position N\` where N > your output size | the \`callTool\` envelope was stringified into your output |
55769
+ | all inputs empty after a valid call | \`PLUGIN_INPUT\` is base64; the plaintext parse failed silently |
55505
55770
 
55506
55771
  Fall back to \`shell_exec\` to run \`node handlers/x.js\` manually with
55507
55772
  \`PLUGIN_INPUT\` and a synthetic \`PLUGIN_CONNECTION_FILE\` to reproduce logic bugs.
@@ -55604,7 +55869,11 @@ call the platform's own tools/agents from its handler, load
55604
55869
  in connection.fields, read it from PLUGIN_CONNECTION_FILE, construct OpenMcpClient
55605
55870
  with API_GATEWAY_URL + that field, and never use
55606
55871
  OPEN_API_TOKEN/OpenMcpClient.fromEnv() in a plugin handler. A human must
55607
- configure the connection before PTC can be verified. If the key's capabilities
55872
+ configure the connection before PTC can be verified. If API_GATEWAY_URL is
55873
+ empty, do not keep retrying or hardcode/guess a host: tell the human to set
55874
+ PUBLIC_GATEWAY_URL on the Gateway (or, as a workaround, add a gatewayUrl
55875
+ connection field). OPEN_API_TOKEN is cleared for plugin handlers on purpose;
55876
+ never try to use or restore it. If the key's capabilities
55608
55877
  are unknown, author a probe handler first and run manage_plugin test with a real
55609
55878
  connectionKey; use the returned listTools names/inputSchema before writing the
55610
55879
  real handler.