@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 +288 -19
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +288 -19
- package/dist/index.mjs.map +1 -1
- package/package.json +2 -2
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
|
-
|
|
56566
|
-
|
|
56567
|
-
|
|
56568
|
-
|
|
56569
|
-
|
|
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 =
|
|
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
|
-
|
|
57285
|
-
const kb = await client.callTool(
|
|
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
|
-
|
|
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
|
-
|
|
57470
|
-
|
|
57471
|
-
|
|
57472
|
-
|
|
57473
|
-
|
|
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
|
-
|
|
57476
|
-
\`
|
|
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
|
|
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.
|