{"record":{"id":"b9efa74dbd69e8e9","repo":"JuliusBrussee/caveman","slug":"cave-harness-upstream-version-unresolvable","errorCode":"cave_${harness}_upstream_version_unresolvable","errorMessage":"cave_${harness}_upstream_version_unresolvable","messagePattern":"cave_(.+?)_upstream_version_unresolvable","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"packages/agent/src/adapters.ts","lineNumber":586,"sourceCode":"    }\n  } catch {\n    // Not resolvable at all.\n  }\n  return undefined;\n}\n\nfunction assertSupportedUpstream(\n  identity: HarnessAdapterIdentity,\n  expected: string,\n  harness: string,\n  pkg: string,\n): void {\n  // The pin is enforced against the INSTALLED version, and the caller's claimed\n  // upstreamVersion must match what is actually installed — a claim alone can no\n  // longer authorize execution.\n  const installed = installedPackageVersion(pkg);\n  if (installed === undefined) {\n    throw new Error(`cave_${harness}_upstream_version_unresolvable`);\n  }\n  if (installed !== expected) {\n    throw new Error(`cave_${harness}_upstream_version_unsupported`);\n  }\n  if (identity.upstreamVersion !== installed) {\n    throw new Error(`cave_${harness}_upstream_version_mismatch`);\n  }\n}\n\nfunction canonicalRecord(value: Readonly<Record<string, unknown>>): Readonly<Record<string, unknown>> {\n  let encoded: string;\n  try {\n    encoded = stableStringify(value);\n  } catch {\n    throw new Error(\"cave_harness_wire_contract_invalid\");\n  }\n  const decoded = JSON.parse(encoded) as unknown;\n  if (!isRecord(decoded)) throw new Error(\"cave_harness_wire_contract_invalid\");","sourceCodeStart":568,"sourceCodeEnd":604,"githubUrl":"https://github.com/JuliusBrussee/caveman/blob/27d5a3981a347890211bb1bf2439e5c821a63bc9/packages/agent/src/adapters.ts#L568-L604","documentation":"The adapter pins each harness to an exact upstream version (Vercel AI SDK 7.0.43, Eve 0.29.2, Mastra 1.55.0) and enforces the pin against what is ACTUALLY installed, resolved via `import.meta.resolve` of the package's own package.json. `cave_${harness}_upstream_version_unresolvable` means `installedPackageVersion(pkg)` returned `undefined`: the adapter could not read a version for the installed package at all, so pin enforcement is impossible and the call fails closed. A caller-claimed version can never substitute for the resolved one.","triggerScenarios":"The harness package (`ai`, `@eve/...`, or `@mastra/*`) is not installed in the runtime resolving the adapter; its package.json cannot be read (permissions, corrupted install); the package's exports map hides `package.json` AND the fallback walk-up from the entry file fails; pnpm/yarn PnP layouts that defeat both resolution paths.","commonSituations":"Deploying to an environment where the adapter package was bundled/externalized but the harness dependency was pruned by tree-shaking or `--production` install pruning; a corrupted node_modules after an interrupted install; a bundler (esbuild/webpack) rewriting `import.meta.resolve` so it throws at runtime; missing optional peer dependency that was never installed.","solutions":["Install the exact pinned harness package in the runtime environment: `npm install ai@7.0.43` (or the Eve/Mastra pin shown in the adapter error's harness name).","Verify resolution at runtime: `node -e \"console.log(import.meta.resolve('ai/package.json'))\"` from your app's entry; if it throws, fix the install layout.","If you use a bundler, mark the harness package as external so `import.meta.resolve`/file reads still work.","Re-run `pnpm install` after deleting lockfile-shadowed `node_modules` if the install is corrupted."],"exampleFix":"// before: harness dependency pruned or never installed\n// package.json deps: { \"@caveman-ai/agent\": \"...\" } // no \"ai\"\n\n// after\n// package.json\n{\n  \"dependencies\": {\n    \"@caveman-ai/agent\": \"...\",\n    \"ai\": \"7.0.43\"\n  }\n}","handlingStrategy":"validation","validationCode":"import { createRequire } from \"node:module\";\nfunction canResolveInstalledVersion(pkg: string): boolean {\n  try {\n    const resolved = import.meta.resolve(`${pkg}/package.json`);\n    return typeof resolved === \"string\";\n  } catch {\n    try {\n      createRequire(import.meta.url).resolve(pkg);\n      return true;\n    } catch {\n      return false;\n    }\n  }\n}\nif (!canResolveInstalledVersion(\"ai\")) throw new Error(\"install ai@7.0.43 before running\");","typeGuard":null,"tryCatchPattern":"try {\n  await adapter.run(request);\n} catch (err) {\n  if (err instanceof Error && err.message.endsWith(\"_upstream_version_unresolvable\")) {\n    // dependency resolution failed: fix the install, surface a setup error to the operator\n  }\n}","preventionTips":["Declare the pinned harness package as a direct exact-pinned dependency.","Mark harness packages external when bundling so import.meta.resolve still works.","Add a startup doctor check that resolves each harness package.json version."],"tags":["adapter","version-pin","dependency-resolution","install"],"backgroundTag":null,"analyzedSha":"27d5a3981a347890211bb1bf2439e5c821a63bc9","analyzedAt":"2026-08-15T09:26:11.751Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}