refactor: consolidate duplicate helper exports (#106016)

* refactor(normalization): consolidate string helpers

* refactor(normalization): consolidate agent ids

* refactor(paths): consolidate user path resolution

* refactor(gateway): preserve transcript helper facade

* fix(normalization): align helper build aliases

* fix(memory): keep helper import line neutral

* chore(plugin-sdk): align consolidated helper surface

* refactor(normalization): reuse lowercase string helper

* refactor(normalization): reuse record guard

* refactor(normalization): share surrogate boundary helper

* refactor(agents): share token estimate constant

* refactor(memory): distinguish standalone helper contracts

* refactor(normalization): share error cause formatter

* refactor(config): distinguish eligibility predicates

* refactor(plugins): share registry state symbol

* refactor(cli): reuse outbound dependency adapter

* refactor(cron): distinguish positive duration parser

* fix(gateway): keep transcript helper private

* fix(paths): preserve public helper status

* refactor(channels): reuse registry normalizer

* refactor(agents): reuse agent core runtime facade

* refactor(auth): reuse locked profile upsert

* refactor(records): distinguish trap-safe guard

* refactor(migrations): distinguish sync directory helper

* test(plugins): drop stale duration alias expectations

* fix(channels): remove stale registry import

* chore(plugin-sdk): refresh helper API baseline

* fix(memory): keep renamed helpers private

* fix(plugins): keep registry state key private

* fix(plugin-sdk): tighten wildcard surface budget

* chore(plugin-sdk): refresh rebased helper API baseline

src/plugins/plugin-sdk-native-resolver.test.ts

@@ -382,6 +382,7 @@ describe("installOpenClawPluginSdkNativeResolver", () => {
       "boolean-coercion.ts",
     );
     const resultSource = writeInternalCorePackageSource(root, "normalization-core", "result.ts");
+    const agentIdSource = writeInternalCorePackageSource(root, "normalization-core", "agent-id.ts");
     const mediaCoreSource = writeInternalCorePackageSource(root, "media-core", "mime.ts");
     const markdownCoreSource = writeInternalCorePackageSource(
       root,
@@ -418,6 +419,7 @@ describe("installOpenClawPluginSdkNativeResolver", () => {
     expect(installedAliases).toContain("@openclaw/normalization-core/string-coerce");
     expect(installedAliases).toContain("@openclaw/normalization-core/boolean-coercion");
     expect(installedAliases).toContain("@openclaw/normalization-core/result");
+    expect(installedAliases).toContain("@openclaw/normalization-core/agent-id");
     expect(installedAliases).toContain("@openclaw/media-core/mime");
     expect(installedAliases).toContain("@openclaw/markdown-core/code-spans");
     expect(installedAliases).toContain("@openclaw/ai/internal/retry-after");
@@ -437,6 +439,9 @@ describe("installOpenClawPluginSdkNativeResolver", () => {
     expect(
       fs.realpathSync(requireFromCoreSource.resolve("@openclaw/normalization-core/result")),
     ).toBe(fs.realpathSync(resultSource));
+    expect(
+      fs.realpathSync(requireFromCoreSource.resolve("@openclaw/normalization-core/agent-id")),
+    ).toBe(fs.realpathSync(agentIdSource));
     expect(fs.realpathSync(requireFromCoreSource.resolve("@openclaw/media-core/mime"))).toBe(
       fs.realpathSync(mediaCoreSource),
     );

src/plugins/plugin-sdk-native-resolver.ts

@@ -67,21 +67,6 @@ const INTERNAL_CORE_PACKAGE_ALIASES = [
       ["types", "types.ts"],
     ],
   },
-  {
-    packageName: "@openclaw/normalization-core",
-    packageDir: "normalization-core",
-    subpaths: [
-      ["", "index.ts"],
-      ["boolean-coercion", "boolean-coercion.ts"],
-      ["error-coercion", "error-coercion.ts"],
-      ["number-coercion", "number-coercion.ts"],
-      ["record-coerce", "record-coerce.ts"],
-      ["result", "result.ts"],
-      ["string-coerce", "string-coerce.ts"],
-      ["string-normalization", "string-normalization.ts"],
-      ["utf16-slice", "utf16-slice.ts"],
-    ],
-  },
   {
     // Mirrors packages/ai/package.json exports; dist file names do not follow
     // the src layout (dist/diagnostics.mjs <- src/utils/diagnostics.ts), so the
@@ -331,15 +316,15 @@ function listInternalCorePackageNativeAliases(
   }> = [];
   const internalCorePackageAliases = [
     ...INTERNAL_CORE_PACKAGE_ALIASES,
-    {
-      packageName: "@openclaw/acp-core",
-      packageDir: "acp-core",
+    ...["normalization-core", "acp-core"].map((packageDir) => ({
+      packageName: `@openclaw/${packageDir}`,
+      packageDir,
       subpaths: listWorkspacePackageExportAliasEntries({
         packageRoot,
-        packageName: "@openclaw/acp-core",
-        packageDir: "acp-core",
+        packageName: `@openclaw/${packageDir}`,
+        packageDir,
       }).map((entry) => [entry.subpath, entry.srcFile] as const),
-    },
+    })),
   ];
   for (const entry of internalCorePackageAliases) {
     for (const [subpath, srcFile] of entry.subpaths) {

src/plugins/provider-catalog-result.ts

@@ -3,7 +3,7 @@ import type { ModelDefinitionConfig, ModelProviderConfig } from "../config/types
 import {
   copyArrayEntries,
   copyRecordEntries,
-  isRecord,
+  isRecordWithoutThrowing,
   readRecordValue,
 } from "../shared/safe-record.js";
 import type { ProviderCatalogResult } from "./types.js";
@@ -92,7 +92,7 @@ export function copyProviderCatalogModels(
 }
 
 function copyProviderCatalogModel(model: unknown): ModelDefinitionConfig | undefined {
-  if (!isRecord(model)) {
+  if (!isRecordWithoutThrowing(model)) {
     return undefined;
   }
   const id = readRecordValue(model, "id");
@@ -118,7 +118,7 @@ function copyProviderCatalogModel(model: unknown): ModelDefinitionConfig | undef
 function copyProviderCatalogProviderConfig(
   providerConfig: unknown,
 ): ModelProviderConfig | undefined {
-  if (!isRecord(providerConfig)) {
+  if (!isRecordWithoutThrowing(providerConfig)) {
     return undefined;
   }
 

src/plugins/provider-thinking.ts

@@ -7,6 +7,7 @@ import type {
   ProviderThinkingProfile,
   ProviderThinkingPolicyContext,
 } from "./provider-thinking.types.js";
+import { PLUGIN_REGISTRY_STATE } from "./runtime-state-key.js";
 
 type ThinkingProviderPlugin = {
   id: string;
@@ -22,8 +23,6 @@ type ThinkingProviderPlugin = {
   ) => "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "adaptive" | null | undefined;
 };
 
-const PLUGIN_REGISTRY_STATE = Symbol.for("openclaw.pluginRegistryState");
-
 type ThinkingRegistryState = {
   activeRegistry?: {
     providers?: Array<{

src/plugins/runtime-channel-state.ts

@@ -1,8 +1,6 @@
 // Stores active plugin channel registry state for the current runtime.
 import type { ActivePluginChannelRegistry } from "./channel-registry-state.types.js";
-
-/** Global symbol that stores process-current plugin registry state. */
-const PLUGIN_REGISTRY_STATE = Symbol.for("openclaw.pluginRegistryState");
+import { PLUGIN_REGISTRY_STATE } from "./runtime-state-key.js";
 
 type GlobalChannelRegistryState = typeof globalThis & {
   [PLUGIN_REGISTRY_STATE]?: {

src/plugins/runtime-state-key.ts

@@ -0,0 +1,2 @@
+/** Process-global symbol shared by every plugin registry runtime projection. */
+export const PLUGIN_REGISTRY_STATE = Symbol.for("openclaw.pluginRegistryState");

src/plugins/runtime-state.ts

@@ -1,7 +1,8 @@
+import { PLUGIN_REGISTRY_STATE } from "./runtime-state-key.js";
 // Stores plugin runtime registry state for the current process lifecycle.
 import { getActivePluginRegistryWorkspaceDirFromState as getPinnedWorkspaceDirFromState } from "./runtime-workspace-state.js";
 
-export const PLUGIN_REGISTRY_STATE = Symbol.for("openclaw.pluginRegistryState");
+export { PLUGIN_REGISTRY_STATE };
 
 type PluginRegistry = import("./registry-types.js").PluginRegistry;
 

src/plugins/runtime-workspace-state.ts

@@ -1,8 +1,8 @@
 // Shares plugin runtime workspace state across module reloads.
 import { AsyncLocalStorage } from "node:async_hooks";
 import { resolveGlobalSingleton } from "../shared/global-singleton.js";
+import { PLUGIN_REGISTRY_STATE } from "./runtime-state-key.js";
 
-const PLUGIN_REGISTRY_STATE = Symbol.for("openclaw.pluginRegistryState");
 const PINNED_PLUGIN_REGISTRY_WORKSPACE_KEY = Symbol.for(
   "openclaw.pinnedPluginRegistryWorkspaceDir",
 );

src/plugins/sdk-alias.test.ts

@@ -1565,6 +1565,12 @@ describe("plugin sdk alias helpers", () => {
       srcFile: "result.ts",
       distFile: "result.mjs",
     });
+    const normalizationAgentId = writeWorkspacePackageEntry({
+      root: fixture.root,
+      packageDir: "normalization-core",
+      srcFile: "agent-id.ts",
+      distFile: "agent-id.mjs",
+    });
     const normalizationStringCoerce = writeWorkspacePackageEntry({
       root: fixture.root,
       packageDir: "normalization-core",
@@ -1641,6 +1647,7 @@ describe("plugin sdk alias helpers", () => {
     fs.rmSync(normalizationCore.distFile);
     fs.rmSync(normalizationBooleanCoercion.distFile);
     fs.rmSync(normalizationResult.distFile);
+    fs.rmSync(normalizationAgentId.distFile);
     fs.rmSync(normalizationStringCoerce.distFile);
     fs.rmSync(retry.distFile);
     fs.rmSync(terminalCore.distFile);
@@ -1706,6 +1713,9 @@ describe("plugin sdk alias helpers", () => {
     expect(fs.realpathSync(aliases["@openclaw/normalization-core/result"] ?? "")).toBe(
       fs.realpathSync(normalizationResult.srcFile),
     );
+    expect(fs.realpathSync(aliases["@openclaw/normalization-core/agent-id"] ?? "")).toBe(
+      fs.realpathSync(normalizationAgentId.srcFile),
+    );
     expect(fs.realpathSync(aliases["@openclaw/normalization-core/string-coerce"] ?? "")).toBe(
       fs.realpathSync(normalizationStringCoerce.srcFile),
     );
@@ -1860,7 +1870,7 @@ describe("plugin sdk alias helpers", () => {
     ).toBe(fs.realpathSync(modelCatalogCore.distFile));
   });
 
-  it("derives acp-core aliases from packaged root dist when package metadata is absent", () => {
+  it("derives workspace aliases from packaged root dist when package metadata is absent", () => {
     const fixture = createPluginSdkAliasFixture();
     const sourcePluginEntry = writePluginEntry(
       fixture.root,
@@ -1869,6 +1879,14 @@ describe("plugin sdk alias helpers", () => {
     const acpRuntimeErrors = path.join(fixture.root, "dist", "acp-core", "runtime", "errors.js");
     mkdirSafeDir(path.dirname(acpRuntimeErrors));
     fs.writeFileSync(acpRuntimeErrors, "export {};\n", "utf-8");
+    const normalizationAgentId = path.join(
+      fixture.root,
+      "dist",
+      "normalization-core",
+      "agent-id.js",
+    );
+    mkdirSafeDir(path.dirname(normalizationAgentId));
+    fs.writeFileSync(normalizationAgentId, "export {};\n", "utf-8");
     const cwdWithoutOpenClawPackage = makeTempDir();
 
     const aliases = withCwd(cwdWithoutOpenClawPackage, () =>
@@ -1880,6 +1898,9 @@ describe("plugin sdk alias helpers", () => {
     expect(fs.realpathSync(aliases["@openclaw/acp-core/runtime/errors"] ?? "")).toBe(
       fs.realpathSync(acpRuntimeErrors),
     );
+    expect(fs.realpathSync(aliases["@openclaw/normalization-core/agent-id"] ?? "")).toBe(
+      fs.realpathSync(normalizationAgentId),
+    );
   });
 
   it("aliases bundled plugin package public surfaces for source plugin transforms", () => {

src/plugins/sdk-alias.ts

@@ -768,25 +768,6 @@ const WORKSPACE_PACKAGE_ALIAS_ENTRIES: WorkspacePackageAliasEntry[] = [
     srcFile: "read-byte-stream-with-limit.ts",
     distFile: "read-byte-stream-with-limit.mjs",
   },
-  ...(
-    [
-      ["", "index"],
-      ["boolean-coercion", "boolean-coercion"],
-      ["error-coercion", "error-coercion"],
-      ["number-coercion", "number-coercion"],
-      ["record-coerce", "record-coerce"],
-      ["result", "result"],
-      ["string-coerce", "string-coerce"],
-      ["string-normalization", "string-normalization"],
-      ["utf16-slice", "utf16-slice"],
-    ] as const
-  ).map(([subpath, file]) => ({
-    packageName: "@openclaw/normalization-core",
-    packageDir: "normalization-core",
-    subpath,
-    srcFile: `${file}.ts`,
-    distFile: `${file}.mjs`,
-  })),
   {
     packageName: "@openclaw/retry",
     packageDir: "retry",
@@ -1343,11 +1324,13 @@ function resolveWorkspacePackageAliasMap(params: {
   const aliasMap: Record<string, string> = {};
   const workspacePackageAliasEntries = [
     ...WORKSPACE_PACKAGE_ALIAS_ENTRIES,
-    ...listWorkspacePackageExportAliasEntries({
-      packageRoot,
-      packageName: "@openclaw/acp-core",
-      packageDir: "acp-core",
-    }),
+    ...["normalization-core", "acp-core"].flatMap((packageDir) =>
+      listWorkspacePackageExportAliasEntries({
+        packageRoot,
+        packageName: `@openclaw/${packageDir}`,
+        packageDir,
+      }),
+    ),
   ];
   for (const entry of workspacePackageAliasEntries) {
     const alias = entry.subpath ? `${entry.packageName}/${entry.subpath}` : entry.packageName;