@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.js CHANGED
@@ -56562,11 +56562,25 @@ var PLUGIN_JSON_TEMPLATE = `{
56562
56562
  `;
56563
56563
  var HANDLER_TEMPLATE = `const fs = require("fs");
56564
56564
 
56565
- const input = process.env.PLUGIN_INPUT
56566
- ? JSON.parse(Buffer.from(process.env.PLUGIN_INPUT, "base64").toString("utf8"))
56567
- : process.env.PLUGIN_INPUT_FILE
56568
- ? JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"))
56569
- : undefined;
56565
+ function readInput() {
56566
+ if (process.env.PLUGIN_INPUT_FILE) {
56567
+ // Large input: the executor writes plain JSON to a file.
56568
+ return JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"));
56569
+ }
56570
+ const raw = process.env.PLUGIN_INPUT;
56571
+ if (!raw) return {};
56572
+ try {
56573
+ return JSON.parse(raw); // manual/debug plaintext
56574
+ } catch (plainErr) {
56575
+ try {
56576
+ return JSON.parse(Buffer.from(raw, "base64").toString("utf8")); // executor
56577
+ } catch (base64Err) {
56578
+ throw new Error("cannot parse PLUGIN_INPUT as JSON or base64 JSON: " + plainErr.message);
56579
+ }
56580
+ }
56581
+ }
56582
+
56583
+ const input = readInput();
56570
56584
  const data = process.env.PLUGIN_CONNECTION_FILE
56571
56585
  ? JSON.parse(fs.readFileSync(process.env.PLUGIN_CONNECTION_FILE, "utf8"))
56572
56586
  : {};
@@ -57212,6 +57226,45 @@ const client = new OpenMcpClient({
57212
57226
  \`OPEN_API_TOKEN\` is **not** injected for plugin handlers. If you find yourself
57213
57227
  calling \`fromEnv()\` in a plugin handler, stop and switch to the connection key.
57214
57228
 
57229
+ ## \`OPEN_API_TOKEN\` is empty on purpose
57230
+
57231
+ The executor clears \`OPEN_API_TOKEN\` before running a plugin handler. An empty
57232
+ value is the expected contract, not a misconfiguration: never read it, never
57233
+ \`fromEnv()\`, and never ask a human to "restore" it. The handler's only platform
57234
+ credential is the password field from \`connection.fields\`.
57235
+ (\`code_eval\` / the builder's own \`shell_exec\` may receive a short-lived,
57236
+ self-bound \`OPEN_API_TOKEN\`; it is not a plugin key and must not be reused.)
57237
+
57238
+ ## \`API_GATEWAY_URL\` is injected, but may be empty
57239
+
57240
+ \`API_GATEWAY_URL\` is **not** tied to \`OPEN_API_TOKEN\`: the Gateway injects it into
57241
+ every plugin handler (short-process and resident) from the deployment's
57242
+ \`PUBLIC_GATEWAY_URL\`. It exists only when the Gateway process has that env set.
57243
+ \`shell_exec\` / \`code_eval\` use the same \`PUBLIC_GATEWAY_URL\` seam.
57244
+
57245
+ If it is empty, stop and ask a human \u2014 do **not** loop, guess a host, or blindly
57246
+ try \`localhost\`:
57247
+
57248
+ \`\`\`js
57249
+ if (!process.env.API_GATEWAY_URL) {
57250
+ process.stdout.write(JSON.stringify({
57251
+ ok: false,
57252
+ error: "API_GATEWAY_URL is empty: ask a human to set PUBLIC_GATEWAY_URL on the Gateway",
57253
+ }));
57254
+ return;
57255
+ }
57256
+ \`\`\`
57257
+
57258
+ Recovery order:
57259
+ 1. Ask the platform operator to set \`PUBLIC_GATEWAY_URL\` on the Gateway to a URL
57260
+ the sandbox can reach (LB/public domain; \`host.docker.internal:<port>\` for
57261
+ local containers; \`localhost:<port>\` only when the sandbox shares the host
57262
+ network), then restart the Gateway.
57263
+ 2. Only if the deployment will not set it, add a \`gatewayUrl\` string field to
57264
+ \`connection.fields\` and use
57265
+ \`const base = process.env.API_GATEWAY_URL || conn.gatewayUrl;\`.
57266
+ Treat this as a workaround, not the default, and never invent the value.
57267
+
57215
57268
  ## Probe first (recommended)
57216
57269
 
57217
57270
  The platform key belongs to a human. Before writing the real handler:
@@ -57241,6 +57294,109 @@ is used, or when a tool schema takes a \`connectionKey\` and multiple connection
57241
57294
  are possible. A key may intentionally point at another project/tenant \u2014 that is a
57242
57295
  feature, not an error. Do not guess a connection key.
57243
57296
 
57297
+ ## \`callTool\` returns an envelope, not your payload
57298
+
57299
+ \`OpenToolResult\` is \`{ isError, content, text(), json() }\`. \`content[0].text\`
57300
+ often holds a JSON **string** (for example a large array). If you call
57301
+ \`JSON.stringify(result)\` \u2014 or put the whole result into your own output envelope
57302
+ \u2014 that text is embedded again and a parser fails with
57303
+ \`Unexpected non-whitespace character after JSON at position N\`.
57304
+
57305
+ Always unwrap:
57306
+
57307
+ \`\`\`js
57308
+ function unwrapToolResult(result) {
57309
+ if (result.isError) throw new Error(result.text() || "tool failed");
57310
+ try {
57311
+ return result.json(); // JSON.parse(first text block)
57312
+ } catch {
57313
+ return result.text(); // plain-text or non-JSON payload
57314
+ }
57315
+ }
57316
+ const data = unwrapToolResult(
57317
+ await client.callTool("collection_search_collection", args),
57318
+ );
57319
+ \`\`\`
57320
+
57321
+ Never print the envelope itself \u2014 print only the unwrapped \`result\`.
57322
+
57323
+ ## Canonical handler skeleton
57324
+
57325
+ Copy this four-step shape; fill in only the tool name and arguments.
57326
+
57327
+ \`\`\`js
57328
+ const fs = require("fs");
57329
+ const { OpenMcpClient } = require("@axiom-lattice/open-mcp-client");
57330
+
57331
+ // 1. Input: plain JSON first, base64 fallback. Surface a bad payload.
57332
+ function parseMaybeBase64(raw) {
57333
+ try {
57334
+ return JSON.parse(raw);
57335
+ } catch (plainErr) {
57336
+ try {
57337
+ return JSON.parse(Buffer.from(raw, "base64").toString("utf8"));
57338
+ } catch {
57339
+ throw new Error("cannot parse input as JSON or base64 JSON: " + plainErr.message);
57340
+ }
57341
+ }
57342
+ }
57343
+ function readInput() {
57344
+ if (process.env.PLUGIN_INPUT_FILE) {
57345
+ return JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"));
57346
+ }
57347
+ const raw = process.env.PLUGIN_INPUT;
57348
+ return raw ? parseMaybeBase64(raw) : {};
57349
+ }
57350
+
57351
+ // 2. Unwrap the MCP envelope: payload only, check isError.
57352
+ function unwrap(result) {
57353
+ if (result.isError) throw new Error(result.text() || "tool failed");
57354
+ try {
57355
+ return result.json();
57356
+ } catch {
57357
+ return result.text();
57358
+ }
57359
+ }
57360
+
57361
+ async function main() {
57362
+ // 3. Connection: first, or the one named by input.connectionKey.
57363
+ const input = readInput();
57364
+ const data = JSON.parse(fs.readFileSync(process.env.PLUGIN_CONNECTION_FILE, "utf8"));
57365
+ const conn = input.connectionKey
57366
+ ? (data.connections ?? []).find((c) => c.key === input.connectionKey)?.config
57367
+ : data.connection;
57368
+ if (!conn) {
57369
+ throw new Error(
57370
+ input.connectionKey
57371
+ ? "connection not found: " + input.connectionKey
57372
+ : "no connection selected; configure one or pass connectionKey",
57373
+ );
57374
+ }
57375
+
57376
+ // 4. Client: connection fields, never fromEnv() in a plugin handler.
57377
+ const client = new OpenMcpClient({
57378
+ url: process.env.API_GATEWAY_URL || conn.gatewayUrl,
57379
+ token: conn.platformApiKey,
57380
+ });
57381
+
57382
+ const rows = unwrap(await client.callTool("collection_search_collection", {
57383
+ collection: "docs",
57384
+ query: input.q,
57385
+ }));
57386
+ process.stdout.write(JSON.stringify({ ok: true, result: rows }));
57387
+ }
57388
+ main().catch((err) => {
57389
+ process.stdout.write(JSON.stringify({
57390
+ ok: false,
57391
+ error: String(err && err.message ? err.message : err),
57392
+ }));
57393
+ });
57394
+ \`\`\`
57395
+
57396
+ If you use \`conn.gatewayUrl\`, declare it in \`connection.fields\`; otherwise the
57397
+ injected \`API_GATEWAY_URL\` is enough. Do not replace the fallback order with
57398
+ \`conn.gatewayUrl\` alone.
57399
+
57244
57400
  ## Worked example
57245
57401
 
57246
57402
 
@@ -57269,10 +57425,34 @@ feature, not an error. Do not guess a connection key.
57269
57425
  const fs = require("fs");
57270
57426
  const { OpenMcpClient } = require("@axiom-lattice/open-mcp-client");
57271
57427
 
57428
+ function readInput() {
57429
+ if (process.env.PLUGIN_INPUT_FILE) {
57430
+ return JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"));
57431
+ }
57432
+ const raw = process.env.PLUGIN_INPUT;
57433
+ if (!raw) return {};
57434
+ try {
57435
+ return JSON.parse(raw); // manual/debug plaintext
57436
+ } catch (plainErr) {
57437
+ try {
57438
+ return JSON.parse(Buffer.from(raw, "base64").toString("utf8")); // executor
57439
+ } catch (base64Err) {
57440
+ throw new Error("cannot parse PLUGIN_INPUT: " + plainErr.message);
57441
+ }
57442
+ }
57443
+ }
57444
+
57445
+ function unwrapToolResult(result) {
57446
+ if (result.isError) throw new Error(result.text() || "tool failed");
57447
+ try {
57448
+ return result.json();
57449
+ } catch {
57450
+ return result.text();
57451
+ }
57452
+ }
57453
+
57272
57454
  async function main() {
57273
- const input = process.env.PLUGIN_INPUT_FILE
57274
- ? JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"))
57275
- : JSON.parse(process.env.PLUGIN_INPUT || "{}");
57455
+ const input = readInput();
57276
57456
  const conn = JSON.parse(
57277
57457
  fs.readFileSync(process.env.PLUGIN_CONNECTION_FILE, "utf8"),
57278
57458
  ).connection;
@@ -57281,8 +57461,11 @@ async function main() {
57281
57461
  url: process.env.API_GATEWAY_URL,
57282
57462
  token: conn.platformApiKey,
57283
57463
  });
57284
- const tools = await client.listTools(); // exactly what this handler may call
57285
- const kb = await client.callTool("collection_search_collection", { collection: "docs", query: input.q });
57464
+ await client.listTools(); // inspect the key's callable set first
57465
+ const kb = unwrapToolResult(await client.callTool(
57466
+ "collection_search_collection",
57467
+ { collection: "docs", query: input.q },
57468
+ ));
57286
57469
 
57287
57470
  process.stdout.write(JSON.stringify({ ok: true, result: kb }));
57288
57471
  }
@@ -57320,6 +57503,11 @@ output (e.g. the tool result), not on echoing the key.
57320
57503
  - [ ] \`connection.fields\` declares a password field for the platform key.
57321
57504
  - [ ] handler reads \`PLUGIN_CONNECTION_FILE.connection.<field>\`.
57322
57505
  - [ ] handler constructs \`OpenMcpClient\` with \`API_GATEWAY_URL\` + that field.
57506
+ - [ ] handler fails with a clear message when \`API_GATEWAY_URL\` is empty.
57507
+ - [ ] handler never reads \`OPEN_API_TOKEN\` (it is cleared on purpose).
57508
+ - [ ] \`require.resolve\` works from the plugin dir (dependency in \`<plugin>/node_modules\`).
57509
+ - [ ] \`callTool\` results are unwrapped (\`isError\` \u2192 \`json()\`/\`text()\`); the envelope is never serialized.
57510
+ - [ ] \`PLUGIN_INPUT\` is decoded as base64 (plaintext fallback); parse failures are visible.
57323
57511
  - [ ] \`listTools()\` is called before \`callTool()\`.
57324
57512
  - [ ] the handler never logs or writes the platform key.
57325
57513
  - [ ] the key is least-privilege and does not grant the plugin's own domain.
@@ -57386,12 +57574,29 @@ apply.
57386
57574
 
57387
57575
  ## Client availability
57388
57576
 
57389
- The sandbox image provides \`@axiom-lattice/open-mcp-client\`; use the bare module.
57577
+ Some sandbox images preinstall \`@axiom-lattice/open-mcp-client\`, but **do not rely
57578
+ on it**: module resolution starts at the plugin's \`handlers/\` directory. If
57579
+ \`require.resolve("@axiom-lattice/open-mcp-client")\` fails there, install it inside
57580
+ the plugin:
57581
+
57582
+ \`\`\`sh
57583
+ cd /home/appuser/.agents/plugins/<type>
57584
+ npm init -y
57585
+ npm install @axiom-lattice/open-mcp-client
57586
+ \`\`\`
57587
+
57588
+ \`/project/node_modules\` and a global \`NODE_PATH\` are not on the handler's
57589
+ resolution path. See \`sandbox-plugins-handlers\` \u2192 "Dependencies".
57390
57590
 
57391
57591
  ## Error handling
57392
57592
 
57393
57593
  | Symptom | Meaning | Action |
57394
57594
  |---|---|---|
57595
+ | \`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/\` |
57596
+ | \`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 |
57597
+ | every input field missing / \`{}\` | parsed base64 \`PLUGIN_INPUT\` as plaintext and swallowed the error | decode base64 with a plaintext fallback; fail visibly |
57598
+ | \`API_GATEWAY_URL\` empty | Gateway has no \`PUBLIC_GATEWAY_URL\` | ask a human to set it; do not guess a host |
57599
+ | \`OPEN_API_TOKEN\` empty | expected in plugin handlers (cleared by design) | use the connection password field, never the env token |
57395
57600
  | \`token is required\` / \`OpenMcpConfigError\` | connection has no platform key | ask the human to configure it |
57396
57601
  | \`OpenMcpAuthError\` / 401 | key disabled, rotated, or invalid | ask the human to rotate/configure |
57397
57602
  | tool-not-found | key has no such domain/action | do not retry; fix the key grant |
@@ -57422,6 +57627,13 @@ If the plugin previously called \`OpenMcpClient.fromEnv()\`:
57422
57627
  const { OpenMcpClient } = require("@axiom-lattice/open-mcp-client");
57423
57628
 
57424
57629
  async function main() {
57630
+ if (!process.env.API_GATEWAY_URL) {
57631
+ process.stdout.write(JSON.stringify({
57632
+ ok: false,
57633
+ error: "API_GATEWAY_URL is empty: ask a human to set PUBLIC_GATEWAY_URL on the Gateway",
57634
+ }));
57635
+ return;
57636
+ }
57425
57637
  const conn = JSON.parse(
57426
57638
  fs.readFileSync(process.env.PLUGIN_CONNECTION_FILE, "utf8"),
57427
57639
  ).connection;
@@ -57466,14 +57678,50 @@ sandbox. Node never evaluates them in the gateway process.
57466
57678
  ## Reading input
57467
57679
  \`\`\`js
57468
57680
  const fs = require("fs");
57469
- const input = process.env.PLUGIN_INPUT
57470
- ? JSON.parse(Buffer.from(process.env.PLUGIN_INPUT, "base64").toString("utf8"))
57471
- : process.env.PLUGIN_INPUT_FILE
57472
- ? JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"))
57473
- : undefined;
57681
+ function readInput() {
57682
+ if (process.env.PLUGIN_INPUT_FILE) {
57683
+ // Large input: plain JSON written to a file.
57684
+ return JSON.parse(fs.readFileSync(process.env.PLUGIN_INPUT_FILE, "utf8"));
57685
+ }
57686
+ const raw = process.env.PLUGIN_INPUT;
57687
+ if (!raw) return {};
57688
+ try {
57689
+ return JSON.parse(raw); // manual/debug plaintext
57690
+ } catch (plainErr) {
57691
+ try {
57692
+ return JSON.parse(Buffer.from(raw, "base64").toString("utf8")); // executor
57693
+ } catch (base64Err) {
57694
+ throw new Error("cannot parse PLUGIN_INPUT as JSON or base64 JSON: " + plainErr.message);
57695
+ }
57696
+ }
57697
+ }
57698
+ const input = readInput();
57699
+ \`\`\`
57700
+ **Small inputs arrive base64-encoded in \`PLUGIN_INPUT\`; large inputs are written
57701
+ as plain JSON to \`PLUGIN_INPUT_FILE\`.** Never silently catch a parse failure and
57702
+ fall back to \`{}\` \u2014 that makes every input disappear and sends you debugging the
57703
+ wrong layer.
57704
+
57705
+ ## Dependencies (the plugin is self-contained)
57706
+ Node resolves \`require(...)\` by walking up from \`handlers/*.js\`:
57707
+ \`<plugin>/node_modules\` \u2192 \`.agents/node_modules\` \u2192 \`/home/appuser\` \u2192 \`/\`.
57708
+ \`/project/node_modules\` and a global \`NODE_PATH\` are **not** guaranteed to be on
57709
+ that path. Install every dependency **inside the plugin directory**:
57710
+
57711
+ \`\`\`sh
57712
+ cd /home/appuser/.agents/plugins/<type>
57713
+ npm init -y # only if there is no package.json
57714
+ npm install @axiom-lattice/open-mcp-client
57715
+ # or: npm install --prefix /home/appuser/.agents/plugins/<type> <pkg>
57716
+ \`\`\`
57717
+
57718
+ Verify from the plugin directory (must print a path under \`<plugin>/node_modules\`):
57719
+ \`\`\`sh
57720
+ node -e "console.log(require.resolve('@axiom-lattice/open-mcp-client'))"
57474
57721
  \`\`\`
57475
- Small inputs arrive as base64 in \`PLUGIN_INPUT\`; large inputs are written to
57476
- \`PLUGIN_INPUT_FILE\`.
57722
+
57723
+ Do not use \`npm install -g\`. Backups and migrations must keep
57724
+ \`<plugin>/node_modules\` with the plugin (or reinstall after copying).
57477
57725
 
57478
57726
  ## Reading the connection
57479
57727
  \`\`\`js
@@ -57593,6 +57841,20 @@ Use the \`manage_plugin\` tool. The loop:
57593
57841
  \`[redacted]\`. Never rely on echoing credentials to verify a handler \u2014 assert on
57594
57842
  functional output instead.
57595
57843
 
57844
+ ## Debugging: change the hypothesis, not just the code
57845
+ - Read the error position. \`Unexpected non-whitespace character after JSON at
57846
+ position N\`: if N is larger than your handler's own stdout, the bad bytes are
57847
+ **not** in your output \u2014 check input decoding and \`callTool\` envelope
57848
+ unwrapping instead.
57849
+ - The same error after one rewrite means the hypothesis is wrong. Stop editing
57850
+ the output format; check a different layer (module resolution, input encoding,
57851
+ envelope shape).
57852
+ - A \`dbg\` tool should print evidence, not guesses: \`typeof PLUGIN_INPUT\`, its
57853
+ decoded prefix, \`typeof result\`, \`Object.keys(result)\`, \`result.isError\`,
57854
+ \`result.content[0].text.slice(0, 200)\`.
57855
+ - Never swallow a parse error and return \`{}\`; throw with the actual shape so the
57856
+ next test shows what arrived.
57857
+
57596
57858
  ## Common failures
57597
57859
  | Symptom | Cause |
57598
57860
  |---|---|
@@ -57602,6 +57864,9 @@ Use the \`manage_plugin\` tool. The loop:
57602
57864
  | non-zero exit | handler threw; read stdout/stderr from \`test\` |
57603
57865
  | old behaviour after edit | the catalog caches by content hash/TTL \u2014 call \`reload\` |
57604
57866
  | empty connection in handler | no \`connectionKey\` passed, or no connection configured for this type |
57867
+ | \`Cannot find module '<pkg>'\` | dependency is not in \`<plugin>/node_modules\` (not \`/project\`, not global) |
57868
+ | \`... after JSON at position N\` where N > your output size | the \`callTool\` envelope was stringified into your output |
57869
+ | all inputs empty after a valid call | \`PLUGIN_INPUT\` is base64; the plaintext parse failed silently |
57605
57870
 
57606
57871
  Fall back to \`shell_exec\` to run \`node handlers/x.js\` manually with
57607
57872
  \`PLUGIN_INPUT\` and a synthetic \`PLUGIN_CONNECTION_FILE\` to reproduce logic bugs.
@@ -57704,7 +57969,11 @@ call the platform's own tools/agents from its handler, load
57704
57969
  in connection.fields, read it from PLUGIN_CONNECTION_FILE, construct OpenMcpClient
57705
57970
  with API_GATEWAY_URL + that field, and never use
57706
57971
  OPEN_API_TOKEN/OpenMcpClient.fromEnv() in a plugin handler. A human must
57707
- configure the connection before PTC can be verified. If the key's capabilities
57972
+ configure the connection before PTC can be verified. If API_GATEWAY_URL is
57973
+ empty, do not keep retrying or hardcode/guess a host: tell the human to set
57974
+ PUBLIC_GATEWAY_URL on the Gateway (or, as a workaround, add a gatewayUrl
57975
+ connection field). OPEN_API_TOKEN is cleared for plugin handlers on purpose;
57976
+ never try to use or restore it. If the key's capabilities
57708
57977
  are unknown, author a probe handler first and run manage_plugin test with a real
57709
57978
  connectionKey; use the returned listTools names/inputSchema before writing the
57710
57979
  real handler.