nolo-cli 0.8.0-alpha.2 → 0.8.0-alpha.21

package/chunk-TILFE6LV.js

@@ -0,0 +1,381 @@
+import {
+  asOptionalFiniteNumber
+} from "./chunk-WWC7I6TA.js";
+import {
+  asTrimmedString
+} from "./chunk-3EUW3WEO.js";
+import {
+  asOptionalTrimmedString
+} from "./chunk-G3SUCT4W.js";
+import {
+  isRecord
+} from "./chunk-KUG52IAP.js";
+
+// packages/agent-runtime/agentRecordConfig.ts
+function stringField(record, key) {
+  const value = record[key];
+  return typeof value === "string" ? value : void 0;
+}
+function numberField(record, key) {
+  return asOptionalFiniteNumber(record[key]);
+}
+function objectField(record, key) {
+  const value = record[key];
+  return isRecord(value) ? value : void 0;
+}
+function appendUniqueStrings(values, next) {
+  if (!Array.isArray(next)) return values;
+  const seen = new Set(values);
+  for (const value of next) {
+    const toolName = typeof value === "string" ? value : isRecord(value) && typeof value.name === "string" ? value.name : isRecord(value) && isRecord(value.function) && typeof value.function.name === "string" ? value.function.name : "";
+    if (toolName && !seen.has(toolName)) {
+      seen.add(toolName);
+      values.push(toolName);
+    }
+  }
+  return values;
+}
+function resolveAgentRuntimeToolNames(record) {
+  const tools = appendUniqueStrings(
+    appendUniqueStrings([], record.toolNames),
+    record.tools
+  );
+  return tools.length > 0 ? tools : void 0;
+}
+function resolveAgentRuntimeConfigFromRecord(key, record) {
+  const name = stringField(record, "name");
+  const prompt = stringField(record, "prompt");
+  const model = stringField(record, "model");
+  const apiSource = stringField(record, "apiSource");
+  const cliProvider = stringField(record, "cliProvider");
+  const customProviderUrl = stringField(record, "customProviderUrl");
+  const apiKey = stringField(record, "apiKey");
+  const apiKeyHeader = stringField(record, "apiKeyHeader");
+  const apiKeyFromAgentKey = stringField(record, "apiKeyFromAgentKey");
+  const apiKeyRef = stringField(record, "apiKeyRef");
+  const credentialRef = stringField(record, "credentialRef");
+  const credentialSynced = record.credentialSynced === true;
+  const useServerProxy = record.useServerProxy === true;
+  const provider = stringField(record, "provider") ?? stringField(record, "apiSource");
+  const toolNames = resolveAgentRuntimeToolNames(record);
+  const temperature = numberField(record, "temperature");
+  const topP = numberField(record, "top_p");
+  const frequencyPenalty = numberField(record, "frequency_penalty");
+  const presencePenalty = numberField(record, "presence_penalty");
+  const maxTokens = numberField(record, "max_tokens");
+  const reasoningEffort = stringField(record, "reasoning_effort") || stringField(record, "reasoningEffort");
+  const runtimeBinding = objectField(record, "runtimeBinding");
+  const runtimeToolPolicy = objectField(record, "runtimeToolPolicy") ?? objectField(runtimeBinding ?? {}, "runtimeToolPolicy");
+  const delegation = objectField(record, "delegation");
+  return {
+    key,
+    ...name ? { name } : {},
+    ...prompt ? { prompt } : {},
+    ...model ? { model } : {},
+    ...provider ? { provider } : {},
+    ...apiSource ? { apiSource } : {},
+    ...cliProvider ? { cliProvider } : {},
+    ...customProviderUrl ? { customProviderUrl } : {},
+    ...apiKey ? { apiKey } : {},
+    ...apiKeyHeader ? { apiKeyHeader } : {},
+    ...apiKeyFromAgentKey ? { apiKeyFromAgentKey } : {},
+    ...apiKeyRef ? { apiKeyRef } : {},
+    ...credentialRef ? { credentialRef } : {},
+    ...credentialSynced ? { credentialSynced } : {},
+    ...useServerProxy ? { useServerProxy } : {},
+    ...toolNames ? { toolNames } : {},
+    ...temperature !== void 0 ? { temperature } : {},
+    ...topP !== void 0 ? { top_p: topP } : {},
+    ...frequencyPenalty !== void 0 ? { frequency_penalty: frequencyPenalty } : {},
+    ...presencePenalty !== void 0 ? { presence_penalty: presencePenalty } : {},
+    ...maxTokens !== void 0 ? { max_tokens: maxTokens } : {},
+    ...reasoningEffort ? { reasoning_effort: reasoningEffort } : {},
+    ...runtimeBinding ? { runtimeBinding } : {},
+    ...runtimeToolPolicy ? { runtimeToolPolicy } : {},
+    ...delegation ? { delegation } : {},
+    rawRecord: record
+  };
+}
+
+// packages/agent-runtime/desktopRequestSnapshot.ts
+var DESKTOP_AGENT_CONFIG_SNAPSHOT_STRING_FIELDS = [
+  "name",
+  "prompt",
+  "provider",
+  "model",
+  "apiSource",
+  "cliProvider",
+  "customProviderUrl",
+  "credentialRef",
+  "apiKeyRef",
+  "apiKeyHeader",
+  "reasoning_effort",
+  "reasoningEffort"
+];
+var DESKTOP_AGENT_CONFIG_SNAPSHOT_NUMBER_FIELDS = [
+  "temperature",
+  "top_p",
+  "frequency_penalty",
+  "presence_penalty",
+  "max_tokens"
+];
+var DESKTOP_AGENT_CONFIG_SNAPSHOT_OBJECT_FIELDS = [
+  "runtimeBinding",
+  "runtimeToolPolicy",
+  "delegation"
+];
+var DESKTOP_AGENT_CONFIG_SNAPSHOT_FORBIDDEN_KEYS = [
+  "apiKey",
+  "apiKeyFromAgentKey",
+  "token",
+  "secret",
+  "password",
+  "accessToken",
+  "refreshToken",
+  "authorization",
+  "authToken",
+  "AUTH_TOKEN",
+  "AUTH",
+  "clientSecret",
+  "privateKey",
+  "bearer"
+];
+var DESKTOP_TOOL_CALL_ARGUMENTS_MAX_CHARS = 8192;
+var REDACTED_SECRET_PLACEHOLDER = "[redacted]";
+var FORBIDDEN_KEY_SET = new Set(
+  DESKTOP_AGENT_CONFIG_SNAPSHOT_FORBIDDEN_KEYS.map((k) => k.toLowerCase())
+);
+function isForbiddenKey(key) {
+  return FORBIDDEN_KEY_SET.has(key.toLowerCase());
+}
+function isDesktopSnapshotSensitivePropertyName(key) {
+  return isForbiddenKey(key);
+}
+function redactSensitiveJsonTree(value, depth = 0) {
+  if (depth > 6) return null;
+  if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => redactSensitiveJsonTree(item, depth + 1));
+  }
+  if (typeof value !== "object") return null;
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (isDesktopSnapshotSensitivePropertyName(key)) {
+      out[key] = REDACTED_SECRET_PLACEHOLDER;
+      continue;
+    }
+    out[key] = redactSensitiveJsonTree(child, depth + 1);
+  }
+  return out;
+}
+function sanitizeToolCallArguments(raw, maxChars = DESKTOP_TOOL_CALL_ARGUMENTS_MAX_CHARS) {
+  const source = typeof raw === "string" ? raw : raw == null ? "{}" : String(raw);
+  let candidate = source;
+  try {
+    const parsed = JSON.parse(source);
+    if (parsed && typeof parsed === "object") {
+      candidate = JSON.stringify(redactSensitiveJsonTree(parsed));
+    }
+  } catch {
+  }
+  if (candidate.length <= maxChars) return candidate;
+  return candidate.slice(0, maxChars);
+}
+function stringField2(record, key) {
+  return asOptionalTrimmedString(record[key]);
+}
+function numberField2(record, key) {
+  return asOptionalFiniteNumber(record[key]);
+}
+function uniqueToolNames(values) {
+  if (!Array.isArray(values)) return void 0;
+  const names = [];
+  const seen = /* @__PURE__ */ new Set();
+  for (const value of values) {
+    const name = asTrimmedString(value) || asTrimmedString(value?.name) || asTrimmedString(
+      value?.function?.name
+    );
+    if (!name || seen.has(name)) continue;
+    seen.add(name);
+    names.push(name);
+  }
+  return names.length > 0 ? names : void 0;
+}
+function sanitizePlainObject(value, depth = 0) {
+  if (!isRecord(value)) return void 0;
+  if (depth > 4) return void 0;
+  const out = {};
+  for (const [key, child] of Object.entries(value)) {
+    if (isForbiddenKey(key)) continue;
+    if (child === null) {
+      out[key] = null;
+      continue;
+    }
+    if (typeof child === "string" || typeof child === "number" || typeof child === "boolean") {
+      out[key] = child;
+      continue;
+    }
+    if (Array.isArray(child)) {
+      const items = child.map((item) => {
+        if (item === null || typeof item === "string" || typeof item === "number" || typeof item === "boolean") {
+          return item;
+        }
+        if (isRecord(item)) {
+          return sanitizePlainObject(item, depth + 1);
+        }
+        return void 0;
+      }).filter((item) => item !== void 0);
+      out[key] = items;
+      continue;
+    }
+    if (typeof child === "object") {
+      const nested = sanitizePlainObject(child, depth + 1);
+      if (nested) out[key] = nested;
+    }
+  }
+  return out;
+}
+function pickAllowlistedAgentConfigFields(source, dbKey) {
+  const snapshot = { dbKey };
+  for (const key of DESKTOP_AGENT_CONFIG_SNAPSHOT_STRING_FIELDS) {
+    if (key === "reasoningEffort") continue;
+    const value = stringField2(source, key);
+    if (value !== void 0) {
+      snapshot[key] = value;
+    }
+  }
+  const reasoningEffort = stringField2(source, "reasoning_effort") || stringField2(source, "reasoningEffort");
+  if (reasoningEffort) snapshot.reasoning_effort = reasoningEffort;
+  for (const key of DESKTOP_AGENT_CONFIG_SNAPSHOT_NUMBER_FIELDS) {
+    const value = numberField2(source, key);
+    if (value !== void 0) {
+      snapshot[key] = value;
+    }
+  }
+  if (source.useServerProxy === true) {
+    snapshot.useServerProxy = true;
+  } else if (source.useServerProxy === false) {
+    snapshot.useServerProxy = false;
+  }
+  const tools = uniqueToolNames(source.tools) ?? uniqueToolNames(source.toolNames);
+  if (tools) snapshot.tools = tools;
+  for (const key of DESKTOP_AGENT_CONFIG_SNAPSHOT_OBJECT_FIELDS) {
+    const value = sanitizePlainObject(source[key]);
+    if (value) {
+      snapshot[key] = value;
+    }
+  }
+  return snapshot;
+}
+function buildDesktopAgentRuntimeAgentConfigSnapshot(source, agentRef) {
+  if (!isRecord(source)) return null;
+  const ref = asTrimmedString(agentRef);
+  if (!ref) return null;
+  const claimed = stringField2(source, "dbKey") || stringField2(source, "key");
+  if (claimed && claimed !== ref) return null;
+  const dbKey = claimed || ref;
+  return pickAllowlistedAgentConfigFields(source, dbKey);
+}
+function sanitizeMessageContent(content) {
+  if (content === null || content === void 0) return null;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return null;
+  const parts = [];
+  for (const part of content) {
+    if (!part || typeof part !== "object") continue;
+    const record = part;
+    if (record.type === "text" && typeof record.text === "string") {
+      parts.push({ type: "text", text: record.text });
+    }
+  }
+  return parts.length > 0 ? parts : null;
+}
+function sanitizeToolCalls(value) {
+  if (!Array.isArray(value)) return void 0;
+  const calls = [];
+  for (const item of value) {
+    if (!item || typeof item !== "object") continue;
+    const record = item;
+    const id = asTrimmedString(record.id);
+    const fn = record.function && typeof record.function === "object" ? record.function : null;
+    const name = asTrimmedString(fn?.name);
+    const rawArgs = typeof fn?.arguments === "string" ? fn.arguments : "{}";
+    if (!id || !name) continue;
+    calls.push({
+      id,
+      type: "function",
+      function: { name, arguments: sanitizeToolCallArguments(rawArgs) }
+    });
+  }
+  return calls.length > 0 ? calls : void 0;
+}
+function sanitizeChatMessage(value) {
+  if (!isRecord(value)) return null;
+  const role = value.role;
+  if (role !== "system" && role !== "user" && role !== "assistant" && role !== "tool") {
+    return null;
+  }
+  const content = sanitizeMessageContent(value.content);
+  const message = {
+    role,
+    content
+  };
+  const toolCallId = asOptionalTrimmedString(value.tool_call_id) ?? asOptionalTrimmedString(value.toolCallId);
+  if (toolCallId) message.tool_call_id = toolCallId;
+  const toolCalls = sanitizeToolCalls(value.tool_calls);
+  if (toolCalls) message.tool_calls = toolCalls;
+  if (typeof value.reasoning_content === "string" && value.reasoning_content) {
+    message.reasoning_content = value.reasoning_content;
+  }
+  return message;
+}
+function buildDesktopAgentRuntimeDialogHistorySnapshot(args) {
+  const dialogId = asTrimmedString(args.dialogId);
+  if (!dialogId) return null;
+  if (!Array.isArray(args.messages)) return null;
+  let messages = args.messages.map((item) => sanitizeChatMessage(item)).filter((item) => item !== null);
+  messages = messages.filter((msg) => {
+    const raw = msg;
+    return raw.isStreaming !== true;
+  });
+  const inputText = normalizeContentToText(args.currentInput);
+  if (inputText && messages.length > 0) {
+    const last = messages[messages.length - 1];
+    if (last.role === "user" && normalizeContentToText(last.content) === inputText) {
+      messages = messages.slice(0, -1);
+    }
+  }
+  return { dialogId, messages };
+}
+function normalizeContentToText(content) {
+  if (typeof content === "string") return content.trim();
+  if (!Array.isArray(content)) return "";
+  return content.flatMap((part) => part?.type === "text" && part.text ? [part.text] : []).join("\n").trim();
+}
+function assertDesktopAgentRuntimeTurnBodyHasNoRawSecrets(body) {
+  if (!body || typeof body !== "object") return;
+  const json = JSON.stringify(body);
+  const walk = (value, path) => {
+    if (!value || typeof value !== "object") return;
+    if (Array.isArray(value)) {
+      value.forEach((item, index) => walk(item, `${path}[${index}]`));
+      return;
+    }
+    for (const [key, child] of Object.entries(value)) {
+      if (isForbiddenKey(key)) {
+        throw new Error(`Forbidden secret field in request body at ${path}.${key}`);
+      }
+      walk(child, path ? `${path}.${key}` : key);
+    }
+  };
+  walk(body, "");
+}
+
+export {
+  resolveAgentRuntimeConfigFromRecord,
+  buildDesktopAgentRuntimeAgentConfigSnapshot,
+  buildDesktopAgentRuntimeDialogHistorySnapshot,
+  assertDesktopAgentRuntimeTurnBodyHasNoRawSecrets
+};

package/chunk-U4TRT5V4.js

@@ -0,0 +1,246 @@
+import {
+  resolveNoloHome
+} from "./chunk-LM6IYQ3F.js";
+
+// packages/database-engine/cliAuthorityBrokerClient.ts
+import { createConnection } from "node:net";
+var DEFAULT_ITERATOR_PAGE_SIZE = 200;
+var CliAuthorityBrokerUnavailableError = class extends Error {
+  reason = "cli_authority_broker_unavailable";
+  status = 503;
+  endpoint;
+  constructor(endpoint, cause) {
+    super(`CLI authority broker unavailable at ${endpoint}. Start the local authority broker and retry.`);
+    this.name = "CliAuthorityBrokerUnavailableError";
+    this.endpoint = endpoint;
+    if (cause !== void 0) {
+      this.cause = cause;
+    }
+  }
+};
+var CliAuthorityBrokerProtocolError = class extends Error {
+  code;
+  retryable;
+  constructor(error) {
+    super(error.message);
+    this.name = "CliAuthorityBrokerProtocolError";
+    this.code = error.code;
+    this.retryable = error.retryable === true;
+  }
+};
+function isCliAuthorityBrokerUnavailableError(error) {
+  return error instanceof CliAuthorityBrokerUnavailableError || typeof error === "object" && error !== null && error.reason === "cli_authority_broker_unavailable" && error.status === 503;
+}
+function isCliAuthorityBrokerProtocolError(error) {
+  return error instanceof CliAuthorityBrokerProtocolError;
+}
+function resolveBrokerSocketTarget(endpoint) {
+  if (endpoint.startsWith("unix://")) {
+    return { kind: "unix", path: endpoint.slice("unix://".length) };
+  }
+  if (endpoint.startsWith("tcp://")) {
+    const url = new URL(endpoint);
+    return {
+      kind: "tcp",
+      host: url.hostname,
+      port: Number(url.port)
+    };
+  }
+  throw new Error(`Unsupported CLI authority broker endpoint: ${endpoint}`);
+}
+function createCliAuthorityBrokerSocketInvoker(options) {
+  const target = resolveBrokerSocketTarget(options.endpoint);
+  return async (request) => {
+    return await new Promise((resolve, reject) => {
+      const socket = target.kind === "unix" ? createConnection(target.path) : createConnection({ host: target.host, port: target.port });
+      let responseBuffer = "";
+      let settled = false;
+      const timeout = setTimeout(() => {
+        finish(() => {
+          socket.destroy();
+          reject(new Error(`CLI authority broker request at ${options.endpoint} timed out after 5000ms`));
+        });
+      }, 5e3);
+      const finish = (fn) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timeout);
+        fn();
+      };
+      socket.setEncoding("utf8");
+      socket.on("connect", () => {
+        socket.write(`${JSON.stringify(request)}
+`);
+      });
+      socket.on("data", (chunk) => {
+        responseBuffer += chunk;
+      });
+      socket.on("end", () => {
+        finish(() => {
+          const payload = responseBuffer.trim();
+          if (!payload) {
+            reject(new Error(`CLI authority broker at ${options.endpoint} returned no response`));
+            return;
+          }
+          try {
+            resolve(JSON.parse(payload));
+          } catch (error) {
+            reject(error);
+          }
+        });
+      });
+      socket.on("error", (error) => {
+        finish(() => reject(error));
+      });
+    });
+  };
+}
+async function invokeBrokerRequest(options, request) {
+  try {
+    const response = await options.invoke(request);
+    if (response.ok) return response.result;
+    if (response.error.code === "BROKER_UNAVAILABLE") {
+      throw new CliAuthorityBrokerUnavailableError(options.endpoint, response.error);
+    }
+    throw new CliAuthorityBrokerProtocolError(response.error);
+  } catch (error) {
+    if (isCliAuthorityBrokerUnavailableError(error)) throw error;
+    if (isCliAuthorityBrokerProtocolError(error)) throw error;
+    throw new CliAuthorityBrokerUnavailableError(options.endpoint, error);
+  }
+}
+function createCliAuthorityBrokerClient(options) {
+  const pageSize = options.iteratorPageSize ?? DEFAULT_ITERATOR_PAGE_SIZE;
+  return {
+    get location() {
+      return options.location ?? options.endpoint;
+    },
+    get status() {
+      return options.status ?? "broker";
+    },
+    async open() {
+      await invokeBrokerRequest(options, { type: "status" });
+    },
+    async close() {
+    },
+    async get(key) {
+      const result = await invokeBrokerRequest(options, { type: "get", key });
+      if (result.type !== "get") {
+        throw new Error(`CLI authority broker protocol mismatch for get at ${options.endpoint}`);
+      }
+      return result.value;
+    },
+    async put(key, value) {
+      await invokeBrokerRequest(options, { type: "put", key, value });
+    },
+    async del(key) {
+      await invokeBrokerRequest(options, { type: "del", key });
+    },
+    async batchWrite(ops) {
+      await invokeBrokerRequest(options, { type: "batchWrite", ops });
+    },
+    createBatch() {
+      const ops = [];
+      return {
+        put(key, value) {
+          ops.push({ type: "put", key, value });
+        },
+        del(key) {
+          ops.push({ type: "del", key });
+        },
+        async write() {
+          await invokeBrokerRequest(options, { type: "batchWrite", ops });
+        }
+      };
+    },
+    iterator(iteratorOptions = {}) {
+      return async function* iterate() {
+        let cursor = void 0;
+        while (true) {
+          const result = await invokeBrokerRequest(options, {
+            type: "iterator",
+            options: iteratorOptions,
+            cursor,
+            limit: pageSize
+          });
+          if (result.type !== "iterator") {
+            throw new Error(
+              `CLI authority broker protocol mismatch for iterator at ${options.endpoint}`
+            );
+          }
+          for (const entry of result.page.entries) {
+            yield entry;
+          }
+          if (result.page.done || !result.page.nextCursor) return;
+          cursor = result.page.nextCursor;
+        }
+      }();
+    }
+  };
+}
+
+// packages/database-engine/cliAuthorityStoreDriver.ts
+import path from "node:path";
+function readCliAuthorityDriver(env) {
+  const value = env.NOLO_CLI_AUTHORITY_DRIVER?.trim();
+  if (value === "broker") {
+    return { driver: "broker", invalidDriver: null };
+  }
+  return {
+    driver: "broker",
+    invalidDriver: value ? value : null
+  };
+}
+function resolveCliAuthorityRunDir(options = {}) {
+  return path.join(resolveNoloHome({
+    ...options,
+    env: options.env ?? {}
+  }), "run");
+}
+function hashString(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash << 5) - hash + value.charCodeAt(index) | 0;
+  }
+  return Math.abs(hash);
+}
+function resolveCliAuthorityBrokerPort(options = {}) {
+  const envPort = options.env?.NOLO_CLI_AUTHORITY_BROKER_PORT?.trim();
+  if (envPort) {
+    const port = Number(envPort);
+    if (Number.isInteger(port) && port > 0 && port < 65536) return port;
+  }
+  const noloHome = resolveNoloHome({
+    ...options,
+    env: options.env ?? {}
+  });
+  return 47e3 + hashString(noloHome) % 2e3;
+}
+function resolveCliAuthorityStoreDriver(options = {}) {
+  return readCliAuthorityDriver(options.env ?? {}).driver;
+}
+function resolveCliAuthorityBrokerSocketPath(options) {
+  return path.join(resolveCliAuthorityRunDir(options), "authority-store-broker.sock");
+}
+function resolveCliAuthorityBrokerEndpoint(options) {
+  if (options.transport === "tcp") {
+    return `tcp://127.0.0.1:${resolveCliAuthorityBrokerPort(options)}`;
+  }
+  return `unix://${resolveCliAuthorityBrokerSocketPath(options)}`;
+}
+function resolveCliAuthorityBrokerMetadataPath(options) {
+  return path.join(resolveCliAuthorityRunDir(options), "authority-store-broker.json");
+}
+function resolveCliAuthorityBrokerHealthPath(options) {
+  return path.join(resolveCliAuthorityRunDir(options), "authority-store-broker.health.json");
+}
+
+export {
+  isCliAuthorityBrokerUnavailableError,
+  createCliAuthorityBrokerSocketInvoker,
+  createCliAuthorityBrokerClient,
+  resolveCliAuthorityStoreDriver,
+  resolveCliAuthorityBrokerEndpoint,
+  resolveCliAuthorityBrokerMetadataPath,
+  resolveCliAuthorityBrokerHealthPath
+};

package/chunk-U6VC4MU4.js

@@ -0,0 +1,8 @@
+// packages/core/optionalPositiveNumber.ts
+function asOptionalPositiveFiniteNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) && value > 0 ? value : void 0;
+}
+
+export {
+  asOptionalPositiveFiniteNumber
+};

package/chunk-UAD2WT54.js

@@ -0,0 +1,64 @@
+// packages/create/space/spaceKeys.ts
+var SEPARATOR = "-";
+var SPACE_PREFIX = "space";
+var SPACE_PREFIX_WITH_SEPARATOR = `${SPACE_PREFIX}${SEPARATOR}`;
+var normalizeSpaceId = (spaceId) => {
+  if (!spaceId) return spaceId;
+  return spaceId.startsWith(SPACE_PREFIX_WITH_SEPARATOR) ? spaceId.slice(SPACE_PREFIX_WITH_SEPARATOR.length) : spaceId;
+};
+var createSpaceKey = {
+  // 空间基础信息的key
+  space: (spaceId) => {
+    return [SPACE_PREFIX, normalizeSpaceId(spaceId)].join(SEPARATOR);
+  },
+  // 空间成员的key
+  member: (userId, spaceId) => {
+    return [SPACE_PREFIX, "member", userId, normalizeSpaceId(spaceId)].join(
+      SEPARATOR
+    );
+  },
+  // 查询用户所在的所有空间的范围
+  memberRange: (userId) => {
+    return {
+      start: [SPACE_PREFIX, "member", userId, ""].join(SEPARATOR),
+      end: [SPACE_PREFIX, "member", userId, "\uFFFF"].join(SEPARATOR)
+    };
+  },
+  /**
+   * 预留：未来若出现“按用户、按空间、且必须跨设备同步”的空间级偏好，
+   * 统一使用这个 key family。当前产品主链不要依赖它。
+   */
+  setting: (userId, spaceId) => {
+    return [SPACE_PREFIX, "setting", userId, normalizeSpaceId(spaceId)].join(
+      SEPARATOR
+    );
+  },
+  /**
+   * 预留：未来如确实需要批量读取空间级远端偏好，再使用这个范围。
+   */
+  settingRange: (userId) => {
+    return {
+      start: [SPACE_PREFIX, "setting", userId, ""].join(SEPARATOR),
+      end: [SPACE_PREFIX, "setting", userId, "\uFFFF"].join(SEPARATOR)
+    };
+  },
+  // 从成员key中提取空间key
+  // 成员 key 格式: space-member-{userId}-{spaceId}
+  // userId 是单段（无连字符），spaceId 是 ULID（无连字符）
+  spaceFromMember: (memberKey) => {
+    const parts = memberKey.split(SEPARATOR);
+    if (parts.length < 4) return "";
+    const spaceId = parts[parts.length - 1];
+    return [SPACE_PREFIX, spaceId].join(SEPARATOR);
+  },
+  // 从成员key中提取空间ID
+  spaceIdFromMember: (memberKey) => {
+    const parts = memberKey.split(SEPARATOR);
+    return parts.length >= 4 ? parts[parts.length - 1] : "";
+  }
+};
+
+export {
+  normalizeSpaceId,
+  createSpaceKey
+};