nolo-cli 0.1.30 → 0.1.31

package/auth/server/token.ts

@@ -1,7 +1,6 @@
 // auth/handleToken.js
-import { verifyToken, parseToken } from "../token";
-import { assertSessionTokenVersion } from "../sessionTokenVersion";
-import serverDb from "../../database/server/db";
+import { getServerAuthorityStore } from "../../database/server/db";
+import { authenticateToken } from "../../server/authenticateToken";
 import { balanceLockManager } from "./locks";
 import { recordUserAccessActivity } from "./accessActivity";
 
@@ -15,21 +14,14 @@ const getUserActivityUpdateIntervalMs = () => {
     : 5 * 60 * 1000;
 };
 
-const getPublicKey = async (userId) => {
-  try {
-    const user = await serverDb.get(`user:${userId}`);
-    if (user?.publicKey) return user.publicKey;
-  } catch { }
-  return null;
-};
-
 const updateUserLastActiveAt = async (userId, metadata?: { ip?: string | null; userAgent?: string | null }) => {
+  const store = getServerAuthorityStore();
   const key = `user:${userId}`;
   const lock = balanceLockManager.getLock(userId);
   let shouldRecord = false;
   try {
     await lock.runExclusive(async () => {
-      const user = await serverDb.get(key);
+      const user = await store.get(key);
       if (!user) return;
 
       const now = Date.now();
@@ -57,53 +49,59 @@ const updateUserLastActiveAt = async (userId, metadata?: { ip?: string | null; u
   }
 };
 
-// NOTE: 这里用 new Date(exp) 处理 ISO 字符串，
-// 而 verifyToken 只检查 number 类型 exp（见 auth/token.ts 的 BUG 注释）
-// 两套逻辑不一致，待 token.ts 的 exp 检查统一修复后可删除此函数
-const isTokenExpired = ({ exp, nbf }) => {
-  const now = Date.now();
-  return (exp && now > exp * 1000) || (nbf && now < nbf * 1000);
-};
-
-export async function handleToken(req, res) {
-  const token = req.headers.get("authorization")?.split(" ")[1];
-  const requestIp =
-    req.headers.get("x-nolo-client-ip")?.trim() ||
-    req.headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
-    req.headers.get("x-real-ip") ||
-    "";
-  const userAgent = req.headers.get("user-agent") || "";
-  if (!token) return handleError(res, new Error("Access denied. No token provided."), 401);
-
-  try {
-    // parseToken 使用 js-base64，正确处理中文用户名的 UTF-8 编码
-    // 原 atob 方案在中文用户名时会产生乱码，导致 userId 错误、publicKey 查找失败
-    const parsed = parseToken(token);
-    if (!parsed?.userId) return handleError(res, new Error("Invalid token format"), 401);
-    const { userId } = parsed;
-    const publicKey = await getPublicKey(userId);
-
-    if (!publicKey) return handleError(res, new Error("Public key not found"), 401);
+const readBearerToken = (headers: { get(name: string): string | null | undefined }) =>
+  headers.get("authorization")?.split(" ")[1];
 
-    const user = await serverDb.get(`user:${userId}`);
-    if (!user?.publicKey) {
-      return handleError(res, new Error("Public key not found"), 401);
-    }
+const readRequestMetadata = (headers: { get(name: string): string | null | undefined }) => ({
+  ip:
+    headers.get("x-nolo-client-ip")?.trim() ||
+    headers.get("x-forwarded-for")?.split(",")[0]?.trim() ||
+    headers.get("x-real-ip") ||
+    "",
+  userAgent: headers.get("user-agent") || "",
+});
 
-    const payload = verifyToken(token, publicKey);
-    assertSessionTokenVersion(payload, user);
-    // NOTE: verifyToken 验签失败会直接 throw，不会返回 null/falsy
-    // 所以下面这行是死代码，永远不会执行
-    if (!payload) return handleError(res, new Error("Invalid token"), 401);
+type TokenAuthResult =
+  | { ok: true; payload: any }
+  | { ok: false; error: Error; status: number };
 
-    // NOTE: verifyToken 内部已检查 Unix 秒格式的 exp，这里再检查 ISO 字符串格式
-    // 两处检查逻辑不同，待 token.ts 修复后可删除此行
-    if (isTokenExpired(payload)) return handleError(res, new Error("Token has expired"), 401);
+async function authenticateRequestHeaders(
+  headers: { get(name: string): string | null | undefined }
+): Promise<TokenAuthResult> {
+  const token = readBearerToken(headers);
+  if (!token) {
+    return {
+      ok: false,
+      error: new Error("Access denied. No token provided."),
+      status: 401,
+    };
+  }
 
-    await updateUserLastActiveAt(userId, { ip: requestIp, userAgent });
+  try {
+    const { userId, payload } = await authenticateToken(token);
+    const { ip, userAgent } = readRequestMetadata(headers);
+    await updateUserLastActiveAt(userId, { ip, userAgent });
+    return { ok: true, payload };
+  } catch (error: any) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error : new Error(String(error)),
+      status: 401,
+    };
+  }
+}
 
-    return payload;
-  } catch (err) {
-    return handleError(res, err, 401);
+export async function handleToken(req, res) {
+  const result = await authenticateRequestHeaders(req.headers);
+  if (!result.ok) {
+    return handleError(res, result.error, result.status);
   }
+  return result.payload;
+}
+
+export async function readUserFromRequest(
+  req: Pick<Request, "headers"> | { headers: { get(name: string): string | null | undefined } }
+) {
+  const result = await authenticateRequestHeaders(req.headers);
+  return result.ok ? result.payload : null;
 }

package/auth/server/tokenUsageBilling.ts

@@ -1,5 +1,6 @@
 import { DB_PREFIX, createTransactionKey } from "../../database/keys";
-import serverDb from "../../database/server/db";
+import { getServerAuthorityStore } from "../../database/server/db";
+import { writeStoreOps } from "../../database/server/storeBatchCompat";
 
 import { balanceLockManager } from "./locks";
 import {
@@ -49,6 +50,14 @@ export type TokenUsageChargeResult =
       balance?: number;
     };
 
+const createTokenUsageBillingStore = (authorityStore = getServerAuthorityStore()): TokenUsageBillingStore => ({
+  get: (key) => authorityStore.get(key),
+  batch: (ops) => writeStoreOps(authorityStore, ops),
+});
+
+const getDefaultTokenUsageBillingStore = (): TokenUsageBillingStore =>
+  createTokenUsageBillingStore(getServerAuthorityStore());
+
 const getMaybe = async <T>(
   store: TokenUsageBillingStore,
   key: string
@@ -64,13 +73,15 @@ const isPositiveFinite = (value: unknown): value is number =>
   typeof value === "number" && Number.isFinite(value) && value > 0;
 
 export async function chargeTokenUsageWithLedger({
-  store = serverDb,
+  store = getDefaultTokenUsageBillingStore(),
   runtime = getBillingLedgerRuntime(),
   userId,
   tokenKey,
   tokenRecord,
   reason = "token_usage",
   txId = `token-${tokenKey}`,
+  ledgerIdempotencyKey = `token:${tokenKey}`,
+  allowBuyerNegative = true,
   nowMs = Date.now(),
 }: {
   store?: TokenUsageBillingStore;
@@ -80,6 +91,8 @@ export async function chargeTokenUsageWithLedger({
   tokenRecord: TokenRevenueShareRecord;
   reason?: string;
   txId?: string;
+  ledgerIdempotencyKey?: string;
+  allowBuyerNegative?: boolean;
   nowMs?: number;
 }): Promise<TokenUsageChargeResult> {
   const lock = balanceLockManager.getLock(`token-usage:${userId}:${tokenKey}`);
@@ -159,7 +172,7 @@ export async function chargeTokenUsageWithLedger({
         runtime,
         type: "usage_charge",
         reason,
-        idempotencyKey: `token:${tokenKey}`,
+        idempotencyKey: ledgerIdempotencyKey,
         txId,
         entries: [
           {
@@ -167,6 +180,7 @@ export async function chargeTokenUsageWithLedger({
             ownerUserId: userId,
             delta: -event.grossCredits,
             startingBalance: userData.balance,
+            allowNegative: allowBuyerNegative,
             metadata: {
               role: "buyer_debit",
               tokenKey,
@@ -217,10 +231,7 @@ export async function chargeTokenUsageWithLedger({
           amountCredits: event.grossCredits,
         };
       }
-      if (
-        ledgerAppend.status === "insufficient_funds" ||
-        userData.balance < event.grossCredits
-      ) {
+      if (ledgerAppend.status === "insufficient_funds") {
         return {
           success: false,
           status: "insufficient_funds",

package/auth/server/usageManagementAccess.ts

@@ -0,0 +1,43 @@
+import { isSystemAdmin } from "../../core/init";
+import { DB_PREFIX } from "../../database/keys";
+import { getServerAuthorityStore } from "../../database/server/db";
+import {
+  hasUsageManagementPermission,
+  mergeAdminPermissions,
+  type AdminPermissions,
+} from "../adminPermissions";
+
+type UserStore = {
+  get(key: string): Promise<any>;
+  put(key: string, value: any): Promise<void>;
+};
+
+const userKey = (userId: string) => `${DB_PREFIX.USER}${userId}`;
+
+export async function canManageUsageReportAccess(
+  userId?: string | null,
+  store: Pick<UserStore, "get"> = getServerAuthorityStore()
+): Promise<boolean> {
+  if (!userId) return false;
+  if (isSystemAdmin(userId)) return true;
+  const userData = await store.get(userKey(userId)).catch(() => null);
+  return hasUsageManagementPermission(userData);
+}
+
+export async function updateUserAdminPermissions(
+  targetUserId: string,
+  patch: Partial<AdminPermissions>,
+  store: UserStore = getServerAuthorityStore()
+) {
+  const key = userKey(targetUserId);
+  const userData = await store.get(key).catch(() => null);
+  if (!userData) return null;
+  const adminPermissions = mergeAdminPermissions(userData.adminPermissions, patch);
+  const updatedUser = {
+    ...userData,
+    adminPermissions,
+    adminPermissionsUpdatedAt: Date.now(),
+  };
+  await store.put(key, updatedUser);
+  return updatedUser;
+}

package/auth/server/usageReport.ts

@@ -0,0 +1,59 @@
+import { getServerAuthorityStore } from "../../database/server/db";
+import { buildBillingUsageReport } from "./billingUsageReport";
+import {
+  createErrorResponse,
+  createSuccessResponse,
+  handleOptionsRequest,
+} from "./shared";
+import { canManageUsageReportAccess } from "./usageManagementAccess";
+
+const parseTimestamp = (value: string | null) => {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  const parsed = Date.parse(trimmed);
+  return Number.isFinite(parsed) ? parsed : null;
+};
+
+const parseSinceDays = (value: string | null) => {
+  if (!value) return 7;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed) || parsed <= 0) return 7;
+  return Math.min(parsed, 3660);
+};
+
+export async function handleGetUsageReport(req: Request) {
+  if (req.method === "OPTIONS") {
+    return handleOptionsRequest();
+  }
+
+  const { userId: actionUserId } = req.user;
+  if (!(await canManageUsageReportAccess(actionUserId))) {
+    return createErrorResponse("Unauthorized: Usage management access required", 403);
+  }
+
+  try {
+    const url = new URL(req.url);
+    const now = Date.now();
+    const untilMs = parseTimestamp(url.searchParams.get("until")) ?? now;
+    const sinceMs =
+      parseTimestamp(url.searchParams.get("since")) ??
+      untilMs - parseSinceDays(url.searchParams.get("sinceDays")) * 24 * 3600_000;
+
+    if (sinceMs > untilMs) {
+      return createErrorResponse("Invalid time range", 400);
+    }
+
+    const report = await buildBillingUsageReport({
+      store: getServerAuthorityStore(),
+      sinceMs,
+      untilMs,
+      nowMs: now,
+    });
+
+    return createSuccessResponse({ success: true, report });
+  } catch {
+    return createErrorResponse("Internal server error");
+  }
+}

package/auth/types.ts

@@ -1,4 +1,5 @@
 // auth/types.ts
+import type { AdminPermissions } from "./adminPermissions";
 
 export interface User {
   userId: string;
@@ -10,6 +11,17 @@ export interface User {
   locale?: string;
   publicKey?: string;
   tokenVersion?: number;
+  balance?: number;
+  gptProAccess?: {
+    status?: string;
+    requiredRechargeAmount?: number;
+    rechargeAmount?: number;
+    source?: string;
+    sourceTxId?: string;
+    grantedAt?: number;
+    updatedAt?: number;
+  };
+  adminPermissions?: AdminPermissions;
 }
 export interface TokenManager {
   getTokens(): Promise<string[]>;

package/auth/utils.ts

@@ -1,8 +1,8 @@
 // path auth/utils.ts
-import { parseToken, verifyToken } from ".//token";
-import { assertSessionTokenVersion } from ".//sessionTokenVersion";
-import serverDb from "../database/server/db";
-import { WEB_AUTH_TOKEN_COOKIE } from "./tokenCookie";
+import { parseToken, verifyToken } from ".//token";
+import { assertSessionTokenVersion } from ".//sessionTokenVersion";
+import { getServerAuthorityStore } from "../database/server/db";
+import { WEB_AUTH_TOKEN_COOKIE } from "./tokenCookie";
 
 export const CORS_HEADERS_AUTH = {
   "Access-Control-Allow-Origin": "*",
@@ -11,22 +11,24 @@ export const CORS_HEADERS_AUTH = {
   "Access-Control-Max-Age": "86400",
 };
 
-export const authErrorResponse = (
-  msg: string,
-  code: string,
+export const authErrorResponse = (
+  msg: string,
+  code: string,
   status: number = 500
 ): Response =>
   new Response(JSON.stringify({ error: { message: msg, code } }), {
     status,
     headers: { "Content-Type": "application/json", ...CORS_HEADERS_AUTH },
-  });
-
-const getPublicKey = async (userId: string) => {
-  try {
-    const u = await serverDb.get(`user:${userId}`);
-    if (!u?.publicKey || u.balance <= 0 || u.isDisabled) {
-      return { publicKey: null, isValid: false };
-    }
+  });
+
+const getAuthUtilsStore = () => getServerAuthorityStore();
+
+const getPublicKey = async (userId: string) => {
+  try {
+    const u = await getAuthUtilsStore().get(`user:${userId}`);
+    if (!u?.publicKey || u.balance <= 0 || u.isDisabled) {
+      return { publicKey: null, isValid: false };
+    }
     return { publicKey: u.publicKey, isValid: true };
   } catch (e) {
     return { publicKey: null, isValid: false };
@@ -66,13 +68,13 @@ export const authenticateRequest = async (
       );
     }
 
-    const { publicKey, isValid } = await getPublicKey(userIdFromTokenHeader);
-    if (!isValid || !publicKey) {
-      return authErrorResponse("Invalid account.", "AUTH_ACCOUNT_INVALID", 401);
-    }
-
-    const user = await serverDb.get(`user:${userIdFromTokenHeader}`);
-    const decodedTokenData = verifyToken(token, publicKey);
+    const { publicKey, isValid } = await getPublicKey(userIdFromTokenHeader);
+    if (!isValid || !publicKey) {
+      return authErrorResponse("Invalid account.", "AUTH_ACCOUNT_INVALID", 401);
+    }
+
+    const user = await getAuthUtilsStore().get(`user:${userIdFromTokenHeader}`);
+    const decodedTokenData = verifyToken(token, publicKey);
     assertSessionTokenVersion(decodedTokenData, user);
     if (!decodedTokenData) {
       return authErrorResponse(

package/authCommands.ts

@@ -9,6 +9,7 @@ import {
   loadProfileConfig,
   saveDefaultProfile,
 } from "./client/profileConfig";
+import { parseUserIdFromAuthToken } from "./cliEnvHelpers";
 import { DEFAULT_NOLO_SERVER_URL } from "./defaultServer";
 
 function getArg(args: string[], flag: string) {
@@ -67,17 +68,47 @@ async function saveTokenLogin(args: {
   configPath: string;
   serverUrl: string;
   authToken: string;
+  fetchImpl: typeof fetch;
   output: Pick<Console, "log">;
   error: Pick<Console, "error">;
 }) {
-  if (!args.authToken.trim()) {
+  const authToken = args.authToken.trim();
+  if (!authToken) {
     args.error.error("No auth token provided.");
     return 1;
   }
 
+  const userId = parseUserIdFromAuthToken(authToken);
+  if (!userId) {
+    args.error.error("Auth token payload is missing userId.");
+    return 1;
+  }
+
+  try {
+    const res = await args.fetchImpl(
+      `${args.serverUrl}/api/v1/db/query/${encodeURIComponent(userId)}?limit=1`,
+      {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${authToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ type: "agent" }),
+      }
+    );
+    if (res.status === 401 || res.status === 403) {
+      args.error.error(
+        `Auth token is not valid for ${args.serverUrl}. Log in against the matching server or use a token issued by that server.`
+      );
+      return 1;
+    }
+  } catch {
+    // Allow saving when the server is temporarily unreachable.
+  }
+
   saveDefaultProfile(args.configPath, {
     serverUrl: args.serverUrl,
-    authToken: args.authToken.trim(),
+    authToken,
   });
   args.output.log(`Saved profile default -> ${args.serverUrl}`);
   return 0;
@@ -144,6 +175,7 @@ async function runWebLogin(args: {
         configPath: args.configPath,
         serverUrl: approvedServer,
         authToken: poll.token,
+        fetchImpl: args.fetchImpl,
         output: args.output,
         error: args.error,
       });
@@ -173,6 +205,7 @@ export async function runLoginCommand(args: string[], deps: LoginCommandDeps = {
       configPath,
       serverUrl,
       authToken: tokenArg,
+      fetchImpl: deps.fetchImpl ?? fetch,
       output: outputTarget,
       error: errorTarget,
     });
@@ -187,6 +220,7 @@ export async function runLoginCommand(args: string[], deps: LoginCommandDeps = {
         configPath,
         serverUrl,
         authToken,
+        fetchImpl: deps.fetchImpl ?? fetch,
         output: outputTarget,
         error: errorTarget,
       });

package/buildPublish.ts

@@ -73,10 +73,12 @@ export async function buildPublishArtifact(
   );
 
   if (inlinedDeps.length > 0) {
-    publishManifest.files = publishManifest.files || [];
+    publishManifest.files = Array.from(new Set(resolvedFilesToCopy));
     for (const dep of inlinedDeps) {
       publishManifest.files.push(`${dep}/**/*.ts`);
     }
+  } else {
+    publishManifest.files = Array.from(new Set(resolvedFilesToCopy));
   }
 
   if (Object.keys(externalDeps).length > 0) {

package/buildPublishArtifactAssembly.ts

@@ -11,6 +11,7 @@ import {
 import { dirname, join, relative } from "node:path";
 import {
   collectTypeScriptSourceFiles,
+  extractLocalRelativeImports,
   findTypeScriptFiles,
 } from "./buildPublishImportAnalysis";
 
@@ -71,7 +72,10 @@ export async function buildPublishArtifactAssembly(
   rmSync(distDir, { recursive: true, force: true });
   mkdirSync(distDir, { recursive: true });
 
-  const resolvedFilesToCopy = resolveFilesToCopy(sourceDir, filesToCopy);
+  const resolvedFilesToCopy = expandLocalFileDependencies(
+    sourceDir,
+    resolveFilesToCopy(sourceDir, filesToCopy)
+  );
   const workspaceDeps = collectWorkspaceDependencies(sourceDir, resolvedFilesToCopy);
 
   for (const file of resolvedFilesToCopy) {
@@ -288,6 +292,63 @@ async function discoverExternalImportsFromInlinedFiles(
 
 export { collectTypeScriptSourceFiles, findTypeScriptFiles };
 
+export function expandLocalFileDependencies(sourceDir: string, filesToCopy: string[]): string[] {
+  const resolved = new Set(filesToCopy);
+  const pending = filesToCopy.filter((file) => file.endsWith(".ts"));
+
+  while (pending.length > 0) {
+    const relativeFilePath = pending.pop()!;
+    const absoluteFilePath = join(sourceDir, relativeFilePath);
+    if (!existsSync(absoluteFilePath)) {
+      continue;
+    }
+
+    const content = readFileSync(absoluteFilePath, "utf8");
+    for (const importPath of extractLocalRelativeImports(content)) {
+      const discoveredPath = resolveLocalImportPath(sourceDir, relativeFilePath, importPath);
+      if (!discoveredPath || resolved.has(discoveredPath)) {
+        continue;
+      }
+      resolved.add(discoveredPath);
+      if (discoveredPath.endsWith(".ts")) {
+        pending.push(discoveredPath);
+      }
+    }
+  }
+
+  return Array.from(resolved);
+}
+
+function resolveLocalImportPath(
+  sourceDir: string,
+  relativeFilePath: string,
+  importPath: string
+): string | null {
+  const fileDir = dirname(join(sourceDir, relativeFilePath));
+  const importBase = join(fileDir, importPath);
+  const candidates = [
+    importBase,
+    `${importBase}.ts`,
+    `${importBase}.tsx`,
+    join(importBase, "index.ts"),
+    join(importBase, "index.tsx"),
+    `${importBase}.json`,
+  ];
+
+  for (const candidate of candidates) {
+    if (!existsSync(candidate)) {
+      continue;
+    }
+    const stat = statSync(candidate);
+    if (!stat.isFile()) {
+      continue;
+    }
+    return relative(sourceDir, candidate).replace(/\\/g, "/");
+  }
+
+  return null;
+}
+
 export function resolveFilesToCopy(sourceDir: string, filesToCopy: string[]): string[] {
   const resolved = new Set<string>();
 

package/buildPublishImportAnalysis.ts

@@ -11,27 +11,27 @@ function extractPackageNameFromImportPath(importPath: string): string {
   return firstSlash === -1 ? importPath : importPath.slice(0, firstSlash);
 }
 
-export function extractExternalImports(content: string): string[] {
-  const imports = new Set<string>();
-  const importRegex =
-    /import\s+(?:(?:type\s+)?(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+)?['"]([^'"]+)['"]/g;
+function extractModuleSpecifiers(content: string): string[] {
+  const specifiers = new Set<string>();
+  const importOrExportRegex =
+    /(?:import|export)\s+(?:(?:type\s+)?(?:\{[^}]*\}|\*\s+as\s+\w+|\w+)\s+from\s+)?['"]([^'"]+)['"]/g;
   const dynamicImportRegex = /import\(\s*['"]([^'"]+)['"]\s*\)/g;
 
   let match: RegExpExecArray | null;
-  while ((match = importRegex.exec(content)) !== null) {
-    const importPath = match[1];
-    if (
-      importPath.startsWith(".") ||
-      importPath.startsWith("node:") ||
-      importPath.startsWith("/")
-    ) {
-      continue;
-    }
-    imports.add(extractPackageNameFromImportPath(importPath));
+  while ((match = importOrExportRegex.exec(content)) !== null) {
+    specifiers.add(match[1]);
   }
 
   while ((match = dynamicImportRegex.exec(content)) !== null) {
-    const importPath = match[1];
+    specifiers.add(match[1]);
+  }
+
+  return Array.from(specifiers);
+}
+
+export function extractExternalImports(content: string): string[] {
+  const imports = new Set<string>();
+  for (const importPath of extractModuleSpecifiers(content)) {
     if (
       importPath.startsWith(".") ||
       importPath.startsWith("node:") ||
@@ -41,10 +41,15 @@ export function extractExternalImports(content: string): string[] {
     }
     imports.add(extractPackageNameFromImportPath(importPath));
   }
-
   return Array.from(imports);
 }
 
+export function extractLocalRelativeImports(content: string): string[] {
+  return extractModuleSpecifiers(content).filter(
+    (importPath) => importPath.startsWith(".") && !importPath.startsWith("/")
+  );
+}
+
 export function extractWorkspaceDependencies(
   manifest: Record<string, any>
 ): string[] {

package/chat/dialog/dialogLaunchScope.ts

@@ -0,0 +1,32 @@
+export interface DialogLaunchScopeInput {
+  routeSpaceId?: string | null;
+  recordSpaceId?: string | null;
+  currentSpaceId?: string | null;
+  viewMode?: string | null;
+  allowSidebarSpaceFallback?: boolean;
+}
+
+const trimSpaceId = (spaceId?: string | null): string | null => {
+  if (typeof spaceId !== "string") return null;
+  const trimmed = spaceId.trim();
+  return trimmed.length > 0 ? trimmed : null;
+};
+
+export const resolveDialogLaunchSpaceId = ({
+  routeSpaceId,
+  recordSpaceId,
+  currentSpaceId,
+  viewMode,
+  allowSidebarSpaceFallback = false,
+}: DialogLaunchScopeInput): string | null => {
+  const explicitSpaceId = trimSpaceId(routeSpaceId) ?? trimSpaceId(recordSpaceId);
+  if (explicitSpaceId) {
+    return explicitSpaceId;
+  }
+
+  if (!allowSidebarSpaceFallback || viewMode !== "categories") {
+    return null;
+  }
+
+  return trimSpaceId(currentSpaceId);
+};