@openclaw/plugin-inspector 0.3.16 → 0.3.17

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## Unreleased
 
+## 0.3.17 - 2026-06-29
+
+### Fixed
+
+- Detect deprecated session SDK read/write, file-path, and transcript helpers across source files, packaged `dist`/`build` artifacts, runtime session APIs, and dynamic SDK imports.
+
 ## 0.3.16 - 2026-06-23
 
 ### Fixed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw/plugin-inspector",
-  "version": "0.3.16",
+  "version": "0.3.17",
   "private": false,
   "description": "Offline compatibility inspector for OpenClaw plugins.",
   "type": "module",

package/src/fixture-summary.js

@@ -724,14 +724,39 @@ function classifySdkDeprecations({ fixture, inspection, fixtureReport, warnings,
     decisions.push({
       fixture: fixture.id,
       decision: "core-compat-adapter",
-      seam: "session-store",
-      action:
-        "Keep loadSessionStore compatibility active while plugin authors migrate to row-scoped session helpers.",
+      seam: sdkDeprecationSeamForCode(code),
+      action: sdkDeprecationActionForCode(code),
       evidence: findings.map((finding) => finding.ref).join(", "),
     });
   }
 }
 
+function sdkDeprecationSeamForCode(code) {
+  if (code === "sdk-session-file-helper") {
+    return "session-file";
+  }
+  if (code === "sdk-session-transcript-file-target" || code === "sdk-session-transcript-low-level") {
+    return "session-transcript";
+  }
+  return "session-store";
+}
+
+function sdkDeprecationActionForCode(code) {
+  if (code === "sdk-session-store-write") {
+    return "Keep whole-store session write compatibility active while plugin authors migrate to row-scoped session write helpers.";
+  }
+  if (code === "sdk-session-file-helper") {
+    return "Keep session file-path compatibility active while plugin authors migrate to session entry and transcript identity helpers.";
+  }
+  if (code === "sdk-session-transcript-file-target") {
+    return "Keep legacy transcript file target compatibility active while plugin authors migrate to structured transcript targets.";
+  }
+  if (code === "sdk-session-transcript-low-level") {
+    return "Keep low-level transcript write compatibility active while plugin authors migrate to structured transcript runtime helpers.";
+  }
+  return "Keep loadSessionStore compatibility active while plugin authors migrate to row-scoped session helpers.";
+}
+
 function classifySecurityManifestCoverage({ fixture, fixtureReport, warnings, decisions }) {
   for (const securityManifest of fixtureReport.securityManifests ?? []) {
     warnings.push({

package/src/inspector.js

@@ -95,10 +95,17 @@ export async function inspectPlugin(fixture, options = {}) {
     return emptyInspection(fixture, "missing");
   }
 
-  const files = await listSourceFiles(sourceRoot, { includeDist: Boolean(fixture.package) });
+  const packageInspection = await readPackageMetadata(config, checkoutPath, sourceRoot);
+  const includeBuildArtifacts = shouldScanBuildArtifacts(fixture, packageInspection);
+  const files = await listSourceFiles(sourceRoot, {
+    includeBuild: includeBuildArtifacts,
+    includeDist: includeBuildArtifacts,
+  });
   if (sourceRoot !== checkoutPath) {
     files.push(...(await listSourceFiles(checkoutPath, { shallowRootOnly: true })));
   }
+  files.push(...packageInspection.entrypointFiles);
+  const sourceFiles = uniquePaths(files);
 
   const hooks = new Set();
   const registrations = new Set();
@@ -107,7 +114,7 @@ export async function inspectPlugin(fixture, options = {}) {
   const sdkImportDetails = [];
   const sdkDeprecationDetails = [];
 
-  for (const filePath of files) {
+  for (const filePath of sourceFiles) {
     const text = await readFile(filePath, "utf8");
     const relativePath = path.relative(config.rootDir ?? process.cwd(), filePath);
     const sourceInspection = inspectSourceText(text, relativePath);
@@ -129,8 +136,6 @@ export async function inspectPlugin(fixture, options = {}) {
   }
 
   const manifestInspection = await readManifestContracts(config, checkoutPath, sourceRoot);
-  const packageInspection = await readPackageMetadata(config, checkoutPath, sourceRoot);
-
   return {
     id: fixture.id,
     status: "ok",
@@ -146,7 +151,7 @@ export async function inspectPlugin(fixture, options = {}) {
     packageEntrypoints: packageInspection.entrypoints,
     sdkImports: uniqueDetails(sdkImportDetails),
     sdkDeprecations: uniqueSdkDeprecations(sdkDeprecationDetails),
-    sourceFiles: files.map((filePath) => path.relative(config.rootDir ?? process.cwd(), filePath)).sort(),
+    sourceFiles: sourceFiles.map((filePath) => path.relative(config.rootDir ?? process.cwd(), filePath)).sort(),
   };
 }
 
@@ -418,18 +423,23 @@ async function readPackageMetadata(config, checkoutPath, sourceRoot) {
   const files = [];
   const errors = [];
   const entrypoints = new Set();
+  const entrypointFiles = new Set();
 
   for (const packageFile of packageFiles) {
     const relativePath = path.relative(config.rootDir ?? process.cwd(), packageFile);
     files.push(relativePath);
     try {
       const packageJson = JSON.parse(await readFile(packageFile, "utf8"));
-      collectEntrypoint(entrypoints, packageJson.main);
-      collectEntrypoint(entrypoints, packageJson.module);
-      collectEntrypoint(entrypoints, packageJson.openclaw?.entry);
-      collectEntrypoint(entrypoints, packageJson.openclaw?.entrypoint);
-      collectEntrypoint(entrypoints, packageJson.exports?.["."]?.import);
-      collectEntrypoint(entrypoints, packageJson.exports?.["."]?.default);
+      const packageDir = path.dirname(packageFile);
+      collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.main);
+      collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.module);
+      collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.entry);
+      collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.entrypoint);
+      collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.setupEntry);
+      collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.exports?.["."]?.import);
+      collectEntrypoint(entrypoints, entrypointFiles, packageDir, packageJson.exports?.["."]?.default);
+      collectEntrypoints(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.extensions);
+      collectEntrypoints(entrypoints, entrypointFiles, packageDir, packageJson.openclaw?.runtimeExtensions);
     } catch {
       errors.push(`${relativePath}: invalid JSON`);
     }
@@ -439,13 +449,58 @@ async function readPackageMetadata(config, checkoutPath, sourceRoot) {
     files: files.sort(),
     errors,
     entrypoints: [...entrypoints].sort(),
+    entrypointFiles: [...entrypointFiles].sort(),
   };
 }
 
-function collectEntrypoint(entrypoints, value) {
+function collectEntrypoints(entrypoints, entrypointFiles, packageDir, values) {
+  if (!Array.isArray(values)) {
+    return;
+  }
+  for (const value of values) {
+    collectEntrypoint(entrypoints, entrypointFiles, packageDir, value);
+  }
+}
+
+function collectEntrypoint(entrypoints, entrypointFiles, packageDir, value) {
   if (typeof value === "string" && value.length > 0) {
     entrypoints.add(value);
+    for (const candidate of entrypointCandidates(packageDir, value)) {
+      if (existsSync(candidate) && isSourceFile(path.basename(candidate), candidate.split(path.sep).join("/"))) {
+        entrypointFiles.add(candidate);
+        return;
+      }
+    }
+  }
+}
+
+function entrypointCandidates(packageDir, specifier) {
+  const resolved = path.resolve(packageDir, specifier);
+  if (path.extname(resolved)) {
+    return [resolved];
+  }
+  return [
+    resolved,
+    `${resolved}.js`,
+    `${resolved}.mjs`,
+    `${resolved}.cjs`,
+    `${resolved}.ts`,
+    path.join(resolved, "index.js"),
+    path.join(resolved, "index.mjs"),
+    path.join(resolved, "index.cjs"),
+    path.join(resolved, "index.ts"),
+  ];
+}
+
+function uniquePaths(paths) {
+  return [...new Set(paths)];
+}
+
+function shouldScanBuildArtifacts(fixture, packageInspection) {
+  if (fixture.package) {
+    return true;
   }
+  return packageInspection.entrypoints.some((entrypoint) => /(^|\/)(?:dist|build)\//.test(entrypoint));
 }
 
 async function listSourceFiles(root, options = {}) {
@@ -484,7 +539,7 @@ function shouldSkipDir(name, normalizedPath, options = {}) {
   return (
     name === "node_modules" ||
     (!options.includeDist && name === "dist") ||
-    name === "build" ||
+    (!options.includeBuild && name === "build") ||
     name === "coverage" ||
     name === ".git" ||
     name === "test" ||

package/src/issues.js

@@ -42,6 +42,10 @@ export const knownIssueCodes = new Set([
   "reserved-sdk-import",
   "security-manifest-schema-unavailable",
   "sdk-load-session-store",
+  "sdk-session-file-helper",
+  "sdk-session-store-write",
+  "sdk-session-transcript-file-target",
+  "sdk-session-transcript-low-level",
   "sdk-export-missing",
   "unrecognized-security-manifest",
 ]);
@@ -124,6 +128,58 @@ export const issueMetadataByCode = {
       ],
     ),
   },
+  "sdk-session-store-write": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "deprecated whole-store session write helper is still used",
+    authorRemediation: migrationRemediation(
+      "Replace deprecated whole-store session writes with row-scoped session helpers.",
+      [
+        "Use patchSessionEntry(...) when updating fields on an existing session entry.",
+        "Use upsertSessionEntry(...) when replacing or creating a session entry.",
+      ],
+    ),
+  },
+  "sdk-session-file-helper": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "deprecated session file-path helper is still used",
+    authorRemediation: migrationRemediation(
+      "Replace deprecated session file-path helpers with session entry and transcript identity APIs.",
+      [
+        "Use getSessionEntry(...) to read session metadata by agent/session identity.",
+        "Use patchSessionEntry(...) or upsertSessionEntry(...) to persist session metadata.",
+      ],
+    ),
+  },
+  "sdk-session-transcript-file-target": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "deprecated transcript file target helper is still used",
+    authorRemediation: migrationRemediation(
+      "Replace legacy transcript file targets with public transcript identity or target helpers.",
+      [
+        "Use resolveSessionTranscriptIdentity(...) when you only need public session identity.",
+        "Use resolveSessionTranscriptTarget(...) when you need a structured transcript operation target.",
+      ],
+    ),
+  },
+  "sdk-session-transcript-low-level": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "deprecated low-level transcript helper is still used",
+    authorRemediation: migrationRemediation(
+      "Replace low-level transcript writes with the structured transcript runtime helpers.",
+      [
+        "Use appendSessionTranscriptMessageByIdentity(...) for transcript appends.",
+        "Use publishSessionTranscriptUpdateByIdentity(...) for transcript update notifications.",
+      ],
+    ),
+  },
   "sdk-export-missing": {
     severity: "P1",
     owner: "core",
@@ -568,6 +624,10 @@ function issueClassFor(code, options) {
       "legacy-root-sdk-import",
       "provider-auth-env-vars",
       "sdk-load-session-store",
+      "sdk-session-file-helper",
+      "sdk-session-store-write",
+      "sdk-session-transcript-file-target",
+      "sdk-session-transcript-low-level",
     ].includes(code)
   ) {
     return "deprecation-warning";

package/src/sdk-deprecation-rules.js

@@ -1,16 +1,53 @@
-const loadSessionStoreReplacement =
+const sessionStoreReadReplacement =
   "getSessionEntry(...) / listSessionEntries(...) for reads and patchSessionEntry(...) / upsertSessionEntry(...) for writes";
+const sessionStoreWriteReplacement = "patchSessionEntry(...) / upsertSessionEntry(...) for row-scoped writes";
+const sessionFileReplacement = "session entries and transcript identity helpers instead of persisted file paths";
+const sessionTranscriptReplacement =
+  "resolveSessionTranscriptTarget(...), appendSessionTranscriptMessageByIdentity(...), and publishSessionTranscriptUpdateByIdentity(...)";
 
-const loadSessionStoreSpecifiers = new Set([
+const sdkSessionSpecifiers = new Set([
   "openclaw/plugin-sdk/config-runtime",
+  "openclaw/plugin-sdk/mattermost",
+  "openclaw/plugin-sdk/agent-harness-runtime",
   "openclaw/plugin-sdk/session-store-runtime",
+  "openclaw/plugin-sdk/session-transcript-runtime",
 ]);
 
 export const pluginSdkDeprecationRules = [
   {
     code: "sdk-load-session-store",
+    symbols: new Set(["loadSessionStore"]),
     title: "deprecated whole-store session helper is still used",
-    replacement: loadSessionStoreReplacement,
+    replacement: sessionStoreReadReplacement,
+    message: (symbol, replacement) => `${symbol} keeps the legacy whole-store session shape; use ${replacement}.`,
+  },
+  {
+    code: "sdk-session-store-write",
+    symbols: new Set(["saveSessionStore", "updateSessionStore"]),
+    title: "deprecated whole-store session write helper is still used",
+    replacement: sessionStoreWriteReplacement,
+    message: (symbol, replacement) => `${symbol} writes the legacy whole-store session shape; use ${replacement}.`,
+  },
+  {
+    code: "sdk-session-file-helper",
+    symbols: new Set(["resolveSessionFilePath", "resolveAndPersistSessionFile"]),
+    title: "deprecated session file-path helper is still used",
+    replacement: sessionFileReplacement,
+    message: (symbol, replacement) => `${symbol} depends on legacy session transcript file paths; use ${replacement}.`,
+  },
+  {
+    code: "sdk-session-transcript-file-target",
+    symbols: new Set(["resolveSessionTranscriptLegacyFileTarget"]),
+    title: "deprecated transcript file target helper is still used",
+    replacement: "resolveSessionTranscriptTarget(...) or resolveSessionTranscriptIdentity(...)",
+    message: (symbol, replacement) => `${symbol} exposes legacy transcript file targets; use ${replacement}.`,
+  },
+  {
+    code: "sdk-session-transcript-low-level",
+    symbols: new Set(["appendSessionTranscriptMessage", "emitSessionTranscriptUpdate"]),
+    title: "deprecated low-level transcript helper is still used",
+    replacement: sessionTranscriptReplacement,
+    message: (symbol, replacement) => `${symbol} bypasses the structured transcript runtime surface; use ${replacement}.`,
   },
 ];
 
@@ -18,9 +55,7 @@ export function inspectSdkDeprecations(text, filePath = "source.js", rules = plu
   const findings = [];
 
   for (const rule of rules) {
-    if (rule.code === "sdk-load-session-store") {
-      collectLoadSessionStoreDeprecations(findings, { text, filePath, rule });
-    }
+    collectSdkHelperDeprecations(findings, { text, filePath, rule });
   }
 
   return uniqueFindings(findings)
@@ -28,12 +63,13 @@ export function inspectSdkDeprecations(text, filePath = "source.js", rules = plu
     .map(({ offset, ...finding }) => finding);
 }
 
-function collectLoadSessionStoreDeprecations(findings, context) {
+function collectSdkHelperDeprecations(findings, context) {
   collectNamedImportDeprecations(findings, context);
   collectNamedReexportDeprecations(findings, context);
   collectNamedRequireDeprecations(findings, context);
   collectNamespaceUsageDeprecations(findings, context);
   collectNamespaceRequireDeprecations(findings, context);
+  collectDynamicImportNamespaceDeprecations(findings, context);
   collectRuntimeUsageDeprecations(findings, context);
   collectRuntimeAliasUsageDeprecations(findings, context);
 }
@@ -43,16 +79,17 @@ function collectNamedImportDeprecations(findings, context) {
     /\bimport\s+(?:type\s+)?(?:[A-Za-z_$][\w$]*\s*,\s*)?{([^}]+)}\s*from\s*["'`]([^"'`]+)["'`]/g;
   for (const match of context.text.matchAll(regex)) {
     const specifier = match[2];
-    if (!loadSessionStoreSpecifiers.has(specifier)) {
+    if (!sdkSessionSpecifiers.has(specifier)) {
       continue;
     }
     for (const binding of parseNamedBindings(match[1])) {
-      if (binding.exported !== "loadSessionStore") {
+      if (!context.rule.symbols.has(binding.exported)) {
         continue;
       }
       findings.push(
         buildFinding(context.rule, {
-          surface: `${specifier} import`,
+          surface: `${specifier} ${binding.exported} import`,
+          symbol: binding.exported,
           sourceText: context.text,
           filePath: context.filePath,
           offset: (match.index ?? 0) + match[0].lastIndexOf(binding.local),
@@ -66,16 +103,17 @@ function collectNamedReexportDeprecations(findings, context) {
   const regex = /\bexport\s*{([^}]+)}\s*from\s*["'`]([^"'`]+)["'`]/g;
   for (const match of context.text.matchAll(regex)) {
     const specifier = match[2];
-    if (!loadSessionStoreSpecifiers.has(specifier)) {
+    if (!sdkSessionSpecifiers.has(specifier)) {
       continue;
     }
     for (const binding of parseNamedBindings(match[1])) {
-      if (binding.exported !== "loadSessionStore") {
+      if (!context.rule.symbols.has(binding.exported)) {
         continue;
       }
       findings.push(
         buildFinding(context.rule, {
-          surface: `${specifier} re-export`,
+          surface: `${specifier} ${binding.exported} re-export`,
+          symbol: binding.exported,
           sourceText: context.text,
           filePath: context.filePath,
           offset: (match.index ?? 0) + match[0].lastIndexOf(binding.local),
@@ -89,16 +127,17 @@ function collectNamedRequireDeprecations(findings, context) {
   const regex = /\b(?:const|let|var)\s+{([^}]+)}\s*=\s*require\(\s*["'`]([^"'`]+)["'`]\s*\)/g;
   for (const match of context.text.matchAll(regex)) {
     const specifier = match[2];
-    if (!loadSessionStoreSpecifiers.has(specifier)) {
+    if (!sdkSessionSpecifiers.has(specifier)) {
       continue;
     }
     for (const binding of parseNamedBindings(match[1], { aliasSeparator: ":" })) {
-      if (binding.exported !== "loadSessionStore") {
+      if (!context.rule.symbols.has(binding.exported)) {
         continue;
       }
       findings.push(
         buildFinding(context.rule, {
-          surface: `${specifier} require`,
+          surface: `${specifier} ${binding.exported} require`,
+          symbol: binding.exported,
           sourceText: context.text,
           filePath: context.filePath,
           offset: (match.index ?? 0) + match[0].lastIndexOf(binding.local),
@@ -109,21 +148,24 @@ function collectNamedRequireDeprecations(findings, context) {
 }
 
 function collectMemberCallDeprecations(findings, context, options) {
-  forEachMethodCall(context.text, "loadSessionStore", (offset) => {
-    // Normalize transparent parentheses and optional-chained member links before matching.
-    const receiver = readNormalizedCallReceiver(context.text, offset);
-    if (!receiver || !options.receiverMatcher(receiver)) {
-      return;
-    }
-    findings.push(
-      buildFinding(context.rule, {
-        surface: options.surface,
-        sourceText: context.text,
-        filePath: context.filePath,
-        offset,
-      }),
-    );
-  });
+  for (const symbol of context.rule.symbols) {
+    forEachMethodCall(context.text, symbol, (offset) => {
+      // Normalize transparent parentheses and optional-chained member links before matching.
+      const receiver = readNormalizedCallReceiver(context.text, offset);
+      if (!receiver || !options.receiverMatcher(receiver)) {
+        return;
+      }
+      findings.push(
+        buildFinding(context.rule, {
+          surface: `${options.surface} ${symbol}`,
+          symbol,
+          sourceText: context.text,
+          filePath: context.filePath,
+          offset,
+        }),
+      );
+    });
+  }
 }
 
 function forEachMethodCall(text, methodName, visit) {
@@ -259,7 +301,11 @@ function isIdentifierBoundary(text, offset) {
 }
 
 function isRuntimeSessionReceiver(receiver) {
-  return /^(?:[A-Za-z_$][A-Za-z0-9_$]*|this)\.runtime\.agent\.session$/.test(receiver);
+  return (
+    /(?:^|\.)(?:[A-Za-z_$][A-Za-z0-9_$]*|this)\.runtime\.agent\.session$/.test(receiver) ||
+    /^(?:runtime|[A-Za-z_$][A-Za-z0-9_$]*Runtime)\.agent\.session$/.test(receiver) ||
+    /^(?:agentRuntime|[A-Za-z_$][A-Za-z0-9_$]*AgentRuntime)\.session$/.test(receiver)
+  );
 }
 
 function collectNamespaceUsageDeprecations(findings, context) {
@@ -267,7 +313,7 @@ function collectNamespaceUsageDeprecations(findings, context) {
   for (const match of context.text.matchAll(regex)) {
     const local = match[1];
     const specifier = match[2];
-    if (!loadSessionStoreSpecifiers.has(specifier)) {
+    if (!sdkSessionSpecifiers.has(specifier)) {
       continue;
     }
     collectMemberCallDeprecations(findings, context, {
@@ -282,7 +328,7 @@ function collectNamespaceRequireDeprecations(findings, context) {
   for (const match of context.text.matchAll(regex)) {
     const local = match[1];
     const specifier = match[2];
-    if (!loadSessionStoreSpecifiers.has(specifier)) {
+    if (!sdkSessionSpecifiers.has(specifier)) {
       continue;
     }
     collectMemberCallDeprecations(findings, context, {
@@ -292,6 +338,22 @@ function collectNamespaceRequireDeprecations(findings, context) {
   }
 }
 
+function collectDynamicImportNamespaceDeprecations(findings, context) {
+  const regex =
+    /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:await\s+)?import\(\s*["'`]([^"'`]+)["'`]\s*\)/g;
+  for (const match of context.text.matchAll(regex)) {
+    const local = match[1];
+    const specifier = match[2];
+    if (!sdkSessionSpecifiers.has(specifier)) {
+      continue;
+    }
+    collectMemberCallDeprecations(findings, context, {
+      receiverMatcher: (receiver) => receiver === local,
+      surface: `${specifier} dynamic import namespace access`,
+    });
+  }
+}
+
 function collectRuntimeUsageDeprecations(findings, context) {
   collectMemberCallDeprecations(findings, context, {
     receiverMatcher: isRuntimeSessionReceiver,
@@ -509,10 +571,11 @@ function buildFinding(rule, details) {
   const refLine = lineForOffset(details.sourceText, details.offset);
   return {
     code: rule.code,
+    symbol: details.symbol,
     surface: details.surface,
     replacement: rule.replacement,
     ref: `${details.filePath}:${refLine}`,
-    message: `loadSessionStore keeps the legacy whole-store session shape; use ${rule.replacement}.`,
+    message: rule.message(details.symbol, rule.replacement),
     offset: details.offset,
   };
 }
@@ -520,7 +583,7 @@ function buildFinding(rule, details) {
 function uniqueFindings(findings) {
   const byKey = new Map();
   for (const finding of findings) {
-    byKey.set(`${finding.code}:${finding.surface}:${finding.ref}`, finding);
+    byKey.set(`${finding.code}:${finding.symbol}:${finding.surface}:${finding.ref}`, finding);
   }
   return [...byKey.values()];
 }