@topline-build/harness-mcp 0.9.7 → 0.9.9

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 CHANGED
@@ -2,6 +2,16 @@
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.9 - 2026-11-02
6
+
7
+ - Dashboard starters from `platform_init_artifact_app` no longer declare their `/_artifact/data/*` route as an app route or call it from the page. The platform serves those paths itself, and only once a dataset or source binding declares them, so the placeholder answered 404 and a fresh deploy's smoke check failed. The page now shows each data route as not connected until it is declared.
8
+ - A session deploy missing integrity arguments names them (`build_session_deployment_arguments_required:expectedBundleSha256`) and gets its own recovery. `expectedBundleSha256`'s description says it is required with `sessionId`.
9
+ - `artifact_version_conflict`'s recovery separates a refused deploy (inspect and deploy again) from a refused validation request (don't deploy again: wait for the current deploy, run checks and smoke, prepare, then request validation).
10
+
11
+ ## 0.9.8 - 2026-11-02
12
+
13
+ - `platform_record_acceptance_review`'s description and the `manual_result_requires_reviewer_skip` recovery no longer mention `evidence.reviewerCheck`, which the tool doesn't take. A passed review needs a check whose latest result the runner recorded as a skipped reviewer check.
14
+
5
15
  ## 0.9.7 - 2026-11-02
6
16
 
7
17
  - A first checkout of a new app (`artifact_source_unavailable`) says to deploy your local source with `platform_deploy_artifact_app` first and wait for the deploy operation, instead of offering a plain retry.
@@ -7,6 +7,11 @@
7
7
  * The scaffold is dependency-free Node and serves placeholder answers only:
8
8
  * it never declares datasets, source bindings, secret bindings or Bedrock env,
9
9
  * because those need the customer's own tables, sources and approved secrets.
10
+ * The platform itself serves /_artifact/data/* and /_artifact/knowledge/*, and
11
+ * only for a declared dataset, binding or grant, so app code never sees those
12
+ * requests. A starter's data route is therefore not a manifest route or a
13
+ * handler: the page shows it as not connected and never fetches it, so a
14
+ * fresh deploy's smoke check stays healthy instead of failing on a 404.
10
15
  * Its structured tests are labelled scaffold checks, not proof of behavior.
11
16
  */
12
17
  export type ArtifactStarterRoute = {
@@ -24,6 +29,11 @@ export type ArtifactStarter = {
24
29
  };
25
30
  export declare const ARTIFACT_STARTERS: ArtifactStarter[];
26
31
  export declare const ARTIFACT_STARTER_IDS: string[];
32
+ /** Paths the platform serves itself once a dataset, source binding or knowledge grant declares them. */
33
+ export declare const PLATFORM_SERVED_ROUTE_PREFIXES: readonly ["/_artifact/data/", "/_artifact/knowledge/"];
34
+ export declare function isPlatformServedRoute(routePath: string): boolean;
35
+ /** The routes app code serves, which the manifest declares and the handler answers. */
36
+ export declare function artifactStarterAppRoutes(starter: ArtifactStarter): ArtifactStarterRoute[];
27
37
  export declare function findArtifactStarter(id: string): ArtifactStarter | undefined;
28
38
  export declare function artifactStarterRecipe(starter: ArtifactStarter): {
29
39
  example: string;
@@ -7,6 +7,11 @@
7
7
  * The scaffold is dependency-free Node and serves placeholder answers only:
8
8
  * it never declares datasets, source bindings, secret bindings or Bedrock env,
9
9
  * because those need the customer's own tables, sources and approved secrets.
10
+ * The platform itself serves /_artifact/data/* and /_artifact/knowledge/*, and
11
+ * only for a declared dataset, binding or grant, so app code never sees those
12
+ * requests. A starter's data route is therefore not a manifest route or a
13
+ * handler: the page shows it as not connected and never fetches it, so a
14
+ * fresh deploy's smoke check stays healthy instead of failing on a 404.
10
15
  * Its structured tests are labelled scaffold checks, not proof of behavior.
11
16
  */
12
17
  export const ARTIFACT_STARTERS = [
@@ -31,7 +36,7 @@ export const ARTIFACT_STARTERS = [
31
36
  routes: [{ path: "/_artifact/data/branch-service-summary", note: "Placeholder for the recipe's live dataset." }],
32
37
  nextSteps: [
33
38
  "Find your own tables with the Workspace data catalog, then add the recipe's datasets[] and refreshSchedules[] with your SQL.",
34
- "Replace the placeholder data handler and its scaffold check once the dataset serves the route."
39
+ "Once the dataset serves the route, fetch it from the page in place of the not-connected notice and replace its scaffold check."
35
40
  ]
36
41
  },
37
42
  {
@@ -54,7 +59,7 @@ export const ARTIFACT_STARTERS = [
54
59
  ],
55
60
  nextSteps: [
56
61
  "Find your own tables with the Workspace data catalog, then add the recipe's two datasets[] with your SQL.",
57
- "Replace the placeholder data handlers and their scaffold checks once the datasets serve the routes."
62
+ "Once the datasets serve the routes, fetch them from the page in place of the not-connected notices and replace their scaffold checks."
58
63
  ]
59
64
  },
60
65
  {
@@ -64,7 +69,7 @@ export const ARTIFACT_STARTERS = [
64
69
  routes: [{ path: "/_artifact/data/service-health", note: "Placeholder for the materialized relation's dataset." }],
65
70
  nextSteps: [
66
71
  "Point a datasets[] entry at the existing materialized relation; the app never creates or refreshes it.",
67
- "Replace the placeholder data handler and its scaffold check once the dataset serves the route."
72
+ "Once the dataset serves the route, fetch it from the page in place of the not-connected notice and replace its scaffold check."
68
73
  ]
69
74
  },
70
75
  {
@@ -74,7 +79,7 @@ export const ARTIFACT_STARTERS = [
74
79
  routes: [{ path: "/_artifact/data/service-performance-report", note: "Placeholder for the precomputed report (windowDays 30 or 90)." }],
75
80
  nextSteps: [
76
81
  "Add the recipe's precomputed datasets[] entry (paramsSchema, warmParams) and its refresh schedule with your SQL.",
77
- "Replace the placeholder data handler and its scaffold check once the dataset serves the route."
82
+ "Once the dataset serves the route, fetch it from the page in place of the not-connected notice and replace its scaffold check."
78
83
  ]
79
84
  },
80
85
  {
@@ -95,11 +100,22 @@ export const ARTIFACT_STARTERS = [
95
100
  routes: [{ path: "/_artifact/data/customers", note: "Placeholder for the viewer-scoped source binding." }],
96
101
  nextSteps: [
97
102
  "Add the recipe's viewer-scoped sourceBindings[] entry for a source you already have, then switch viewerPolicy to tenant.",
98
- "Keep viewerPolicy private until the binding filters every row to the signed-in viewer."
103
+ "Keep viewerPolicy private until the binding filters every row to the signed-in viewer.",
104
+ "Once the binding serves /_artifact/data/customers, fetch it from the page in place of the not-connected notice and replace its scaffold check."
99
105
  ]
100
106
  }
101
107
  ];
102
108
  export const ARTIFACT_STARTER_IDS = ARTIFACT_STARTERS.map((starter) => starter.id);
109
+ /** Paths the platform serves itself once a dataset, source binding or knowledge grant declares them. */
110
+ export const PLATFORM_SERVED_ROUTE_PREFIXES = ["/_artifact/data/", "/_artifact/knowledge/"];
111
+ export function isPlatformServedRoute(routePath) {
112
+ return PLATFORM_SERVED_ROUTE_PREFIXES.some((prefix) => routePath.startsWith(prefix));
113
+ }
114
+ /** The routes app code serves, which the manifest declares and the handler answers. */
115
+ export function artifactStarterAppRoutes(starter) {
116
+ return starter.routes.filter((route) => !isPlatformServedRoute(route.path));
117
+ }
118
+ const NOT_CONNECTED_TEXT = "Not connected yet. The platform serves this path once a datasets[] or sourceBindings[] entry declares it; until then the page does not call it.";
103
119
  export function findArtifactStarter(id) {
104
120
  return ARTIFACT_STARTERS.find((starter) => starter.id === id);
105
121
  }
@@ -117,13 +133,21 @@ const escapeHtml = (value) => value.replace(/[&<>"']/g, (char) => ({ "&": "&amp;
117
133
  export function artifactStarterSource(starter, title) {
118
134
  const safeTitle = escapeHtml(title);
119
135
  const items = starter.routes
120
- .map((route) => `<li><code>${route.method ?? "GET"} ${escapeHtml(route.path)}</code> ${escapeHtml(route.note)} <span data-route="${escapeHtml(route.path)}" data-method="${route.method ?? "GET"}">...</span></li>`)
136
+ .map((route) => isPlatformServedRoute(route.path)
137
+ ? `<li><code>${route.method ?? "GET"} ${escapeHtml(route.path)}</code> ${escapeHtml(route.note)} <span data-not-connected="${escapeHtml(route.path)}">${escapeHtml(NOT_CONNECTED_TEXT)}</span></li>`
138
+ : `<li><code>${route.method ?? "GET"} ${escapeHtml(route.path)}</code> ${escapeHtml(route.note)} <span data-route="${escapeHtml(route.path)}" data-method="${route.method ?? "GET"}">...</span></li>`)
121
139
  .join("");
122
140
  const page = `<!doctype html><html><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>${safeTitle}</title></head><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p>Starter from the <code>${starter.id}</code> recipe. ${escapeHtml(starter.summary)}</p><ul>${items}</ul></main><script type="module">for (const el of document.querySelectorAll("[data-route]")) { const method = el.dataset.method; fetch("." + el.dataset.route, { method, headers: { "content-type": "application/json" }, body: method === "POST" ? "{}" : undefined }).then((r) => el.textContent = "answers " + r.status).catch(() => el.textContent = "not reachable"); }</script></body></html>`;
123
- const routes = starter.routes.map((route) => ({ path: route.path, method: route.method ?? "GET" }));
141
+ const routes = artifactStarterAppRoutes(starter).map((route) => ({ path: route.path, method: route.method ?? "GET" }));
124
142
  const tests = [
125
143
  { description: "Scaffold check: the page renders a visible app root.", required: true, status: "passed", summary: "Generated starter check; not proof of implemented behavior.", evidence: { selector: "data-platform-artifact-root", scaffold: true } },
126
- ...starter.routes.map((route) => ({
144
+ ...starter.routes.map((route) => isPlatformServedRoute(route.path) ? ({
145
+ description: `Scaffold check: ${route.method ?? "GET"} ${route.path} is shown as not connected until its dataset or binding is declared.`,
146
+ required: false,
147
+ status: "passed",
148
+ summary: "Generated starter check; replace it with a check of the real data once the platform serves the route.",
149
+ evidence: { route: route.path, scaffold: true, platformServed: true }
150
+ }) : ({
127
151
  description: `Scaffold check: ${route.method ?? "GET"} ${route.path} answers with a placeholder.`,
128
152
  required: false,
129
153
  status: "passed",
@@ -135,7 +159,8 @@ export function artifactStarterSource(starter, title) {
135
159
  import path from "node:path";
136
160
 
137
161
  // Starter from the Build cookbook recipe "${starter.id}". Every route below
138
- // returns a placeholder; follow the recipe to make each one real.
162
+ // returns a placeholder; follow the recipe to make each one real. Data routes
163
+ // (/_artifact/data/*) are served by the platform once declared, never here.
139
164
  const page = ${JSON.stringify(page)};
140
165
  const routes = ${JSON.stringify(routes)};
141
166
 
@@ -38,7 +38,7 @@ export function externalBuildHelperTools(annotate) {
38
38
  ...mutation, description: { type: "string", minLength: 3, maxLength: 1000 }
39
39
  }, [...Object.keys(mutation), "description"]),
40
40
  tool("platform_run_acceptance_checks", "Run required acceptance checks for the exact current draft revision through the shared service.", mutation, Object.keys(mutation)),
41
- tool("platform_record_acceptance_review", "Record the builder's review of a reviewer-only acceptance check. A passed result needs a check that platform_run_acceptance_checks marked skipped for this version (run the checks first) and evidence.reviewerCheck true. Does not impersonate the independent validator or remove required checks.", {
41
+ tool("platform_record_acceptance_review", "Record the builder's review of a reviewer-only acceptance check. A passed result is accepted only for a check whose latest result platform_run_acceptance_checks recorded as a skipped reviewer check for this version, so run the checks first. Does not impersonate the independent validator or remove required checks.", {
42
42
  ...mutation, checkId: id, status: { type: "string", enum: ["passed", "failed"] }, summary: { type: "string", minLength: 3, maxLength: 2000 }
43
43
  }, [...Object.keys(mutation), "checkId", "status", "summary"]),
44
44
  tool("platform_prepare_artifact_validation", "Prepare validation evidence for the exact private draft revision; missing required checks block readiness.", { ...session, artifactVersionId: id, deploymentRecordId: id, idempotencyKey: requestKey }, ["sessionId", "artifactVersionId", "deploymentRecordId"], true),
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.7";
45
+ export declare const HARNESS_MCP_VERSION = "0.9.9";
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[];
package/dist/index.js CHANGED
@@ -9,7 +9,7 @@ import path from "node:path";
9
9
  import { gzipSync } from "node:zlib";
10
10
  import { externalBuildHelperTools, EXTERNAL_BUILD_FORWARD_TOOLS, EXTERNAL_BUILD_SESSION_FORWARD_TOOLS, EXTERNAL_BUILD_SESSION_TOOLS } from "./build-session-tools.js";
11
11
  import { domainHelperTools, DOMAIN_FORWARD_TOOLS, DOMAIN_ERROR_CODES } from "./domain-tools.js";
12
- import { ARTIFACT_STARTER_IDS, artifactStarterRecipe, artifactStarterSource, findArtifactStarter } from "./artifact-starters.js";
12
+ import { ARTIFACT_STARTER_IDS, artifactStarterAppRoutes, artifactStarterRecipe, artifactStarterSource, findArtifactStarter } from "./artifact-starters.js";
13
13
  import { boundedTransfer, extractArtifactSourceArchive, MAX_SOURCE_ARCHIVE_BYTES, safeSourcePath } from "./source-checkout.js";
14
14
  import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
15
15
  import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -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.7";
22
+ export const HARNESS_MCP_VERSION = "0.9.9";
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([
@@ -947,8 +947,10 @@ export async function deployArtifactApp(opts, input, onProgress) {
947
947
  if (sessionId) {
948
948
  if (!servesBuild(opts))
949
949
  throw new Error("external_session_requires_build_surface");
950
- if (!sessionVersion || !idempotencyKey || !inspectedSourceHash || !expectedBundleSha256)
951
- throw new Error("build_session_deployment_arguments_required");
950
+ const missing = [["artifactVersionId", sessionVersion], ["idempotencyKey", idempotencyKey], ["inspectedSourceHash", inspectedSourceHash], ["expectedBundleSha256", expectedBundleSha256]]
951
+ .filter(([, value]) => !value).map(([name]) => name);
952
+ if (missing.length)
953
+ throw new Error(`build_session_deployment_arguments_required:${missing.join(",")}`);
952
954
  const session = asRecord(await callHostedBuildTool(opts, "platform_read_build_session", { sessionId }));
953
955
  // The server resolves a repeated operation key before checking current
954
956
  // version/source. Do not reject a lost-response retry using the newer read.
@@ -1388,7 +1390,7 @@ export async function initArtifactApp(opts, input) {
1388
1390
  build: { command: "node src/index.js --build", outputDir: "dist" },
1389
1391
  validation: { localCommand: "node src/index.js --test", testCommand: "node src/index.js --test --artifact-tests-json" },
1390
1392
  routes: starter
1391
- ? [{ path: "/", kind: "page", handler: "artifactApp" }, ...starter.routes.map((route) => ({ path: route.path, kind: "api", handler: "artifactApp" }))]
1393
+ ? [{ path: "/", kind: "page", handler: "artifactApp" }, ...artifactStarterAppRoutes(starter).map((route) => ({ path: route.path, kind: "api", handler: "artifactApp" }))]
1392
1394
  : [
1393
1395
  { path: "/", kind: "page", handler: "artifactApp" },
1394
1396
  { path: "/_artifact/health", kind: "api", handler: "artifactApp" }
@@ -1413,7 +1415,7 @@ export async function initArtifactApp(opts, input) {
1413
1415
  files: ["artifact-app.json", "package.json", "src/index.js"],
1414
1416
  ...(starter ? { starter: starter.id, recipe: artifactStarterRecipe(starter) } : {}),
1415
1417
  nextAction: starter
1416
- ? `Read the ${starter.id} recipe (docs id build-cookbook-example-${starter.id}) and replace each placeholder route. Its tests are scaffold checks, not proof of behavior. Then run npm test in ${appDir} and call platform_inspect_artifact_app with the same appDir before deployment.`
1418
+ ? `Read the ${starter.id} recipe (docs id build-cookbook-example-${starter.id}) and replace the placeholder content with the real behavior (platform-served /_artifact/data/* routes are declared in the manifest, not handled in app code). Its tests are scaffold checks, not proof of behavior. Then run npm test in ${appDir} and call platform_inspect_artifact_app with the same appDir before deployment.`
1417
1419
  : `Run npm test in ${appDir}, then call platform_inspect_artifact_app with the same appDir before deployment.`
1418
1420
  };
1419
1421
  }
@@ -1926,7 +1928,7 @@ const BUILD_MCP_TOOLS = [
1926
1928
  title: { type: "string" },
1927
1929
  description: { type: "string" },
1928
1930
  projectId: { type: "string", format: "uuid" },
1929
- expectedBundleSha256: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "Optional SHA-256 from platform_inspect_artifact_app; deployment fails locally if source changed." },
1931
+ expectedBundleSha256: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "SHA-256 of the bundle from platform_inspect_artifact_app. Required with sessionId, optional otherwise; deployment fails locally if source changed after inspection." },
1930
1932
  requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." },
1931
1933
  sessionId: { type: "string", format: "uuid" },
1932
1934
  artifactVersionId: { type: "string", format: "uuid", description: "Exact current version from the session or checkout; required with sessionId." },
@@ -2346,7 +2348,7 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
2346
2348
  idempotency_conflict: { retryable: false, recoveryAction: "This idempotencyKey was already used with different input, and Topline keeps the first call. Read the current state before acting (platform_read_build_session for a build session; the original receipt for a domain or address change); the first call may still be pending. To recover the first call, repeat its exact input. To make a different change, send it with a new idempotencyKey." },
2347
2349
  artifact_source_unavailable: { retryable: false, recoveryAction: "Topline can't export saved source for this version. For a new app, deploy your local source with platform_deploy_artifact_app first, wait until platform_deploy_operation says it is terminal, then check out. Retrying the checkout unchanged won't create source." },
2348
2350
  build_input_target_exists: { retryable: false, recoveryAction: "targetDir already exists, and checkout never writes into an existing directory, so your local edits there are safe. Pass a new directory path that doesn't exist yet." },
2349
- manual_result_requires_reviewer_skip: { retryable: false, recoveryAction: "A passing builder review needs a reviewer-only check that platform_run_acceptance_checks marked skipped for this version. Run the acceptance checks first, then record status passed (with evidence.reviewerCheck true) only for a check whose latest result is skipped." },
2351
+ manual_result_requires_reviewer_skip: { retryable: false, recoveryAction: "A passing builder review needs a reviewer-only check that platform_run_acceptance_checks marked skipped for this version. Run the acceptance checks first, then record a passed review only for a check whose latest result the runner recorded as a skipped reviewer check." },
2350
2352
  manual_result_requires_llm_review_check: { retryable: false, recoveryAction: "This check is run by platform_run_acceptance_checks, so it can't take a builder review. Record reviews only for reviewer-only checks." },
2351
2353
  invalid_arguments: { retryable: false, recoveryAction: "The package refused these arguments before calling Topline. The message names the argument that doesn't fit this tool's input schema; fix or drop it and call again." },
2352
2354
  build_session_not_active: { retryable: false, recoveryAction: "This build session is closed or expired, so it takes no more changes. Keep your local edits, call platform_start_build_session for the same artifactId with its current artifactVersionId (platform_artifact_status shows it), then repeat the refused call with the new sessionId." },
@@ -2374,7 +2376,8 @@ const BUILD_MCP_RECOVERY_ERROR_VALUES = {
2374
2376
  artifact_app_scaffold_starter_invalid: { retryable: false, recoveryAction: `Use one of the starters: ${ARTIFACT_STARTER_IDS.join(", ")}.` },
2375
2377
  artifact_app_scaffold_starter_shape_conflict: { retryable: false, recoveryAction: "A starter scaffolds the single shape; leave shape out or set it to single." },
2376
2378
  // Stale preconditions: the same input can never succeed, whatever HTTP status an older Topline sends.
2377
- artifact_version_conflict: { retryable: false, recoveryAction: "The session moved to a newer version. Read the session (platform_read_build_session), keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash." },
2379
+ artifact_version_conflict: { retryable: false, recoveryAction: "The session moved to a newer version. Read the session (platform_read_build_session). 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." },
2380
+ 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." },
2378
2381
  artifact_source_conflict: { retryable: false, recoveryAction: "inspectedSourceHash no longer matches the session's source fence. 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." },
2379
2382
  artifact_operation_pending: { retryable: false, recoveryAction: "Another operation on this app has not settled. Read it with platform_deploy_operation (a deploy that already landed settles on that read), or platform_read_build_session, then call this tool again once it is terminal." },
2380
2383
  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)." },
@@ -2,7 +2,7 @@
2
2
  "schemaVersion": 1,
3
3
  "package": {
4
4
  "name": "@topline-build/harness-mcp",
5
- "version": "0.9.7",
5
+ "version": "0.9.9",
6
6
  "bin": {
7
7
  "topline-mcp": "dist/cli.js"
8
8
  }
@@ -12,7 +12,7 @@
12
12
  "defaultVersion": "2025-11-25",
13
13
  "server": {
14
14
  "name": "topline-build-stdio",
15
- "version": "0.9.7"
15
+ "version": "0.9.9"
16
16
  }
17
17
  },
18
18
  "generatedFrom": {
@@ -353,7 +353,7 @@
353
353
  {
354
354
  "code": "manual_result_requires_reviewer_skip",
355
355
  "retryable": false,
356
- "recoveryAction": "A passing builder review needs a reviewer-only check that platform_run_acceptance_checks marked skipped for this version. Run the acceptance checks first, then record status passed (with evidence.reviewerCheck true) only for a check whose latest result is skipped."
356
+ "recoveryAction": "A passing builder review needs a reviewer-only check that platform_run_acceptance_checks marked skipped for this version. Run the acceptance checks first, then record a passed review only for a check whose latest result the runner recorded as a skipped reviewer check."
357
357
  },
358
358
  {
359
359
  "code": "manual_result_requires_llm_review_check",
@@ -473,7 +473,12 @@
473
473
  {
474
474
  "code": "artifact_version_conflict",
475
475
  "retryable": false,
476
- "recoveryAction": "The session moved to a newer version. Read the session (platform_read_build_session), keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash."
476
+ "recoveryAction": "The session moved to a newer version. Read the session (platform_read_build_session). 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."
477
+ },
478
+ {
479
+ "code": "build_session_deployment_arguments_required",
480
+ "retryable": false,
481
+ "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."
477
482
  },
478
483
  {
479
484
  "code": "artifact_source_conflict",
@@ -909,7 +914,7 @@
909
914
  "expectedBundleSha256": {
910
915
  "type": "string",
911
916
  "pattern": "^[0-9a-fA-F]{64}$",
912
- "description": "Optional SHA-256 from platform_inspect_artifact_app; deployment fails locally if source changed."
917
+ "description": "SHA-256 of the bundle from platform_inspect_artifact_app. Required with sessionId, optional otherwise; deployment fails locally if source changed after inspection."
913
918
  },
914
919
  "requestId": {
915
920
  "type": "string",
@@ -4350,7 +4355,7 @@
4350
4355
  },
4351
4356
  {
4352
4357
  "name": "platform_record_acceptance_review",
4353
- "description": "Record the builder's review of a reviewer-only acceptance check. A passed result needs a check that platform_run_acceptance_checks marked skipped for this version (run the checks first) and evidence.reviewerCheck true. Does not impersonate the independent validator or remove required checks.",
4358
+ "description": "Record the builder's review of a reviewer-only acceptance check. A passed result is accepted only for a check whose latest result platform_run_acceptance_checks recorded as a skipped reviewer check for this version, so run the checks first. Does not impersonate the independent validator or remove required checks.",
4354
4359
  "annotations": {
4355
4360
  "title": "Platform Record Acceptance Review",
4356
4361
  "readOnlyHint": false,
@@ -2,7 +2,7 @@
2
2
 
3
3
  > Generated from `src/index.ts#BUILD_MCP_TOOLS`. Do not edit this file by hand.
4
4
 
5
- Package: `@topline-build/harness-mcp@0.9.7`
5
+ Package: `@topline-build/harness-mcp@0.9.9`
6
6
  Transport: `stdio`
7
7
  Default protocol: `2025-11-25`
8
8
  Canonical guide: https://topline.build/docs/build-mcp-guide
@@ -67,7 +67,7 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
67
67
  - `domain_result_unknown` (not automatically retryable): The response did not establish an outcome. Recover the original receipt through platform_get_artifact_address (saved artifactId and apply key) or platform_read_artifact_domains (request/verify kind and key). Preserve the original plan/domain/input/key; an absent, pending or expired receipt does not authorize a fresh key. No mutation is replayed automatically.
68
68
  - `artifact_source_unavailable` (not automatically retryable): Topline can't export saved source for this version. For a new app, deploy your local source with platform_deploy_artifact_app first, wait until platform_deploy_operation says it is terminal, then check out. Retrying the checkout unchanged won't create source.
69
69
  - `build_input_target_exists` (not automatically retryable): targetDir already exists, and checkout never writes into an existing directory, so your local edits there are safe. Pass a new directory path that doesn't exist yet.
70
- - `manual_result_requires_reviewer_skip` (not automatically retryable): A passing builder review needs a reviewer-only check that platform_run_acceptance_checks marked skipped for this version. Run the acceptance checks first, then record status passed (with evidence.reviewerCheck true) only for a check whose latest result is skipped.
70
+ - `manual_result_requires_reviewer_skip` (not automatically retryable): A passing builder review needs a reviewer-only check that platform_run_acceptance_checks marked skipped for this version. Run the acceptance checks first, then record a passed review only for a check whose latest result the runner recorded as a skipped reviewer check.
71
71
  - `manual_result_requires_llm_review_check` (not automatically retryable): This check is run by platform_run_acceptance_checks, so it can't take a builder review. Record reviews only for reviewer-only checks.
72
72
  - `build_session_not_active` (not automatically retryable): This build session is closed or expired, so it takes no more changes. Keep your local edits, call platform_start_build_session for the same artifactId with its current artifactVersionId (platform_artifact_status shows it), then repeat the refused call with the new sessionId.
73
73
  - `build_session_tool_unavailable` (not automatically retryable): The connection's hosted Build tool list does not offer this build session tool, so the package does not list or run it. Call platform_capability_status to see what is missing, such as a scope or capability, and reconnect through browser sign-in with any missing scope. The package asks the host to list tools again, so the tool comes back once Topline offers it.
@@ -91,7 +91,8 @@ Tool failures set `isError: true` and return `structuredContent.error` with `cod
91
91
  - `artifact_app_scaffold_shape_invalid` (not automatically retryable): Use shape single or web-and-api.
92
92
  - `artifact_app_scaffold_starter_invalid` (not automatically retryable): Use one of the starters: bounded-bedrock-assistant, cache-warmed-multi-source-dashboard, internal-action-tool, live-operations-dashboard, materialized-sql-data-product, precomputed-s3-report, private-api-first-app, viewer-scoped-customer-portal.
93
93
  - `artifact_app_scaffold_starter_shape_conflict` (not automatically retryable): A starter scaffolds the single shape; leave shape out or set it to single.
94
- - `artifact_version_conflict` (not automatically retryable): The session moved to a newer version. Read the session (platform_read_build_session), keep your local edits, run platform_inspect_artifact_app again, then deploy with the current artifactVersionId and the new inspectedSourceHash.
94
+ - `artifact_version_conflict` (not automatically retryable): The session moved to a newer version. Read the session (platform_read_build_session). 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.
95
+ - `build_session_deployment_arguments_required` (not automatically retryable): 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.
95
96
  - `artifact_source_conflict` (not automatically retryable): inspectedSourceHash no longer matches the session's source fence. 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.
96
97
  - `artifact_operation_pending` (not automatically retryable): Another operation on this app has not settled. Read it with platform_deploy_operation (a deploy that already landed settles on that read), or platform_read_build_session, then call this tool again once it is terminal.
97
98
  - `artifact_deploy_in_flight` (retryable): 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).
@@ -568,7 +569,7 @@ Input schema:
568
569
  "expectedBundleSha256": {
569
570
  "type": "string",
570
571
  "pattern": "^[0-9a-fA-F]{64}$",
571
- "description": "Optional SHA-256 from platform_inspect_artifact_app; deployment fails locally if source changed."
572
+ "description": "SHA-256 of the bundle from platform_inspect_artifact_app. Required with sessionId, optional otherwise; deployment fails locally if source changed after inspection."
572
573
  },
573
574
  "requestId": {
574
575
  "type": "string",
@@ -4346,7 +4347,7 @@ Output schema:
4346
4347
 
4347
4348
  ### `platform_record_acceptance_review`
4348
4349
 
4349
- Record the builder's review of a reviewer-only acceptance check. A passed result needs a check that platform_run_acceptance_checks marked skipped for this version (run the checks first) and evidence.reviewerCheck true. Does not impersonate the independent validator or remove required checks.
4350
+ Record the builder's review of a reviewer-only acceptance check. A passed result is accepted only for a check whose latest result platform_run_acceptance_checks recorded as a skipped reviewer check for this version, so run the checks first. Does not impersonate the independent validator or remove required checks.
4350
4351
 
4351
4352
  Safety: read-only=false, destructive=false, idempotent=true, open-world=true.
4352
4353
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@topline-build/harness-mcp",
3
- "version": "0.9.7",
3
+ "version": "0.9.9",
4
4
  "description": "Topline Build MCP for creating and deploying artifact app drafts.",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",