@topline-build/harness-mcp 0.9.14 → 0.9.16
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/CHANGELOG.md +14 -0
- package/dist/index.d.ts +22 -1
- package/dist/index.js +138 -8
- package/docs/generated/build-mcp-manifest.json +453 -8
- package/docs/generated/build-mcp-reference.md +430 -6
- package/package.json +1 -1
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,20 @@
|
|
|
2
2
|
|
|
3
3
|
All notable customer-visible Build MCP changes are recorded here. A source change is not a published package or customer release.
|
|
4
4
|
|
|
5
|
+
## 0.9.16 - 2026-11-11
|
|
6
|
+
|
|
7
|
+
- `platform_deploy_artifact_app` runs inspect's manifest and `node --check` checks and refuses with `artifact_package_not_ready`, naming each problem's code and file, before it uploads anything or spends build budget. (Data-binding findings stay inspect-only, since a leftover build file can trip them.)
|
|
8
|
+
- `node --check` no longer reports an ES module file as a syntax error on Node versions that check it as CommonJS ("Cannot use import statement outside a module").
|
|
9
|
+
- Inside a build session, a deploy that passes `projectId` is refused locally with `build_session_project_id_not_allowed` instead of reaching Topline as a retryable server error.
|
|
10
|
+
- A deploy cancelled because its build session was closed (`artifact_deploy_failed:build_session_cancelled`) says to start a new session and deploy again, not to fix the source.
|
|
11
|
+
- `javascript_syntax_error` details no longer end in a stray carriage return on Windows.
|
|
12
|
+
|
|
13
|
+
## 0.9.15 - 2026-11-11
|
|
14
|
+
|
|
15
|
+
- `platform_inspect_artifact_app` runs `node --check` on each `.js`, `.mjs` and `.cjs` source file, so a syntax error makes `packageReady` false with a `javascript_syntax_error` problem naming the file and line, instead of failing the build after deploy.
|
|
16
|
+
- Inspect also returns `warnings` for static page text that Topline's render smoke would refuse as sample or mock data (`rendered_text_rule:sample_or_mock_data_text`), with the file and the phrase.
|
|
17
|
+
- A source conflict error carries `currentSourceHash`, and a pending-operation error carries this session's `pendingOperationId` and `pendingKind`, when Topline sends them. `artifact_operation_pending` is marked retryable once the operation settles.
|
|
18
|
+
|
|
5
19
|
## 0.9.14 - 2026-11-11
|
|
6
20
|
|
|
7
21
|
- `platform_wait_artifact_deploy` names the build's failure code (`artifact_deploy_failed:<code>`) instead of only `failed`, and its recovery says to read `platform_deploy_operation` for the build's own error instead of retrying the wait.
|
package/dist/index.d.ts
CHANGED
|
@@ -42,7 +42,7 @@ type ToolProgressReporter = (progress: number, message: string) => void | Promis
|
|
|
42
42
|
export type McpSurface = "build" | "topline" | "harness";
|
|
43
43
|
export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
44
44
|
export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
|
|
45
|
-
export declare const HARNESS_MCP_VERSION = "0.9.
|
|
45
|
+
export declare const HARNESS_MCP_VERSION = "0.9.16";
|
|
46
46
|
export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
|
|
47
47
|
/** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
|
|
48
48
|
export declare const TOPLINE_OAUTH_SCOPES: readonly string[];
|
|
@@ -136,6 +136,12 @@ export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input:
|
|
|
136
136
|
path: string;
|
|
137
137
|
detail: string;
|
|
138
138
|
}[];
|
|
139
|
+
warnings: {
|
|
140
|
+
code: string;
|
|
141
|
+
path: string;
|
|
142
|
+
phrase: string;
|
|
143
|
+
detail: string;
|
|
144
|
+
}[];
|
|
139
145
|
serverManifestValidationRequired: boolean;
|
|
140
146
|
appDir: string;
|
|
141
147
|
platformAppDir: string;
|
|
@@ -168,6 +174,21 @@ export declare function localPreflightProblems(appDir: string, manifest: Record<
|
|
|
168
174
|
path: string;
|
|
169
175
|
detail: string;
|
|
170
176
|
}>>;
|
|
177
|
+
/**
|
|
178
|
+
* Round 12: a JavaScript syntax error passed inspect (packageReady true) and then failed the
|
|
179
|
+
* build. Check each source file the way the build's Node would, and name the file and line.
|
|
180
|
+
*/
|
|
181
|
+
export declare function javascriptSyntaxProblems(appDir: string): Promise<Array<{
|
|
182
|
+
code: string;
|
|
183
|
+
path: string;
|
|
184
|
+
detail: string;
|
|
185
|
+
}>>;
|
|
186
|
+
export declare function renderedTextRuleWarnings(appDir: string): Promise<Array<{
|
|
187
|
+
code: string;
|
|
188
|
+
path: string;
|
|
189
|
+
phrase: string;
|
|
190
|
+
detail: string;
|
|
191
|
+
}>>;
|
|
171
192
|
export declare function waitForArtifactDeploy(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<Record<string, unknown>>;
|
|
172
193
|
export declare function initArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
|
|
173
194
|
ok: boolean;
|
package/dist/index.js
CHANGED
|
@@ -19,7 +19,7 @@ const MCP_SURFACES = ["build", "topline", "harness"];
|
|
|
19
19
|
export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
|
|
20
20
|
const DEFAULT_TIMEOUT_MS = 120_000;
|
|
21
21
|
export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
|
|
22
|
-
export const HARNESS_MCP_VERSION = "0.9.
|
|
22
|
+
export const HARNESS_MCP_VERSION = "0.9.16";
|
|
23
23
|
export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
|
|
24
24
|
/** The Topline server's scopes: Build and Workspace. Consent shows what the seat allows. */
|
|
25
25
|
export const TOPLINE_OAUTH_SCOPES = Object.freeze([
|
|
@@ -936,6 +936,14 @@ export async function deployArtifactApp(opts, input, onProgress) {
|
|
|
936
936
|
.digest("hex");
|
|
937
937
|
await onProgress?.(0.2, "Packaging local artifact app");
|
|
938
938
|
const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
|
|
939
|
+
// Round 13 R4: a package inspect says isn't ready fails the build the same way, after spending
|
|
940
|
+
// budget and a minute; refuse it here, before anything is uploaded.
|
|
941
|
+
// Only checks that can't be a stale or unrelated file (manifest fields and syntax errors) block a deploy;
|
|
942
|
+
// inspect still lists data-binding findings, which a leftover build output can trip.
|
|
943
|
+
const problems = (await localPreflightProblems(absoluteAppDir, manifest)).filter((problem) => problem.code === "invalid_artifact_app_manifest");
|
|
944
|
+
problems.push(...await javascriptSyntaxProblems(absoluteAppDir));
|
|
945
|
+
if (problems.length)
|
|
946
|
+
throw new Error(`artifact_package_not_ready:${problems.slice(0, 5).map((problem) => `${problem.code} ${problem.path}`).join("; ")}`);
|
|
939
947
|
const expectedBundleSha256 = optionalString(input, "expectedBundleSha256")?.toLowerCase();
|
|
940
948
|
if (expectedBundleSha256 && bundle.sha256 !== expectedBundleSha256) {
|
|
941
949
|
throw new Error("artifact_app_bundle_changed_after_inspection");
|
|
@@ -952,6 +960,9 @@ export async function deployArtifactApp(opts, input, onProgress) {
|
|
|
952
960
|
.filter(([, value]) => !value).map(([name]) => name);
|
|
953
961
|
if (missing.length)
|
|
954
962
|
throw new Error(`build_session_deployment_arguments_required:${missing.join(",")}`);
|
|
963
|
+
// Round 13 R7: the session already belongs to its artifact (and project); Topline refuses projectId here.
|
|
964
|
+
if (optionalString(input, "projectId"))
|
|
965
|
+
throw new Error("build_session_project_id_not_allowed");
|
|
955
966
|
const session = asRecord(await callHostedBuildTool(opts, "platform_read_build_session", { sessionId }));
|
|
956
967
|
// The server resolves a repeated operation key before checking current
|
|
957
968
|
// version/source. Do not reject a lost-response retry using the newer read.
|
|
@@ -1154,10 +1165,13 @@ export async function inspectArtifactApp(opts, input) {
|
|
|
1154
1165
|
const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
|
|
1155
1166
|
const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
|
|
1156
1167
|
const problems = await localPreflightProblems(absoluteAppDir, manifest);
|
|
1168
|
+
problems.push(...await javascriptSyntaxProblems(absoluteAppDir));
|
|
1169
|
+
const warnings = await renderedTextRuleWarnings(absoluteAppDir);
|
|
1157
1170
|
return {
|
|
1158
1171
|
ok: true,
|
|
1159
1172
|
packageReady: problems.length === 0,
|
|
1160
1173
|
problems,
|
|
1174
|
+
warnings,
|
|
1161
1175
|
serverManifestValidationRequired: true,
|
|
1162
1176
|
appDir: workspaceAppDir,
|
|
1163
1177
|
platformAppDir,
|
|
@@ -1243,6 +1257,91 @@ export async function localPreflightProblems(appDir, manifest) {
|
|
|
1243
1257
|
await visit(appDir);
|
|
1244
1258
|
return problems.slice(0, 25);
|
|
1245
1259
|
}
|
|
1260
|
+
const SYNTAX_CHECK_EXTENSIONS = new Set([".js", ".mjs", ".cjs"]);
|
|
1261
|
+
const SYNTAX_CHECK_SKIP_DIRS = new Set([...PREFLIGHT_SKIP_DIRS, "dist", "build", "out", "vendor"]);
|
|
1262
|
+
async function listAppFiles(appDir, extensions, skipDirs, limit) {
|
|
1263
|
+
const out = [];
|
|
1264
|
+
const visit = async (dir) => {
|
|
1265
|
+
for (const entry of await readdir(dir, { withFileTypes: true }).catch(() => [])) {
|
|
1266
|
+
if (out.length >= limit)
|
|
1267
|
+
return;
|
|
1268
|
+
const full = path.join(dir, entry.name);
|
|
1269
|
+
if (entry.isDirectory()) {
|
|
1270
|
+
if (!skipDirs.has(entry.name))
|
|
1271
|
+
await visit(full);
|
|
1272
|
+
continue;
|
|
1273
|
+
}
|
|
1274
|
+
if (entry.isFile() && extensions.has(path.extname(entry.name)))
|
|
1275
|
+
out.push(full);
|
|
1276
|
+
}
|
|
1277
|
+
};
|
|
1278
|
+
await visit(appDir);
|
|
1279
|
+
return out;
|
|
1280
|
+
}
|
|
1281
|
+
function nodeCheck(file) {
|
|
1282
|
+
return new Promise((resolve) => {
|
|
1283
|
+
const child = spawn(process.execPath, ["--check", file], { stdio: ["ignore", "ignore", "pipe"] });
|
|
1284
|
+
let stderr = "";
|
|
1285
|
+
child.stderr?.on("data", (chunk) => { if (stderr.length < 4_000)
|
|
1286
|
+
stderr += String(chunk); });
|
|
1287
|
+
const timer = setTimeout(() => { child.kill(); resolve(null); }, 10_000);
|
|
1288
|
+
child.on("error", () => { clearTimeout(timer); resolve(null); });
|
|
1289
|
+
child.on("close", (code) => { clearTimeout(timer); resolve(code === 0 ? null : stderr); });
|
|
1290
|
+
});
|
|
1291
|
+
}
|
|
1292
|
+
/**
|
|
1293
|
+
* Round 12: a JavaScript syntax error passed inspect (packageReady true) and then failed the
|
|
1294
|
+
* build. Check each source file the way the build's Node would, and name the file and line.
|
|
1295
|
+
*/
|
|
1296
|
+
export async function javascriptSyntaxProblems(appDir) {
|
|
1297
|
+
const problems = [];
|
|
1298
|
+
for (const file of await listAppFiles(appDir, SYNTAX_CHECK_EXTENSIONS, SYNTAX_CHECK_SKIP_DIRS, 200)) {
|
|
1299
|
+
const stderr = await nodeCheck(file);
|
|
1300
|
+
if (!stderr || !/SyntaxError/.test(stderr))
|
|
1301
|
+
continue;
|
|
1302
|
+
// Round 13 review: an ES module file checked as CommonJS (older Node, no "type": "module") isn't
|
|
1303
|
+
// a syntax error the build hits; only real syntax errors count.
|
|
1304
|
+
if (/outside a module|Unexpected token 'export'|Cannot use 'import\.meta'/.test(stderr))
|
|
1305
|
+
continue;
|
|
1306
|
+
const rel = path.relative(appDir, file).replaceAll("\\", "/");
|
|
1307
|
+
const line = new RegExp(`${file.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}:(\\d+)`).exec(stderr)?.[1] ?? null;
|
|
1308
|
+
const message = /SyntaxError:[^\r\n]*/.exec(stderr)?.[0]?.slice(0, 200) ?? "SyntaxError";
|
|
1309
|
+
problems.push({ code: "javascript_syntax_error", path: line ? `${rel}:${line}` : rel, detail: `${rel}${line ? ` line ${line}` : ""}: ${message}` });
|
|
1310
|
+
if (problems.length >= 10)
|
|
1311
|
+
break;
|
|
1312
|
+
}
|
|
1313
|
+
return problems;
|
|
1314
|
+
}
|
|
1315
|
+
// The page-text rule the build's render smoke applies (sample_or_mock_data_text). Inspect can only
|
|
1316
|
+
// see static text, so a match is a warning: the build fails only if the rendered page shows it.
|
|
1317
|
+
const SAMPLE_DATA_TEXT_PATTERNS = [
|
|
1318
|
+
/\b(showing|using|displaying|rendering|loaded|fallback|placeholder)\s+(sample|demo|mock|placeholder|example)?\s*(data|dataset|rows|metrics|values)\b/i,
|
|
1319
|
+
/\b(sample|demo|mock|placeholder|example)\s+(data|dataset|rows|metrics|values)\b/i,
|
|
1320
|
+
/\b(template[-\s]?local|local[-\s]?(summary|tasks|events|rows|metrics|dataset))\b/i
|
|
1321
|
+
];
|
|
1322
|
+
export async function renderedTextRuleWarnings(appDir) {
|
|
1323
|
+
const warnings = [];
|
|
1324
|
+
for (const file of await listAppFiles(appDir, new Set([".html", ".js", ".jsx", ".ts", ".tsx", ".mjs"]), SYNTAX_CHECK_SKIP_DIRS, 500)) {
|
|
1325
|
+
const content = await readFile(file, "utf8").catch(() => "");
|
|
1326
|
+
if (content.length > 2_000_000)
|
|
1327
|
+
continue;
|
|
1328
|
+
// Visible text only: HTML text between tags and quoted string literals, not identifiers or comments.
|
|
1329
|
+
const texts = [...content.matchAll(/>([^<>]{3,400})</g), ...content.matchAll(/(["'`])((?:(?!\1)[^\\\n]|\\.){3,400})\1/g)].map((m) => m[m.length - 1] ?? "");
|
|
1330
|
+
for (const text of texts) {
|
|
1331
|
+
const match = SAMPLE_DATA_TEXT_PATTERNS.map((pattern) => pattern.exec(text)).find(Boolean);
|
|
1332
|
+
if (!match)
|
|
1333
|
+
continue;
|
|
1334
|
+
const rel = path.relative(appDir, file).replaceAll("\\", "/");
|
|
1335
|
+
const phrase = match[0].slice(0, 80);
|
|
1336
|
+
warnings.push({ code: "rendered_text_rule:sample_or_mock_data_text", path: rel, phrase,
|
|
1337
|
+
detail: `${rel} contains "${phrase}". If the page shows this text, Topline's build refuses it as sample or mock data. Reword it (for example "synthetic figures") or show the real data.` });
|
|
1338
|
+
break;
|
|
1339
|
+
}
|
|
1340
|
+
if (warnings.length >= 10)
|
|
1341
|
+
break;
|
|
1342
|
+
}
|
|
1343
|
+
return warnings;
|
|
1344
|
+
}
|
|
1246
1345
|
async function callHostedBuildTool(opts, name, input) {
|
|
1247
1346
|
if (!servesBuild(opts))
|
|
1248
1347
|
throw new Error(`${name}_requires_build_surface`);
|
|
@@ -1987,7 +2086,7 @@ const BUILD_MCP_TOOLS = [
|
|
|
1987
2086
|
},
|
|
1988
2087
|
{
|
|
1989
2088
|
name: "platform_deploy_artifact_app",
|
|
1990
|
-
description: "Package a local artifact app directory, upload it, deploy a private draft, and return status.",
|
|
2089
|
+
description: "Package a local artifact app directory, upload it, deploy a private draft, and return status. It runs platform_inspect_artifact_app's manifest and JavaScript syntax checks first and refuses with artifact_package_not_ready, before uploading or spending budget, while any of those problems remain. Inside a build session, leave projectId out.",
|
|
1991
2090
|
annotations: mcpToolAnnotations("platform_deploy_artifact_app", { readOnly: false, openWorld: true }),
|
|
1992
2091
|
inputSchema: {
|
|
1993
2092
|
type: "object",
|
|
@@ -2025,7 +2124,7 @@ const BUILD_MCP_TOOLS = [
|
|
|
2025
2124
|
},
|
|
2026
2125
|
{
|
|
2027
2126
|
name: "platform_inspect_artifact_app",
|
|
2028
|
-
description: "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft. Also runs the manifest and data-binding checks Topline's build would fail (datasets[].name and route, routes[].path, ./_artifact/data/<name> references with no matching dataset); packageReady is false and problems lists each one until they are fixed.",
|
|
2127
|
+
description: "Inspect local artifact paths and package boundaries without authenticating, uploading, or creating a remote draft. Also runs the manifest and data-binding checks Topline's build would fail (datasets[].name and route, routes[].path, ./_artifact/data/<name> references with no matching dataset) and a node --check of each .js/.mjs/.cjs file (javascript_syntax_error with file and line); packageReady is false and problems lists each one until they are fixed. warnings lists static text the build's page-text rules would refuse if the page shows it.",
|
|
2029
2128
|
annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
|
|
2030
2129
|
inputSchema: {
|
|
2031
2130
|
type: "object",
|
|
@@ -2038,7 +2137,8 @@ const BUILD_MCP_TOOLS = [
|
|
|
2038
2137
|
properties: {
|
|
2039
2138
|
ok: { type: "boolean" },
|
|
2040
2139
|
packageReady: { type: "boolean" },
|
|
2041
|
-
problems: { type: "array", items: { type: "object" }, description: "Checks Topline's build would fail: each has code, path (manifest field or file) and detail. packageReady is false while any remain." },
|
|
2140
|
+
problems: { type: "array", items: { type: "object" }, description: "Checks Topline's build would fail: each has code, path (manifest field or file, with :line for javascript_syntax_error) and detail. packageReady is false while any remain." },
|
|
2141
|
+
warnings: { type: "array", items: { type: "object" }, description: "Static text that matches a rule Topline's render smoke applies to the page (rendered_text_rule:sample_or_mock_data_text), with the file and phrase. The build fails only if the rendered page shows it." },
|
|
2042
2142
|
serverManifestValidationRequired: { type: "boolean" },
|
|
2043
2143
|
appDir: { type: "string" },
|
|
2044
2144
|
platformAppDir: { type: "string" },
|
|
@@ -2407,6 +2507,9 @@ function withRecoveryOutputSchema(value) {
|
|
|
2407
2507
|
retryable: { type: "boolean" },
|
|
2408
2508
|
recoveryAction: { type: "string" },
|
|
2409
2509
|
signInUrl: { type: "string" },
|
|
2510
|
+
currentSourceHash: { type: "string" },
|
|
2511
|
+
pendingOperationId: { type: "string" },
|
|
2512
|
+
pendingKind: { type: "string" },
|
|
2410
2513
|
...(DOMAIN_FORWARD_TOOLS.has(tool.name) ? { recovery: { type: "object", additionalProperties: true } } : {})
|
|
2411
2514
|
},
|
|
2412
2515
|
required: ["code", "message", "retryable", "recoveryAction"],
|
|
@@ -2485,9 +2588,12 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
|
|
|
2485
2588
|
artifact_app_scaffold_starter_shape_conflict: { retryable: false, recoveryAction: "A starter scaffolds the single shape; leave shape out or set it to single." },
|
|
2486
2589
|
// Stale preconditions: the same input can never succeed, whatever HTTP status an older Topline sends.
|
|
2487
2590
|
artifact_version_conflict: { retryable: false, recoveryAction: "The session moved to a newer version. Read the session (platform_read_build_session). A build session always starts from the app's current version; Build MCP can't check out an older saved version, so to go back, deploy source you saved before (or ask the coding agent in Topline to go back to version N). For a refused deploy: keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash. For a refused validation request: don't deploy again. Wait for the current version's deploy to settle (platform_deploy_operation), run its checks and smoke, prepare it with platform_prepare_artifact_validation, then call platform_request_artifact_validation with that prepared evidence." },
|
|
2591
|
+
artifact_package_not_ready: { retryable: false, recoveryAction: "platform_inspect_artifact_app reports problems Topline's build would fail on (named after the code, with file and line), so nothing was uploaded or spent. Fix them, run platform_inspect_artifact_app until packageReady is true, then deploy with the new expectedBundleSha256." },
|
|
2592
|
+
build_session_project_id_not_allowed: { retryable: false, recoveryAction: "Inside a build session the draft already belongs to the session's artifact and project. Leave projectId out and call again." },
|
|
2593
|
+
"artifact_deploy_failed:build_session_cancelled": { retryable: false, recoveryAction: "This deploy was cancelled because its build session was closed before it finished; the source wasn't at fault. Start a new build session for this artifact, then inspect and deploy again." },
|
|
2488
2594
|
build_session_deployment_arguments_required: { retryable: false, recoveryAction: "Inside a build session a deploy needs artifactVersionId, idempotencyKey, and the inspectedSourceHash and expectedBundleSha256 that platform_inspect_artifact_app returned. The fields named after the code are missing; add them and call again." },
|
|
2489
|
-
artifact_source_conflict: { retryable: false, recoveryAction: "inspectedSourceHash no longer matches the session's source fence.
|
|
2490
|
-
artifact_operation_pending: { retryable:
|
|
2595
|
+
artifact_source_conflict: { retryable: false, recoveryAction: "inspectedSourceHash no longer matches the session's source fence. Use currentSourceHash from this error when present, or read the session for its current sourceHash (or check out again into a new directory). Keep your local edits, inspect again, then deploy with the fresh hash." },
|
|
2596
|
+
artifact_operation_pending: { retryable: true, recoveryAction: "Another operation on this app has not settled. Read it with platform_deploy_operation, using pendingOperationId from this error when present (a deploy that already landed settles on that read), or platform_read_build_session, then call this tool again once it is terminal." },
|
|
2491
2597
|
artifact_deploy_in_flight: { retryable: true, recoveryAction: "A deploy for this app is still running. Wait until platform_deploy_operation says it is terminal, then retry the call that was refused (checkout, delete or deploy)." },
|
|
2492
2598
|
artifact_logs_deployment_not_found: { retryable: false, recoveryAction: "There is no deployment to read runtime logs from yet. For a failed build, read platform_deploy_operation: its failure field carries the build error." }
|
|
2493
2599
|
};
|
|
@@ -2496,16 +2602,40 @@ export function structuredToolError(message) {
|
|
|
2496
2602
|
const code = recoveryErrorCode(message);
|
|
2497
2603
|
// A 4xx means the same request will be refused again; only 5xx, timeouts and rate limits are worth retrying unchanged.
|
|
2498
2604
|
const retryable = /^platform_harness_http_error:5|timeout|rate_limited|unavailable|internal_error/.test(message);
|
|
2499
|
-
|
|
2605
|
+
// A failure code after the error code can have its own guidance (artifact_deploy_failed:build_session_cancelled).
|
|
2606
|
+
const detailCode = /^[a-z_]+:([a-z][a-z0-9_]{2,80})\b/.exec(message)?.[1];
|
|
2607
|
+
const selected = (detailCode ? BUILD_MCP_RECOVERY_ERRORS[`${code}:${detailCode}`] : undefined) ?? BUILD_MCP_RECOVERY_ERRORS[code] ?? { retryable, recoveryAction: !retryable && /^platform_harness_http_error:4|^platform_mcp_tool_error:/.test(message)
|
|
2500
2608
|
? "Topline refused this request as sent. Read the code, correct the input or state it names, then call the tool again; the same input fails the same way."
|
|
2501
2609
|
: "Inspect the code and message, correct the input if needed, then retry the same tool." };
|
|
2502
|
-
const structuredContent = { ok: false, error: { code, message, ...selected } };
|
|
2610
|
+
const structuredContent = { ok: false, error: { code, message, ...selected, ...conflictFieldsFromMessage(message) } };
|
|
2503
2611
|
return {
|
|
2504
2612
|
content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
|
|
2505
2613
|
structuredContent,
|
|
2506
2614
|
isError: true
|
|
2507
2615
|
};
|
|
2508
2616
|
}
|
|
2617
|
+
/** Round 12 Q5: Topline names the value a conflict needs (value-free hashes and ids); lift them onto the error. */
|
|
2618
|
+
function conflictFieldsFromMessage(message) {
|
|
2619
|
+
const http = /^platform_harness_http_error:\d{3}:(.*)$/s.exec(message);
|
|
2620
|
+
if (!http)
|
|
2621
|
+
return {};
|
|
2622
|
+
let body;
|
|
2623
|
+
try {
|
|
2624
|
+
body = JSON.parse(http[1]);
|
|
2625
|
+
}
|
|
2626
|
+
catch {
|
|
2627
|
+
return {};
|
|
2628
|
+
}
|
|
2629
|
+
if (!isRecord(body))
|
|
2630
|
+
return {};
|
|
2631
|
+
const out = {};
|
|
2632
|
+
for (const key of ["currentSourceHash", "pendingOperationId", "pendingKind"]) {
|
|
2633
|
+
const value = body[key];
|
|
2634
|
+
if (typeof value === "string" && /^[A-Za-z0-9_:.-]{1,128}$/.test(value))
|
|
2635
|
+
out[key] = value;
|
|
2636
|
+
}
|
|
2637
|
+
return out;
|
|
2638
|
+
}
|
|
2509
2639
|
/** The code Topline put inside a wrapped tool error: JSON `{ error: { code } }`, `{ error: "code" }`, or a leading code token. */
|
|
2510
2640
|
function hostedToolErrorCode(inner) {
|
|
2511
2641
|
try {
|