@openclaw/plugin-inspector 0.3.13 → 0.3.14

package/CHANGELOG.md

@@ -1,6 +1,10 @@
 # Changelog
 
-## Unreleased
+## 0.3.14 - 2026-06-11
+
+### Changed
+
+- Flag deprecated `loadSessionStore(...)` whole-store session helper usage as an author-facing deprecation warning while keeping speculative transcript-identity migration rules out of default inspection. Thanks @jalehman.
 
 ## 0.3.13 - 2026-06-09
 

package/README.md

@@ -299,7 +299,7 @@ Important report sections:
 | `status` | `pass` unless hard breakages exist. |
 | `summary` | Counts for fixtures, breakages, warnings, suggestions, issues, issue classes, and contract probes. |
 | `targetOpenClaw` | Status and public compatibility data read from the optional OpenClaw checkout. |
-| `fixtures` | Per-plugin metadata, hooks, registrations, manifest contracts, package data, and SDK imports. |
+| `fixtures` | Per-plugin metadata, hooks, registrations, manifest contracts, package data, SDK imports, and SDK deprecation evidence. |
 | `breakages` | Blocking compatibility failures. |
 | `warnings` / `suggestions` | Non-blocking compatibility findings. |
 | `issues` | Normalized issue rows with severity and class. |
@@ -311,6 +311,9 @@ Default `check`, `ci`, and `batch` reports include both author-facing and
 internal findings. Pass `--author-facing` when producing plugin-author output;
 that filtered view includes only findings with `authorRemediation.summary` and
 `authorRemediation.docsUrl`.
+Current author-facing deprecation warnings include deprecated SDK helpers such
+as `loadSessionStore(...)` when a plugin still depends on the legacy whole-store
+session shape.
 
 ## CI Policy And Shared Reporting Primitives
 

package/package.json

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

package/src/fixture-summary.js

@@ -49,6 +49,7 @@ export async function buildCompatibilityFixtureReport({ fixture, inspection, che
     packages: packageSummaries,
     sdkImports,
     sdkImportDetails: inspection.sdkImports ?? [],
+    sdkDeprecations: inspection.sdkDeprecations ?? [],
   };
 }
 
@@ -496,6 +497,7 @@ export function classifyCompatibilityFixture({ fixture, inspection, fixtureRepor
   logs.push(...packageContracts.logs);
   decisions.push(...packageContracts.decisions);
   classifySecurityManifestCoverage({ fixture, fixtureReport, warnings, decisions });
+  classifySdkDeprecations({ fixture, inspection, fixtureReport, warnings, decisions });
 
   for (const pluginManifest of fixtureReport.pluginManifests) {
     const providerAuthKeys = Object.keys(pluginManifest.providerAuthEnvVars ?? {});
@@ -702,6 +704,34 @@ export function classifyCompatibilityFixture({ fixture, inspection, fixtureRepor
   return { warnings, suggestions, logs, decisions };
 }
 
+function classifySdkDeprecations({ fixture, inspection, fixtureReport, warnings, decisions }) {
+  const grouped = new Map();
+  for (const finding of fixtureReport.sdkDeprecations ?? inspection.sdkDeprecations ?? []) {
+    const existing = grouped.get(finding.code) ?? [];
+    existing.push(finding);
+    grouped.set(finding.code, existing);
+  }
+
+  for (const [code, findings] of grouped) {
+    const first = findings[0];
+    warnings.push({
+      fixture: fixture.id,
+      code,
+      level: "warning",
+      message: first.message,
+      evidence: findings.map((finding) => `${finding.surface} @ ${finding.ref}`),
+    });
+    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.",
+      evidence: findings.map((finding) => finding.ref).join(", "),
+    });
+  }
+}
+
 function classifySecurityManifestCoverage({ fixture, fixtureReport, warnings, decisions }) {
   for (const securityManifest of fixtureReport.securityManifests ?? []) {
     warnings.push({

package/src/inspector.js

@@ -10,6 +10,7 @@ import { fixtureCheckoutPath, fixtureSourceRoot } from "./config.js";
 import { buildCompatibilityFixtureReport } from "./fixture-summary.js";
 import { readOpenClawTargetSurface } from "./openclaw-target.js";
 import { buildCompatibilityReport, buildReport } from "./report.js";
+import { inspectSdkDeprecations } from "./sdk-deprecation-rules.js";
 
 const execFileAsync = promisify(execFile);
 const registrationEquivalents = new Map([
@@ -104,6 +105,7 @@ export async function inspectPlugin(fixture, options = {}) {
   const hookDetails = [];
   const registrationDetails = [];
   const sdkImportDetails = [];
+  const sdkDeprecationDetails = [];
 
   for (const filePath of files) {
     const text = await readFile(filePath, "utf8");
@@ -121,6 +123,9 @@ export async function inspectPlugin(fixture, options = {}) {
     for (const sdkImport of sourceInspection.sdkImports) {
       sdkImportDetails.push(sdkImport);
     }
+    for (const sdkDeprecation of sourceInspection.sdkDeprecations) {
+      sdkDeprecationDetails.push(sdkDeprecation);
+    }
   }
 
   const manifestInspection = await readManifestContracts(config, checkoutPath, sourceRoot);
@@ -140,6 +145,7 @@ export async function inspectPlugin(fixture, options = {}) {
     packageErrors: packageInspection.errors,
     packageEntrypoints: packageInspection.entrypoints,
     sdkImports: uniqueDetails(sdkImportDetails),
+    sdkDeprecations: uniqueSdkDeprecations(sdkDeprecationDetails),
     sourceFiles: files.map((filePath) => path.relative(config.rootDir ?? process.cwd(), filePath)).sort(),
   };
 }
@@ -160,11 +166,13 @@ export function inspectSourceText(text, filePath = "source.js") {
     filePath,
     "specifier",
   );
+  const sdkDeprecations = inspectSdkDeprecations(searchableText, filePath);
 
   return {
     hooks,
     registrations,
     sdkImports,
+    sdkDeprecations,
   };
 }
 
@@ -353,6 +361,7 @@ function emptyInspection(fixture, status) {
     packageErrors: [],
     packageEntrypoints: [],
     sdkImports: [],
+    sdkDeprecations: [],
     sourceFiles: [],
   };
 }
@@ -554,3 +563,11 @@ function uniqueDetails(details) {
   }
   return [...byKey.values()];
 }
+
+function uniqueSdkDeprecations(details) {
+  const byKey = new Map();
+  for (const detail of [...details].sort((left, right) => left.ref.localeCompare(right.ref))) {
+    byKey.set(`${detail.code}:${detail.surface}:${detail.ref}`, detail);
+  }
+  return [...byKey.values()];
+}

package/src/issues.js

@@ -41,6 +41,7 @@ export const knownIssueCodes = new Set([
   "runtime-tool-capture",
   "reserved-sdk-import",
   "security-manifest-schema-unavailable",
+  "sdk-load-session-store",
   "sdk-export-missing",
   "unrecognized-security-manifest",
 ]);
@@ -110,6 +111,19 @@ export const issueMetadataByCode = {
       ],
     ),
   },
+  "sdk-load-session-store": {
+    severity: "P2",
+    owner: "core",
+    decision: "core-compat-adapter",
+    title: "deprecated whole-store session helper is still used",
+    authorRemediation: migrationRemediation(
+      "Replace deprecated loadSessionStore whole-store access with row-scoped session helpers.",
+      [
+        "Use getSessionEntry(...) or listSessionEntries(...) for reads instead of cloning the whole session store.",
+        "Use patchSessionEntry(...) or upsertSessionEntry(...) for writes instead of mutating and saving a whole-store object.",
+      ],
+    ),
+  },
   "sdk-export-missing": {
     severity: "P1",
     owner: "core",
@@ -545,7 +559,16 @@ function issueClassFor(code, options) {
   if (code === "missing-compat-record") {
     return "compat-gap";
   }
-  if (options.deprecated || ["channel-env-vars", "legacy-before-agent-start", "legacy-root-sdk-import", "provider-auth-env-vars"].includes(code)) {
+  if (
+    options.deprecated ||
+    [
+      "channel-env-vars",
+      "legacy-before-agent-start",
+      "legacy-root-sdk-import",
+      "provider-auth-env-vars",
+      "sdk-load-session-store",
+    ].includes(code)
+  ) {
     return "deprecation-warning";
   }
   if (

package/src/report.js

@@ -26,6 +26,7 @@ export function buildReport({ config, inspections, failures = [], generatedAt =
       registrations: inspection.registrations,
       manifestContracts: inspection.manifestContracts,
       sdkImports: inspection.sdkImports,
+      sdkDeprecations: inspection.sdkDeprecations,
       sourceFiles: inspection.sourceFiles,
       manifestFiles: inspection.manifestFiles,
       packageFiles: inspection.packageFiles,
@@ -477,6 +478,7 @@ function defaultCompatibilityFixtureReport({ fixture, inspection }) {
     packages: [],
     sdkImports: inspection.sdkImports.map((sdkImport) => sdkImport.specifier).filter(Boolean),
     sdkImportDetails: inspection.sdkImports,
+    sdkDeprecations: inspection.sdkDeprecations,
   };
 }
 
@@ -495,6 +497,7 @@ function normalizeInspection(inspection, fixture) {
     packageErrors: [],
     packageEntrypoints: [],
     sdkImports: [],
+    sdkDeprecations: [],
     sourceFiles: [],
     ...inspection,
   };

package/src/sdk-deprecation-rules.js

@@ -0,0 +1,369 @@
+const loadSessionStoreReplacement =
+  "getSessionEntry(...) / listSessionEntries(...) for reads and patchSessionEntry(...) / upsertSessionEntry(...) for writes";
+
+const loadSessionStoreSpecifiers = new Set([
+  "openclaw/plugin-sdk/config-runtime",
+  "openclaw/plugin-sdk/session-store-runtime",
+]);
+
+export const pluginSdkDeprecationRules = [
+  {
+    code: "sdk-load-session-store",
+    title: "deprecated whole-store session helper is still used",
+    replacement: loadSessionStoreReplacement,
+  },
+];
+
+export function inspectSdkDeprecations(text, filePath = "source.js", rules = pluginSdkDeprecationRules) {
+  const findings = [];
+
+  for (const rule of rules) {
+    if (rule.code === "sdk-load-session-store") {
+      collectLoadSessionStoreDeprecations(findings, { text, filePath, rule });
+    }
+  }
+
+  return uniqueFindings(findings)
+    .sort((left, right) => left.offset - right.offset || left.surface.localeCompare(right.surface))
+    .map(({ offset, ...finding }) => finding);
+}
+
+function collectLoadSessionStoreDeprecations(findings, context) {
+  collectNamedImportDeprecations(findings, context);
+  collectNamedReexportDeprecations(findings, context);
+  collectNamedRequireDeprecations(findings, context);
+  collectNamespaceUsageDeprecations(findings, context);
+  collectNamespaceRequireDeprecations(findings, context);
+  collectRuntimeUsageDeprecations(findings, context);
+}
+
+function collectNamedImportDeprecations(findings, context) {
+  const regex =
+    /\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)) {
+      continue;
+    }
+    for (const binding of parseNamedBindings(match[1])) {
+      if (binding.exported !== "loadSessionStore") {
+        continue;
+      }
+      findings.push(
+        buildFinding(context.rule, {
+          surface: `${specifier} import`,
+          sourceText: context.text,
+          filePath: context.filePath,
+          offset: (match.index ?? 0) + match[0].lastIndexOf(binding.local),
+        }),
+      );
+    }
+  }
+}
+
+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)) {
+      continue;
+    }
+    for (const binding of parseNamedBindings(match[1])) {
+      if (binding.exported !== "loadSessionStore") {
+        continue;
+      }
+      findings.push(
+        buildFinding(context.rule, {
+          surface: `${specifier} re-export`,
+          sourceText: context.text,
+          filePath: context.filePath,
+          offset: (match.index ?? 0) + match[0].lastIndexOf(binding.local),
+        }),
+      );
+    }
+  }
+}
+
+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)) {
+      continue;
+    }
+    for (const binding of parseNamedBindings(match[1], { aliasSeparator: ":" })) {
+      if (binding.exported !== "loadSessionStore") {
+        continue;
+      }
+      findings.push(
+        buildFinding(context.rule, {
+          surface: `${specifier} require`,
+          sourceText: context.text,
+          filePath: context.filePath,
+          offset: (match.index ?? 0) + match[0].lastIndexOf(binding.local),
+        }),
+      );
+    }
+  }
+}
+
+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,
+      }),
+    );
+  });
+}
+
+function forEachMethodCall(text, methodName, visit) {
+  let start = 0;
+  while (start < text.length) {
+    const offset = text.indexOf(methodName, start);
+    if (offset === -1) {
+      return;
+    }
+    start = offset + methodName.length;
+    if (!isIdentifierBoundary(text, offset - 1) || !isIdentifierBoundary(text, offset + methodName.length)) {
+      continue;
+    }
+    if (!hasCallSuffix(text, offset + methodName.length)) {
+      continue;
+    }
+    visit(offset);
+  }
+}
+
+function readNormalizedCallReceiver(text, methodOffset) {
+  let cursor = skipWhitespaceBackward(text, methodOffset);
+  const operator = readMemberAccessOperator(text, cursor);
+  if (!operator) {
+    return null;
+  }
+  cursor = operator.start;
+  const receiverStart = findReceiverStart(text, cursor);
+  if (receiverStart === cursor) {
+    return null;
+  }
+  return normalizeReceiverExpression(text.slice(receiverStart, cursor));
+}
+
+function readMemberAccessOperator(text, endOffset) {
+  if (endOffset >= 2 && text.slice(endOffset - 2, endOffset) === "?.") {
+    return { kind: "optional", start: endOffset - 2 };
+  }
+  if (endOffset >= 1 && text[endOffset - 1] === ".") {
+    return { kind: "direct", start: endOffset - 1 };
+  }
+  return null;
+}
+
+function findReceiverStart(text, endOffset) {
+  let cursor = endOffset;
+  let parenDepth = 0;
+  while (cursor > 0) {
+    const char = text[cursor - 1];
+    if (char === ")") {
+      parenDepth += 1;
+      cursor -= 1;
+      continue;
+    }
+    if (char === "(") {
+      if (parenDepth === 0) {
+        break;
+      }
+      parenDepth -= 1;
+      cursor -= 1;
+      continue;
+    }
+    if (parenDepth > 0) {
+      cursor -= 1;
+      continue;
+    }
+    if (isReceiverCharacter(char)) {
+      cursor -= 1;
+      continue;
+    }
+    break;
+  }
+  return cursor;
+}
+
+function normalizeReceiverExpression(rawReceiver) {
+  let normalized = rawReceiver.replace(/\s+/g, "");
+  while (normalized.startsWith("(") && normalized.endsWith(")") && wrapsWholeExpression(normalized)) {
+    normalized = normalized.slice(1, -1);
+  }
+  return normalized.replaceAll("?.", ".");
+}
+
+function wrapsWholeExpression(value) {
+  let depth = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    const char = value[index];
+    if (char === "(") {
+      depth += 1;
+    } else if (char === ")") {
+      depth -= 1;
+      if (depth === 0 && index < value.length - 1) {
+        return false;
+      }
+    }
+  }
+  return depth === 0;
+}
+
+function hasCallSuffix(text, startOffset) {
+  let cursor = skipWhitespaceForward(text, startOffset);
+  if (text.slice(cursor, cursor + 2) === "?.") {
+    cursor = skipWhitespaceForward(text, cursor + 2);
+  }
+  return text[cursor] === "(";
+}
+
+function skipWhitespaceForward(text, startOffset) {
+  let cursor = startOffset;
+  while (cursor < text.length && /\s/.test(text[cursor])) {
+    cursor += 1;
+  }
+  return cursor;
+}
+
+function skipWhitespaceBackward(text, endOffset) {
+  let cursor = endOffset;
+  while (cursor > 0 && /\s/.test(text[cursor - 1])) {
+    cursor -= 1;
+  }
+  return cursor;
+}
+
+function isReceiverCharacter(char) {
+  return /[A-Za-z0-9_$?.]/.test(char);
+}
+
+function isIdentifierBoundary(text, offset) {
+  if (offset < 0 || offset >= text.length) {
+    return true;
+  }
+  return !/[A-Za-z0-9_$]/.test(text[offset]);
+}
+
+function isRuntimeSessionReceiver(receiver) {
+  return /^(?:[A-Za-z_$][A-Za-z0-9_$]*|this)\.runtime\.agent\.session$/.test(receiver);
+}
+
+function collectNamespaceUsageDeprecations(findings, context) {
+  const regex = /\bimport\s+(?:type\s+)?\*\s+as\s+([A-Za-z_$][\w$]*)\s*from\s*["'`]([^"'`]+)["'`]/g;
+  for (const match of context.text.matchAll(regex)) {
+    const local = match[1];
+    const specifier = match[2];
+    if (!loadSessionStoreSpecifiers.has(specifier)) {
+      continue;
+    }
+    collectMemberCallDeprecations(findings, context, {
+      receiverMatcher: (receiver) => receiver === local,
+      surface: `${specifier} namespace access`,
+    });
+  }
+}
+
+function collectNamespaceRequireDeprecations(findings, context) {
+  const regex = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*require\(\s*["'`]([^"'`]+)["'`]\s*\)/g;
+  for (const match of context.text.matchAll(regex)) {
+    const local = match[1];
+    const specifier = match[2];
+    if (!loadSessionStoreSpecifiers.has(specifier)) {
+      continue;
+    }
+    collectMemberCallDeprecations(findings, context, {
+      receiverMatcher: (receiver) => receiver === local,
+      surface: `${specifier} require namespace access`,
+    });
+  }
+}
+
+function collectRuntimeUsageDeprecations(findings, context) {
+  collectMemberCallDeprecations(findings, context, {
+    receiverMatcher: isRuntimeSessionReceiver,
+    surface: "api.runtime.agent.session",
+  });
+}
+
+function parseNamedBindings(rawBindings, options = {}) {
+  const aliasSeparator = options.aliasSeparator ?? "as";
+  return rawBindings
+    .split(",")
+    .map((binding) => binding.trim())
+    .filter(Boolean)
+    .map((binding) => binding.replace(/^type\s+/, "").trim())
+    .map((binding) => parseBindingAlias(binding, aliasSeparator))
+    .filter((binding) => binding.exported && binding.local);
+}
+
+function parseBindingAlias(binding, aliasSeparator) {
+  if (aliasSeparator === ":") {
+    const separatorIndex = binding.indexOf(":");
+    if (separatorIndex === -1) {
+      return {
+        exported: binding.trim(),
+        local: binding.trim(),
+      };
+    }
+    return {
+      exported: binding.slice(0, separatorIndex).trim(),
+      local: binding.slice(separatorIndex + 1).trim(),
+    };
+  }
+
+  const tokens = binding.trim().split(/\s+/);
+  if (tokens.length === 3 && tokens[1] === "as") {
+    return {
+      exported: tokens[0],
+      local: tokens[2],
+    };
+  }
+
+  return {
+    exported: binding.trim(),
+    local: binding.trim(),
+  };
+}
+
+function buildFinding(rule, details) {
+  const refLine = lineForOffset(details.sourceText, details.offset);
+  return {
+    code: rule.code,
+    surface: details.surface,
+    replacement: rule.replacement,
+    ref: `${details.filePath}:${refLine}`,
+    message: `loadSessionStore keeps the legacy whole-store session shape; use ${rule.replacement}.`,
+    offset: details.offset,
+  };
+}
+
+function uniqueFindings(findings) {
+  const byKey = new Map();
+  for (const finding of findings) {
+    byKey.set(`${finding.code}:${finding.surface}:${finding.ref}`, finding);
+  }
+  return [...byKey.values()];
+}
+
+function lineForOffset(text, offset) {
+  let line = 1;
+  for (let index = 0; index < offset; index += 1) {
+    if (text.charCodeAt(index) === 10) {
+      line += 1;
+    }
+  }
+  return line;
+}