@openclaw/plugin-inspector 0.3.15 → 0.3.17

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## 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
+
+- Write `package.json` updates atomically for `init --scripts` and `prune-workspace-dev-deps`, including symlink-preserving target rewrites and temp-file cleanup on staging failures. Thanks @KrasimirKralev.
+- Mock the Lark SDK HTTP interceptor surface during runtime capture so Feishu plugin bundles load successfully.
+
 ## 0.3.15 - 2026-06-12
 
 ### Fixed

package/package.json

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

package/src/capture-api.js

@@ -151,7 +151,7 @@ export function createCaptureContext(options = {}) {
     resolvePath: options.resolvePath ?? ((value) => value),
     runtime: options.runtime ?? createRuntimeContext(options),
     secrets: options.secrets ?? createSecretContext(options),
-    store: options.store ?? createStoreContext(options),
+    store: options.store ?? createStoreContext(),
     paths: options.paths ?? {
       cacheDir: ".plugin-inspector/cache",
       configDir: ".plugin-inspector/config",

package/src/cli.js

@@ -38,7 +38,7 @@ try {
     await runConfig(commandArgs);
   } else if (command === "inspect" || command === "report") {
     if (command === "inspect" && !commandArgs.includes("--config")) {
-      await runCheck(commandArgs);
+      await runCheck(commandArgs, { check: commandArgs.includes("--check") });
     } else {
       await runReport(command, commandArgs);
     }
@@ -100,7 +100,7 @@ async function runConfig(commandArgs) {
   }
 }
 
-async function runCheck(commandArgs) {
+async function runCheck(commandArgs, options = {}) {
   const configPath = readFlag(commandArgs, "--config");
   const pluginRoot = readFlag(commandArgs, "--plugin-root") ?? readFlag(commandArgs, "--root");
   const outDir = readFlag(commandArgs, "--out") ?? "reports";
@@ -133,7 +133,7 @@ async function runCheck(commandArgs) {
     console.log(renderTextSummary(report, { artifacts: paths }));
   }
 
-  if (report.status !== "pass") {
+  if ((options.check ?? true) && report.status !== "pass") {
     throw new Error(`plugin-inspector found ${report.summary.breakageCount} breakages`);
   }
 }
@@ -288,7 +288,7 @@ async function runCapture(commandArgs) {
   const entrypoint = findCaptureEntrypoint(commandArgs);
   const outputPath = readFlag(commandArgs, "--output");
   const pluginRoot = readFlag(commandArgs, "--plugin-root");
-  const mockSdk = readMockSdkFlag(commandArgs) ?? commandArgs.includes("--mock-sdk");
+  const mockSdk = readMockSdkFlag(commandArgs) ?? true;
   const allowExecution = readAllowExecutionFlag(commandArgs);
   if (!entrypoint) {
     throw new Error("capture requires an entrypoint path");

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/init.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { inferPluginSeams, packageId } from "./config.js";
+import { writeJsonFileAtomic } from "./json-file.js";
 
 export const defaultInitConfigPath = "plugin-inspector.config.json";
 export const defaultInitWorkflowPath = ".github/workflows/plugin-inspector.yml";
@@ -59,7 +60,7 @@ export async function writePluginInspectorInit(options = {}) {
       ...defaultInitPackageScripts,
     };
     if (!dryRun) {
-      await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
+      await writeJsonFileAtomic(packageJsonPath, packageJson);
     }
     written.push(packageJsonPath);
   }

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,13 +42,17 @@ 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",
 ]);
 
 const authorRemediationDocsUrl = (code) => `https://docs.openclaw.ai/clawhub/plugin-validation-fixes#${code}`;
 
-const authorRemediation = (summary) => ({ summary });
+const authorRemediation = (summary, ..._details) => ({ summary });
 
 const migrationRemediation = authorRemediation;
 
@@ -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",
@@ -462,10 +518,7 @@ export function buildIssues({ breakages = [], warnings = [], suggestions = [], t
       runtimeCoverage: finding.runtimeCoverage ?? null,
       ...(finding.authorRemediation
         ? {
-            authorRemediation: {
-              summary: finding.authorRemediation.summary,
-              docsUrl: authorRemediationDocsUrl(finding.code),
-            },
+            authorRemediation: withAuthorRemediationDocs(finding.code, finding.authorRemediation),
           }
         : {}),
     }));
@@ -491,10 +544,7 @@ export function issueMetadata(finding, targetOpenClaw) {
   };
   const authorMetadata = metadata.authorRemediation
     ? {
-        authorRemediation: {
-          summary: metadata.authorRemediation.summary,
-          docsUrl: authorRemediationDocsUrl(finding.code),
-        },
+        authorRemediation: withAuthorRemediationDocs(finding.code, metadata.authorRemediation),
       }
     : {};
   return {
@@ -505,6 +555,13 @@ export function issueMetadata(finding, targetOpenClaw) {
   };
 }
 
+function withAuthorRemediationDocs(code, remediation) {
+  return {
+    ...remediation,
+    docsUrl: authorRemediationDocsUrl(code),
+  };
+}
+
 export function classifyIssueFinding(finding, targetOpenClaw, metadata = {}) {
   const compatStatus = compatStatusFor(finding, targetOpenClaw);
   const deprecated = compatStatus === "deprecated";
@@ -567,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/json-file.js

@@ -1,5 +1,7 @@
+import { randomUUID } from "node:crypto";
 import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
+import { lstat, open, readFile, readlink, realpath, rename, stat, unlink } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
 
 export async function readJsonFile(jsonPath) {
   return JSON.parse(await readFile(jsonPath, "utf8"));
@@ -8,3 +10,98 @@ export async function readJsonFile(jsonPath) {
 export async function readOptionalJsonFile(jsonPath) {
   return existsSync(jsonPath) ? readJsonFile(jsonPath) : null;
 }
+
+// Writes JSON.stringify(value, null, 2) + newline atomically: stage to a sibling
+// temp file, fsync, then rename over the destination. A crash mid-write can only
+// truncate the temp file, so an interrupted run never corrupts an existing
+// manifest. The destination file mode is preserved exactly (including any
+// special bits) so the atomic replace stays permission-neutral. Existing
+// symlinked manifests resolve to their target before staging so the link itself
+// is never replaced.
+export async function writeJsonFileAtomic(jsonPath, value) {
+  const writePath = await resolveJsonWritePath(jsonPath);
+  const data = `${JSON.stringify(value, null, 2)}\n`;
+  const tempPath = join(dirname(writePath), `.${basename(writePath)}.${process.pid}.${randomUUID()}.tmp`);
+
+  let existingMode;
+  try {
+    existingMode = (await stat(writePath)).mode & 0o7777;
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  const handle = await open(tempPath, "wx");
+  let stagingError = null;
+  try {
+    await handle.writeFile(data, "utf8");
+    await handle.sync();
+    if (existingMode !== undefined) {
+      await handle.chmod(existingMode);
+    }
+  } catch (error) {
+    stagingError = error;
+  } finally {
+    try {
+      await handle.close();
+    } catch (error) {
+      stagingError ??= error;
+    }
+  }
+
+  if (stagingError) {
+    await unlink(tempPath).catch(() => {});
+    throw stagingError;
+  }
+
+  try {
+    await rename(tempPath, writePath);
+  } catch (error) {
+    await unlink(tempPath).catch(() => {});
+    throw error;
+  }
+}
+
+async function resolveJsonWritePath(jsonPath) {
+  try {
+    return await realpath(jsonPath);
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  let writePath = jsonPath;
+  const seen = new Set();
+  for (let hops = 0; hops < 40; hops += 1) {
+    const normalizedPath = resolve(writePath);
+    if (seen.has(normalizedPath)) {
+      const error = new Error(`too many symbolic links resolving ${jsonPath}`);
+      error.code = "ELOOP";
+      throw error;
+    }
+    seen.add(normalizedPath);
+
+    let entry;
+    try {
+      entry = await lstat(writePath);
+    } catch (error) {
+      if (error.code === "ENOENT") {
+        return writePath;
+      }
+      throw error;
+    }
+
+    if (!entry.isSymbolicLink()) {
+      return writePath;
+    }
+
+    const target = await readlink(writePath);
+    writePath = resolve(dirname(writePath), target);
+  }
+
+  const error = new Error(`too many symbolic links resolving ${jsonPath}`);
+  error.code = "ELOOP";
+  throw error;
+}

package/src/profile-diff.js

@@ -194,12 +194,16 @@ function registrySurfaceChecks(baseline, current) {
     action: "pass",
     metric,
     message: "registry surface delta is tracked as context",
-    baseline: baseline.targetOpenClaw[metric],
-    current: current.targetOpenClaw[metric],
-    delta: current.targetOpenClaw[metric] - baseline.targetOpenClaw[metric],
+    baseline: registrySurfaceCount(baseline.targetOpenClaw[metric]),
+    current: registrySurfaceCount(current.targetOpenClaw[metric]),
+    delta: registrySurfaceCount(current.targetOpenClaw[metric]) - registrySurfaceCount(baseline.targetOpenClaw[metric]),
   }));
 }
 
+function registrySurfaceCount(value) {
+  return Array.isArray(value) ? value.length : Number(value ?? 0);
+}
+
 function commandWall(profile, commandId) {
   return profile.commands.find((command) => command.id === commandId)?.wallMs?.median ?? 0;
 }

package/src/prune-workspace-dev-deps-cli.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { readFile, writeFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
+import { writeJsonFileAtomic } from "./json-file.js";
 import path from "node:path";
 
 const packageJsonPath = path.resolve(process.cwd(), "package.json");
@@ -19,5 +20,5 @@ if (packageJson.devDependencies && Object.keys(packageJson.devDependencies).leng
 }
 
 if (changed) {
-  await writeFile(packageJsonPath, `${JSON.stringify(packageJson, null, 2)}\n`, "utf8");
+  await writeJsonFileAtomic(packageJsonPath, packageJson);
 }

package/src/report.js

@@ -450,6 +450,7 @@ function emptyFixtureReport(fixture) {
     registrations: [],
     manifestContracts: [],
     sdkImports: [],
+    sdkDeprecations: [],
     sourceFiles: [],
     manifestFiles: [],
     packageFiles: [],

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()];
 }

package/src/sdk-mock.js

@@ -273,7 +273,10 @@ export async function createMockSdkPackage(rootDir, options = {}) {
     if (specifier === "openclaw/plugin-sdk") {
       continue;
     }
-    const relative = specifier.slice("openclaw/plugin-sdk/".length);
+    const relative = safePluginSdkSubpath(specifier.slice("openclaw/plugin-sdk/".length));
+    if (!relative) {
+      continue;
+    }
     if (mockSdkSubpathExports[relative]) {
       continue;
     }
@@ -443,7 +446,12 @@ export async function resolve(specifier, context, nextResolve) {
     return moduleUrl(path.join(pluginSdkDir, "index.js"));
   }
   if (specifier.startsWith("openclaw/plugin-sdk/")) {
-    const subpath = specifier.slice("openclaw/plugin-sdk/".length);
+    const subpath = safePluginSdkSubpath(specifier.slice("openclaw/plugin-sdk/".length));
+    if (!subpath) {
+      throw Object.assign(new Error(\`invalid OpenClaw plugin SDK subpath: \${specifier}\`), {
+        code: "ERR_INVALID_MODULE_SPECIFIER",
+      });
+    }
     return moduleUrl(path.join(pluginSdkDir, \`\${subpath}.js\`));
   }
   if (externalMap.has(specifier)) {
@@ -514,9 +522,25 @@ function isMockableBareSpecifier(specifier) {
     !specifier.startsWith("data:") &&
     !specifier.startsWith("file:");
 }
+
+function safePluginSdkSubpath(value) {
+  const normalized = path.posix.normalize(String(value).replaceAll("\\\\", "/"));
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/")) {
+    return null;
+  }
+  return normalized;
+}
 `;
 }
 
+function safePluginSdkSubpath(value) {
+  const normalized = path.posix.normalize(String(value).replaceAll("\\", "/"));
+  if (!normalized || normalized === "." || normalized === ".." || normalized.startsWith("../") || normalized.startsWith("/")) {
+    return null;
+  }
+  return normalized;
+}
+
 function dynamicMockModuleSource(exportNames, options = {}) {
   const names = new Set([...exportNames].filter(isValidExportName));
   if (options.zod) {
@@ -530,6 +554,9 @@ export default ${options.zod ? "createZNamespace()" : 'createMockValue("default"
 }
 
 function externalMockModuleSource(specifier, exportNames) {
+  if (specifier === "@larksuiteoapi/node-sdk") {
+    return larkSdkMockModuleSource(exportNames);
+  }
   const names = new Set([...exportNames].filter(isValidExportName));
   if (specifier === "zod") {
     addZodExports(names);
@@ -537,6 +564,52 @@ function externalMockModuleSource(specifier, exportNames) {
   return dynamicMockModuleSource(names, { zod: specifier === "zod" });
 }
 
+function larkSdkMockModuleSource(exportNames) {
+  const larkExports = new Set([
+    "AppType",
+    "Client",
+    "Domain",
+    "EventDispatcher",
+    "LoggerLevel",
+    "WSClient",
+    ...exportNames,
+  ]);
+  larkExports.delete("defaultHttpInstance");
+  return `${genericMockRuntimeSource()}
+const requestInterceptors = {
+  handlers: [],
+  use(handler) {
+    this.handlers.push(handler);
+    return this.handlers.length - 1;
+  },
+};
+
+export const defaultHttpInstance = {
+  interceptors: {
+    request: requestInterceptors,
+    response: {
+      handlers: [],
+      use(handler) {
+        this.handlers.push(handler);
+        return this.handlers.length - 1;
+      },
+    },
+  },
+  request: createMockValue("defaultHttpInstance.request"),
+  get: createMockValue("defaultHttpInstance.get"),
+  post: createMockValue("defaultHttpInstance.post"),
+  put: createMockValue("defaultHttpInstance.put"),
+  patch: createMockValue("defaultHttpInstance.patch"),
+  delete: createMockValue("defaultHttpInstance.delete"),
+  head: createMockValue("defaultHttpInstance.head"),
+  options: createMockValue("defaultHttpInstance.options"),
+};
+${[...larkExports].filter(isValidExportName).map(genericExportStatement).join("\n")}
+
+export default createMockValue("default");
+`;
+}
+
 function addZodExports(names) {
   for (const name of ["z", "any", "array", "boolean", "enum", "literal", "number", "object", "record", "string", "unknown"]) {
     names.add(name);

package/src/workspace-plan.js

@@ -1,5 +1,5 @@
 import { existsSync } from "node:fs";
-import { mkdir, readFile } from "node:fs/promises";
+import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { renderPaddedMarkdownTable, writeJsonMarkdownArtifacts } from "./artifacts.js";
@@ -229,13 +229,13 @@ async function buildEntrypointPlan({ fixtureId, entrypoint, packageSummary, pack
 
   steps.push({
     kind: "prepare",
-    command: `mkdir -p ${workspacePath} && rsync -a --delete ${packageDir}/ ${workspacePath}/`,
+    command: `mkdir -p ${shellQuote(workspacePath)} && rsync -a --delete ${shellQuote(`${packageDir}/`)} ${shellQuote(`${workspacePath}/`)}`,
     cwd: repoRelative("."),
     reason: "copy fixture package into an isolated mutable workspace",
   });
   steps.push({
     kind: "prepare-artifacts",
-    command: `mkdir -p ${resultPath}`,
+    command: `mkdir -p ${shellQuote(resultPath)}`,
     cwd: repoRelative("."),
     reason: "create a stable result directory for capture and synthetic probe artifacts",
   });
@@ -243,7 +243,7 @@ async function buildEntrypointPlan({ fixtureId, entrypoint, packageSummary, pack
   if (requiredCapabilities.includes("target-openclaw-link")) {
     steps.push({
       kind: "link-openclaw",
-      command: `${packageManager} pkg set dependencies.openclaw="file:${targetOpenClawWorkspacePath(settings, fixtureId, targetOpenClawPath)}"`,
+      command: `${shellQuote(packageManager)} pkg set ${shellQuote(`dependencies.openclaw=file:${targetOpenClawWorkspacePath(settings, fixtureId, targetOpenClawPath)}`)}`,
       cwd: workspacePath,
       reason: "link the plugin's openclaw peer dependency to the target checkout under test",
     });
@@ -253,7 +253,7 @@ async function buildEntrypointPlan({ fixtureId, entrypoint, packageSummary, pack
     if (hasWorkspaceProtocolDevDependencies(packageJson)) {
       steps.push({
         kind: "prune-dev-workspace-deps",
-        command: `node ${helperScript(settings, workspacePath, settings.pruneWorkspaceDevDepsScript, "prune-workspace-dev-deps-cli.js")}`,
+        command: `node ${shellQuote(helperScript(settings, workspacePath, settings.pruneWorkspaceDevDepsScript, "prune-workspace-dev-deps-cli.js"))}`,
         cwd: workspacePath,
         reason: "remove workspace: devDependencies from the isolated runtime install; the mock SDK supplies OpenClaw host imports",
       });
@@ -361,6 +361,7 @@ function requiredCapabilitiesFor(entrypoint, packageSummary = {}) {
     }
     if (blocker.code === "build-required") {
       capabilities.add("build");
+      capabilities.add("dependency-install");
     }
     if (blocker.code === "ts-loader-required") {
       capabilities.add("ts-loader");
@@ -453,35 +454,35 @@ function installCommand(packageManager) {
 function auditCommand(settings, packageManager, fixtureId, workspacePath) {
   const output = workspaceRelativeArtifactPath(settings, fixtureId, workspacePath, "package-audit.json");
   if (packageManager === "npm") {
-    return `npm audit --json > ${output} || true`;
+    return `npm audit --json > ${shellQuote(output)} || true`;
   }
   if (packageManager === "pnpm") {
-    return `pnpm audit --json > ${output} || true`;
+    return `pnpm audit --json > ${shellQuote(output)} || true`;
   }
   if (packageManager === "yarn") {
-    return `yarn npm audit --json > ${output} || true`;
+    return `yarn npm audit --json > ${shellQuote(output)} || true`;
   }
   if (packageManager === "bun") {
-    return `bun audit --json > ${output} || true`;
+    return `bun audit --json > ${shellQuote(output)} || true`;
   }
-  return `${packageManager} audit --json > ${output} || true`;
+  return `${shellQuote(packageManager)} audit --json > ${shellQuote(output)} || true`;
 }
 
 function runCommand(packageManager, script) {
   if (packageManager === "npm") {
-    return `npm run ${script}`;
+    return `npm run ${shellQuote(script)}`;
   }
-  return `${packageManager} run ${script}`;
+  return `${shellQuote(packageManager)} run ${shellQuote(script)}`;
 }
 
 function captureCommand(settings, fixtureId, entrypoint, workspacePath) {
   const script = helperScript(settings, workspacePath, settings.captureScript, "capture-cli.js");
-  return `${settings.optInEnv} node ${script} ${entrypoint.specifier} --mock-sdk --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "capture")}`;
+  return `${settings.optInEnv} node ${shellQuote(script)} ${shellQuote(entrypoint.specifier)} --mock-sdk --output ${shellQuote(workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "capture"))}`;
 }
 
 function syntheticProbeCommand(settings, fixtureId, entrypoint, workspacePath) {
   const script = helperScript(settings, workspacePath, settings.syntheticProbeScript, "synthetic-probes-cli.js");
-  return `${settings.optInEnv} node ${script} --entrypoint ${entrypoint.specifier} --mock-sdk --output ${workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "synthetic")}`;
+  return `${settings.optInEnv} node ${shellQuote(script)} --entrypoint ${shellQuote(entrypoint.specifier)} --mock-sdk --output ${shellQuote(workspaceArtifactPath(settings, fixtureId, entrypoint, workspacePath, "synthetic"))}`;
 }
 
 function helperScript(settings, workspacePath, configuredScript, helperFileName) {
@@ -526,6 +527,14 @@ function auditArtifactPath(settings, fixtureId) {
   return posixJoin(settings.resultsRoot, fixtureId, "package-audit.json");
 }
 
+function shellQuote(value) {
+  const text = String(value);
+  if (/^[A-Za-z0-9_./:=@%+-]+$/u.test(text)) {
+    return text;
+  }
+  return `'${text.replaceAll("'", "'\\''")}'`;
+}
+
 function markdownTable(rows, headers) {
   return renderPaddedMarkdownTable(rows, headers);
 }