@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.mjs
CHANGED
|
@@ -54462,11 +54462,25 @@ var PLUGIN_JSON_TEMPLATE = `{
|
|
|
54462
54462
|
`;
|
|
54463
54463
|
var HANDLER_TEMPLATE = `const fs = require("fs");
|
|
54464
54464
|
|
|
54465
|
-
|
|
54466
|
-
|
|
54467
|
-
|
|
54468
|
-
|
|
54469
|
-
|
|
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 =
|
|
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
|
-
|
|
55185
|
-
const kb = await client.callTool(
|
|
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
|
-
|
|
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
|
-
|
|
55370
|
-
|
|
55371
|
-
|
|
55372
|
-
|
|
55373
|
-
|
|
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
|
-
|
|
55376
|
-
\`
|
|
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
|
|
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.
|