opensteer 0.6.0 → 0.6.2

package/dist/chunk-WDRMHPWL.js

@@ -0,0 +1,1320 @@
+// src/error-normalization.ts
+function extractErrorMessage(error, fallback = "Unknown error.") {
+  if (error instanceof Error) {
+    const message = error.message.trim();
+    if (message) return message;
+    const name = error.name.trim();
+    if (name) return name;
+  }
+  if (typeof error === "string" && error.trim()) {
+    return error.trim();
+  }
+  const record = asRecord(error);
+  const recordMessage = toNonEmptyString(record?.message) || toNonEmptyString(record?.error);
+  if (recordMessage) {
+    return recordMessage;
+  }
+  return fallback;
+}
+function normalizeError(error, fallback = "Unknown error.", maxCauseDepth = 2) {
+  const seen = /* @__PURE__ */ new WeakSet();
+  return normalizeErrorInternal(error, fallback, maxCauseDepth, seen);
+}
+function normalizeErrorInternal(error, fallback, depthRemaining, seen) {
+  const record = asRecord(error);
+  if (record) {
+    if (seen.has(record)) {
+      return {
+        message: extractErrorMessage(error, fallback)
+      };
+    }
+    seen.add(record);
+  }
+  const message = extractErrorMessage(error, fallback);
+  const code = extractCode(error);
+  const name = extractName(error);
+  const details = extractDetails(error);
+  if (depthRemaining <= 0) {
+    return compactErrorInfo({
+      message,
+      ...code ? { code } : {},
+      ...name ? { name } : {},
+      ...details ? { details } : {}
+    });
+  }
+  const cause = extractCause(error);
+  if (!cause) {
+    return compactErrorInfo({
+      message,
+      ...code ? { code } : {},
+      ...name ? { name } : {},
+      ...details ? { details } : {}
+    });
+  }
+  const normalizedCause = normalizeErrorInternal(
+    cause,
+    "Caused by an unknown error.",
+    depthRemaining - 1,
+    seen
+  );
+  return compactErrorInfo({
+    message,
+    ...code ? { code } : {},
+    ...name ? { name } : {},
+    ...details ? { details } : {},
+    cause: normalizedCause
+  });
+}
+function compactErrorInfo(info) {
+  const safeDetails = toJsonSafeRecord(info.details);
+  return {
+    message: info.message,
+    ...info.code ? { code: info.code } : {},
+    ...info.name ? { name: info.name } : {},
+    ...safeDetails ? { details: safeDetails } : {},
+    ...info.cause ? { cause: info.cause } : {}
+  };
+}
+function extractCode(error) {
+  const record = asRecord(error);
+  const raw = record?.code;
+  if (typeof raw === "string" && raw.trim()) {
+    return raw.trim();
+  }
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return String(raw);
+  }
+  return void 0;
+}
+function extractName(error) {
+  if (error instanceof Error && error.name.trim()) {
+    return error.name.trim();
+  }
+  const record = asRecord(error);
+  return toNonEmptyString(record?.name);
+}
+function extractDetails(error) {
+  const record = asRecord(error);
+  if (!record) return void 0;
+  const details = {};
+  const rawDetails = asRecord(record.details);
+  if (rawDetails) {
+    Object.assign(details, rawDetails);
+  }
+  const action = toNonEmptyString(record.action);
+  if (action) {
+    details.action = action;
+  }
+  const selectorUsed = toNonEmptyString(record.selectorUsed);
+  if (selectorUsed) {
+    details.selectorUsed = selectorUsed;
+  }
+  if (typeof record.status === "number" && Number.isFinite(record.status)) {
+    details.status = record.status;
+  }
+  const failure = asRecord(record.failure);
+  if (failure) {
+    const failureCode = toNonEmptyString(failure.code);
+    const classificationSource = toNonEmptyString(
+      failure.classificationSource
+    );
+    const failureDetails = asRecord(failure.details);
+    if (failureCode || classificationSource || failureDetails) {
+      details.actionFailure = {
+        ...failureCode ? { code: failureCode } : {},
+        ...classificationSource ? { classificationSource } : {},
+        ...failureDetails ? { details: failureDetails } : {}
+      };
+    }
+  }
+  return Object.keys(details).length ? details : void 0;
+}
+function extractCause(error) {
+  if (error instanceof Error) {
+    return error.cause;
+  }
+  const record = asRecord(error);
+  return record?.cause;
+}
+function asRecord(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  return value;
+}
+function toNonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
+function toJsonSafeRecord(value) {
+  if (!value) return void 0;
+  const sanitized = toJsonSafeValue(value, /* @__PURE__ */ new WeakSet());
+  if (!sanitized || typeof sanitized !== "object" || Array.isArray(sanitized)) {
+    return void 0;
+  }
+  const record = sanitized;
+  return Object.keys(record).length > 0 ? record : void 0;
+}
+function toJsonSafeValue(value, seen) {
+  if (value === null) return null;
+  if (typeof value === "string" || typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "number") {
+    return Number.isFinite(value) ? value : null;
+  }
+  if (typeof value === "bigint") {
+    return value.toString();
+  }
+  if (value === void 0 || typeof value === "function" || typeof value === "symbol") {
+    return void 0;
+  }
+  if (value instanceof Date) {
+    return Number.isNaN(value.getTime()) ? null : value.toISOString();
+  }
+  if (Array.isArray(value)) {
+    if (seen.has(value)) return "[Circular]";
+    seen.add(value);
+    const output = value.map((item) => {
+      const next = toJsonSafeValue(item, seen);
+      return next === void 0 ? null : next;
+    });
+    seen.delete(value);
+    return output;
+  }
+  if (value instanceof Set) {
+    if (seen.has(value)) return "[Circular]";
+    seen.add(value);
+    const output = Array.from(value, (item) => {
+      const next = toJsonSafeValue(item, seen);
+      return next === void 0 ? null : next;
+    });
+    seen.delete(value);
+    return output;
+  }
+  if (value instanceof Map) {
+    if (seen.has(value)) return "[Circular]";
+    seen.add(value);
+    const output = {};
+    for (const [key, item] of value.entries()) {
+      const normalizedKey = String(key);
+      const next = toJsonSafeValue(item, seen);
+      if (next !== void 0) {
+        output[normalizedKey] = next;
+      }
+    }
+    seen.delete(value);
+    return output;
+  }
+  if (typeof value === "object") {
+    const objectValue = value;
+    if (seen.has(objectValue)) return "[Circular]";
+    seen.add(objectValue);
+    const output = {};
+    for (const [key, item] of Object.entries(objectValue)) {
+      const next = toJsonSafeValue(item, seen);
+      if (next !== void 0) {
+        output[key] = next;
+      }
+    }
+    seen.delete(objectValue);
+    return output;
+  }
+  return void 0;
+}
+
+// src/storage/namespace.ts
+import path from "path";
+var DEFAULT_NAMESPACE = "default";
+function normalizeNamespace(input) {
+  const raw = String(input || "").trim().replace(/\\/g, "/");
+  if (!raw) return DEFAULT_NAMESPACE;
+  const segments = raw.split("/").map((segment) => sanitizeNamespaceSegment(segment)).filter((segment) => Boolean(segment));
+  if (!segments.length) return DEFAULT_NAMESPACE;
+  return segments.join("/");
+}
+function resolveNamespaceDir(rootDir, namespace) {
+  const selectorsRoot = path.resolve(rootDir, ".opensteer", "selectors");
+  const normalizedNamespace = normalizeNamespace(namespace);
+  const namespaceDir = path.resolve(selectorsRoot, normalizedNamespace);
+  const relative = path.relative(selectorsRoot, namespaceDir);
+  if (relative === "" || relative === ".") return namespaceDir;
+  if (relative.startsWith("..") || path.isAbsolute(relative)) {
+    throw new Error(
+      `Namespace "${namespace}" resolves outside selectors root.`
+    );
+  }
+  return namespaceDir;
+}
+function sanitizeNamespaceSegment(segment) {
+  const trimmed = String(segment || "").trim();
+  if (!trimmed || trimmed === "." || trimmed === "..") return "";
+  const replaced = trimmed.replace(/[^a-zA-Z0-9_-]+/g, "_");
+  const collapsed = replaced.replace(/_+/g, "_");
+  const bounded = collapsed.replace(/^_+|_+$/g, "");
+  return bounded || "";
+}
+
+// src/config.ts
+import fs from "fs";
+import path2 from "path";
+import { fileURLToPath } from "url";
+import { parse as parseDotenv } from "dotenv";
+var DEFAULT_CONFIG = {
+  browser: {
+    headless: false,
+    executablePath: void 0,
+    slowMo: 0,
+    connectUrl: void 0,
+    channel: void 0,
+    profileDir: void 0
+  },
+  storage: {
+    rootDir: process.cwd()
+  },
+  cursor: {
+    enabled: false,
+    profile: "snappy"
+  },
+  model: "gpt-5.1",
+  debug: false
+};
+function dotenvFileOrder(nodeEnv) {
+  const normalized = nodeEnv?.trim() || "";
+  const files = [];
+  if (normalized) {
+    files.push(`.env.${normalized}.local`);
+  }
+  if (normalized !== "test") {
+    files.push(".env.local");
+  }
+  if (normalized) {
+    files.push(`.env.${normalized}`);
+  }
+  files.push(".env");
+  return files;
+}
+function loadDotenvValues(rootDir, baseEnv, options = {}) {
+  const values = {};
+  if (parseBool(baseEnv.OPENSTEER_DISABLE_DOTENV_AUTOLOAD) === true) {
+    return values;
+  }
+  const debug = options.debug ?? parseBool(baseEnv.OPENSTEER_DEBUG) === true;
+  const baseDir = path2.resolve(rootDir);
+  const nodeEnv = baseEnv.NODE_ENV?.trim() || "";
+  for (const filename of dotenvFileOrder(nodeEnv)) {
+    const filePath = path2.join(baseDir, filename);
+    if (!fs.existsSync(filePath)) continue;
+    try {
+      const raw = fs.readFileSync(filePath, "utf8");
+      const parsed = parseDotenv(raw);
+      for (const [key, value] of Object.entries(parsed)) {
+        if (values[key] === void 0) {
+          values[key] = value;
+        }
+      }
+    } catch (error) {
+      const message = extractErrorMessage(
+        error,
+        "Unable to read or parse dotenv file."
+      );
+      if (debug) {
+        console.warn(
+          `[opensteer] failed to load dotenv file "${filePath}": ${message}`
+        );
+      }
+      continue;
+    }
+  }
+  return values;
+}
+function resolveEnv(rootDir, options = {}) {
+  const baseEnv = options.baseEnv ?? process.env;
+  const dotenvValues = loadDotenvValues(rootDir, baseEnv, options);
+  return {
+    ...dotenvValues,
+    ...baseEnv
+  };
+}
+function hasOwn(config, key) {
+  if (!config || typeof config !== "object") return false;
+  return Object.prototype.hasOwnProperty.call(config, key);
+}
+function hasLegacyAiConfig(config) {
+  return hasOwn(config, "ai");
+}
+function assertNoLegacyAiConfig(source, config) {
+  if (hasLegacyAiConfig(config)) {
+    throw new Error(
+      `Legacy "ai" config is no longer supported in ${source}. Use top-level "model" instead.`
+    );
+  }
+}
+function assertNoLegacyRuntimeConfig(source, config) {
+  if (!config || typeof config !== "object") return;
+  const configRecord = config;
+  if (hasOwn(configRecord, "runtime")) {
+    throw new Error(
+      `Legacy "runtime" config is no longer supported in ${source}. Use top-level "cloud" instead.`
+    );
+  }
+  if (hasOwn(configRecord, "mode")) {
+    throw new Error(
+      `Top-level "mode" config is no longer supported in ${source}. Use "cloud: true" to enable cloud mode.`
+    );
+  }
+  if (hasOwn(configRecord, "remote")) {
+    throw new Error(
+      `Top-level "remote" config is no longer supported in ${source}. Use "cloud" options instead.`
+    );
+  }
+  if (hasOwn(configRecord, "apiKey")) {
+    throw new Error(
+      `Top-level "apiKey" config is not supported in ${source}. Use "cloud.apiKey" instead.`
+    );
+  }
+}
+function loadConfigFile(rootDir, options = {}) {
+  const configPath = path2.join(rootDir, ".opensteer", "config.json");
+  if (!fs.existsSync(configPath)) return {};
+  try {
+    const raw = fs.readFileSync(configPath, "utf8");
+    return JSON.parse(raw);
+  } catch (error) {
+    const message = extractErrorMessage(
+      error,
+      "Unable to read or parse config file."
+    );
+    if (options.debug) {
+      console.warn(
+        `[opensteer] failed to load config file "${configPath}": ${message}`
+      );
+    }
+    return {};
+  }
+}
+function mergeDeep(base, patch) {
+  const out = {
+    ...base
+  };
+  for (const [key, value] of Object.entries(patch || {})) {
+    const currentValue = out[key];
+    if (value && typeof value === "object" && !Array.isArray(value) && currentValue && typeof currentValue === "object" && !Array.isArray(currentValue)) {
+      out[key] = mergeDeep(
+        currentValue,
+        value
+      );
+      continue;
+    }
+    if (value !== void 0) {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+function parseBool(value) {
+  if (value == null) return void 0;
+  const normalized = value.trim().toLowerCase();
+  if (normalized === "true" || normalized === "1") return true;
+  if (normalized === "false" || normalized === "0") return false;
+  return void 0;
+}
+function parseNumber(value) {
+  if (value == null || value.trim() === "") return void 0;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return void 0;
+  return parsed;
+}
+function parseRuntimeMode(value, source) {
+  if (value == null) return void 0;
+  if (typeof value !== "string") {
+    throw new Error(
+      `Invalid ${source} value "${String(value)}". Use "local" or "cloud".`
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return void 0;
+  if (normalized === "local" || normalized === "cloud") {
+    return normalized;
+  }
+  throw new Error(
+    `Invalid ${source} value "${value}". Use "local" or "cloud".`
+  );
+}
+function parseAuthScheme(value, source) {
+  if (value == null) return void 0;
+  if (typeof value !== "string") {
+    throw new Error(
+      `Invalid ${source} value "${String(value)}". Use "api-key" or "bearer".`
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return void 0;
+  if (normalized === "api-key" || normalized === "bearer") {
+    return normalized;
+  }
+  throw new Error(
+    `Invalid ${source} value "${value}". Use "api-key" or "bearer".`
+  );
+}
+function parseCloudAnnounce(value, source) {
+  if (value == null) return void 0;
+  if (typeof value !== "string") {
+    throw new Error(
+      `Invalid ${source} value "${String(value)}". Use "always", "off", or "tty".`
+    );
+  }
+  const normalized = value.trim().toLowerCase();
+  if (!normalized) return void 0;
+  if (normalized === "always" || normalized === "off" || normalized === "tty") {
+    return normalized;
+  }
+  throw new Error(
+    `Invalid ${source} value "${value}". Use "always", "off", or "tty".`
+  );
+}
+function resolveOpensteerApiKey(env) {
+  const value = env.OPENSTEER_API_KEY?.trim();
+  if (!value) return void 0;
+  return value;
+}
+function resolveOpensteerAccessToken(env) {
+  const value = env.OPENSTEER_ACCESS_TOKEN?.trim();
+  if (!value) return void 0;
+  return value;
+}
+function resolveOpensteerBaseUrl(env) {
+  const value = env.OPENSTEER_BASE_URL?.trim();
+  if (!value) return void 0;
+  return value;
+}
+function resolveOpensteerAuthScheme(env) {
+  return parseAuthScheme(env.OPENSTEER_AUTH_SCHEME, "OPENSTEER_AUTH_SCHEME");
+}
+function resolveOpensteerCloudProfileId(env) {
+  const value = env.OPENSTEER_CLOUD_PROFILE_ID?.trim();
+  if (!value) return void 0;
+  return value;
+}
+function resolveOpensteerCloudProfileReuseIfActive(env) {
+  return parseBool(env.OPENSTEER_CLOUD_PROFILE_REUSE_IF_ACTIVE);
+}
+function parseCloudBrowserProfileReuseIfActive(value) {
+  if (value == null) return void 0;
+  if (typeof value !== "boolean") {
+    throw new Error(
+      `Invalid cloud.browserProfile.reuseIfActive value "${String(
+        value
+      )}". Use true or false.`
+    );
+  }
+  return value;
+}
+function normalizeCloudBrowserProfileOptions(value, source) {
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new Error(
+      `Invalid ${source} value "${String(value)}". Use an object with profileId and optional reuseIfActive.`
+    );
+  }
+  const record = value;
+  const rawProfileId = record.profileId;
+  if (typeof rawProfileId !== "string" || !rawProfileId.trim()) {
+    throw new Error(
+      `${source}.profileId must be a non-empty string when browserProfile is provided.`
+    );
+  }
+  return {
+    profileId: rawProfileId.trim(),
+    reuseIfActive: parseCloudBrowserProfileReuseIfActive(record.reuseIfActive)
+  };
+}
+function resolveEnvCloudBrowserProfile(profileId, reuseIfActive) {
+  if (reuseIfActive !== void 0 && !profileId) {
+    throw new Error(
+      "OPENSTEER_CLOUD_PROFILE_REUSE_IF_ACTIVE requires OPENSTEER_CLOUD_PROFILE_ID."
+    );
+  }
+  if (!profileId) {
+    return void 0;
+  }
+  return {
+    profileId,
+    reuseIfActive
+  };
+}
+function normalizeCloudOptions(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return void 0;
+  }
+  return value;
+}
+function normalizeNonEmptyString(value) {
+  if (typeof value !== "string") return void 0;
+  const normalized = value.trim();
+  return normalized.length ? normalized : void 0;
+}
+function parseCloudEnabled(value, source) {
+  if (value == null) return void 0;
+  if (typeof value === "boolean") return value;
+  if (typeof value === "object" && !Array.isArray(value)) return true;
+  throw new Error(
+    `Invalid ${source} value "${String(value)}". Use true, false, or a cloud options object.`
+  );
+}
+function resolveCloudSelection(config, env = process.env) {
+  const configCloud = parseCloudEnabled(config.cloud, "cloud");
+  if (configCloud !== void 0) {
+    return {
+      cloud: configCloud,
+      source: "config.cloud"
+    };
+  }
+  const envMode = parseRuntimeMode(env.OPENSTEER_MODE, "OPENSTEER_MODE");
+  if (envMode) {
+    return {
+      cloud: envMode === "cloud",
+      source: "env.OPENSTEER_MODE"
+    };
+  }
+  return {
+    cloud: false,
+    source: "default"
+  };
+}
+function resolveConfigWithEnv(input = {}, options = {}) {
+  const processEnv = options.env ?? process.env;
+  const debugHint = typeof input.debug === "boolean" ? input.debug : parseBool(processEnv.OPENSTEER_DEBUG) === true;
+  const initialRootDir = input.storage?.rootDir ?? process.cwd();
+  const runtimeDefaults = mergeDeep(DEFAULT_CONFIG, {
+    storage: {
+      rootDir: initialRootDir
+    }
+  });
+  assertNoLegacyAiConfig("Opensteer constructor config", input);
+  assertNoLegacyRuntimeConfig("Opensteer constructor config", input);
+  const fileConfig = loadConfigFile(initialRootDir, {
+    debug: debugHint
+  });
+  assertNoLegacyAiConfig(".opensteer/config.json", fileConfig);
+  assertNoLegacyRuntimeConfig(".opensteer/config.json", fileConfig);
+  const fileRootDir = typeof fileConfig.storage?.rootDir === "string" ? fileConfig.storage.rootDir : void 0;
+  const envRootDir = input.storage?.rootDir ?? fileRootDir ?? initialRootDir;
+  const env = resolveEnv(envRootDir, {
+    debug: debugHint,
+    baseEnv: processEnv
+  });
+  if (env.OPENSTEER_AI_MODEL) {
+    throw new Error(
+      "OPENSTEER_AI_MODEL is no longer supported. Use OPENSTEER_MODEL instead."
+    );
+  }
+  if (env.OPENSTEER_RUNTIME != null) {
+    throw new Error(
+      "OPENSTEER_RUNTIME is no longer supported. Use OPENSTEER_MODE instead."
+    );
+  }
+  const envConfig = {
+    browser: {
+      headless: parseBool(env.OPENSTEER_HEADLESS),
+      executablePath: env.OPENSTEER_BROWSER_PATH || void 0,
+      slowMo: parseNumber(env.OPENSTEER_SLOW_MO),
+      connectUrl: env.OPENSTEER_CONNECT_URL || void 0,
+      channel: env.OPENSTEER_CHANNEL || void 0,
+      profileDir: env.OPENSTEER_PROFILE_DIR || void 0
+    },
+    cursor: {
+      enabled: parseBool(env.OPENSTEER_CURSOR)
+    },
+    model: env.OPENSTEER_MODEL || void 0,
+    debug: parseBool(env.OPENSTEER_DEBUG)
+  };
+  const mergedWithFile = mergeDeep(runtimeDefaults, fileConfig);
+  const mergedWithEnv = mergeDeep(mergedWithFile, envConfig);
+  const resolved = mergeDeep(mergedWithEnv, input);
+  const envApiKey = resolveOpensteerApiKey(env);
+  const envAccessTokenRaw = resolveOpensteerAccessToken(env);
+  const envBaseUrl = resolveOpensteerBaseUrl(env);
+  const envAuthScheme = resolveOpensteerAuthScheme(env);
+  if (envApiKey && envAccessTokenRaw) {
+    throw new Error(
+      "OPENSTEER_API_KEY and OPENSTEER_ACCESS_TOKEN are mutually exclusive. Set only one."
+    );
+  }
+  const envAccessToken = envAccessTokenRaw || (envAuthScheme === "bearer" ? envApiKey : void 0);
+  const envApiCredential = envAuthScheme === "bearer" && !envAccessTokenRaw ? void 0 : envApiKey;
+  const envCloudProfileId = resolveOpensteerCloudProfileId(env);
+  const envCloudProfileReuseIfActive = resolveOpensteerCloudProfileReuseIfActive(env);
+  const envCloudAnnounce = parseCloudAnnounce(
+    env.OPENSTEER_REMOTE_ANNOUNCE,
+    "OPENSTEER_REMOTE_ANNOUNCE"
+  );
+  const inputCloudOptions = normalizeCloudOptions(input.cloud);
+  const inputCloudBrowserProfile = normalizeCloudBrowserProfileOptions(
+    inputCloudOptions?.browserProfile,
+    "cloud.browserProfile"
+  );
+  const inputAuthScheme = parseAuthScheme(
+    inputCloudOptions?.authScheme,
+    "cloud.authScheme"
+  );
+  const inputCloudAnnounce = parseCloudAnnounce(
+    inputCloudOptions?.announce,
+    "cloud.announce"
+  );
+  const inputHasCloudApiKey = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "apiKey")
+  );
+  const inputHasCloudAccessToken = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "accessToken")
+  );
+  const inputHasCloudBaseUrl = Boolean(
+    inputCloudOptions && Object.prototype.hasOwnProperty.call(inputCloudOptions, "baseUrl")
+  );
+  if (normalizeNonEmptyString(inputCloudOptions?.apiKey) && normalizeNonEmptyString(inputCloudOptions?.accessToken)) {
+    throw new Error(
+      "cloud.apiKey and cloud.accessToken are mutually exclusive. Set only one."
+    );
+  }
+  const cloudSelection = resolveCloudSelection({
+    cloud: resolved.cloud
+  }, env);
+  if (cloudSelection.cloud) {
+    const resolvedCloud = normalizeCloudOptions(resolved.cloud) ?? {};
+    const {
+      apiKey: resolvedCloudApiKeyRaw,
+      accessToken: resolvedCloudAccessTokenRaw,
+      ...resolvedCloudRest
+    } = resolvedCloud;
+    if (normalizeNonEmptyString(resolvedCloudApiKeyRaw) && normalizeNonEmptyString(resolvedCloudAccessTokenRaw)) {
+      throw new Error(
+        "Cloud config cannot include both apiKey and accessToken at the same time."
+      );
+    }
+    const resolvedCloudBrowserProfile = normalizeCloudBrowserProfileOptions(
+      resolvedCloud.browserProfile,
+      "resolved.cloud.browserProfile"
+    );
+    const envCloudBrowserProfile = resolveEnvCloudBrowserProfile(
+      envCloudProfileId,
+      envCloudProfileReuseIfActive
+    );
+    const browserProfile = inputCloudBrowserProfile ?? envCloudBrowserProfile ?? resolvedCloudBrowserProfile;
+    let authScheme = inputAuthScheme ?? envAuthScheme ?? parseAuthScheme(resolvedCloud.authScheme, "cloud.authScheme") ?? "api-key";
+    const announce = inputCloudAnnounce ?? envCloudAnnounce ?? parseCloudAnnounce(resolvedCloud.announce, "cloud.announce") ?? "always";
+    const credentialOverriddenByInput = inputHasCloudApiKey || inputHasCloudAccessToken;
+    let apiKey = normalizeNonEmptyString(resolvedCloudApiKeyRaw);
+    let accessToken = normalizeNonEmptyString(resolvedCloudAccessTokenRaw);
+    if (!credentialOverriddenByInput) {
+      if (envAccessToken) {
+        accessToken = envAccessToken;
+        apiKey = void 0;
+      } else if (envApiCredential) {
+        apiKey = envApiCredential;
+        accessToken = void 0;
+      }
+    }
+    if (accessToken) {
+      authScheme = "bearer";
+    }
+    resolved.cloud = {
+      ...resolvedCloudRest,
+      ...inputHasCloudApiKey ? { apiKey: resolvedCloudApiKeyRaw } : apiKey ? { apiKey } : {},
+      ...inputHasCloudAccessToken ? { accessToken: resolvedCloudAccessTokenRaw } : accessToken ? { accessToken } : {},
+      authScheme,
+      announce,
+      ...browserProfile ? { browserProfile } : {}
+    };
+  }
+  if (envBaseUrl && cloudSelection.cloud && !inputHasCloudBaseUrl) {
+    resolved.cloud = {
+      ...normalizeCloudOptions(resolved.cloud) ?? {},
+      baseUrl: envBaseUrl
+    };
+  }
+  return {
+    config: resolved,
+    env
+  };
+}
+function resolveNamespace(config, rootDir) {
+  if (config.name && config.name.trim()) {
+    return normalizeNamespace(config.name);
+  }
+  const caller = getCallerFilePath();
+  if (!caller) return normalizeNamespace("default");
+  const relative = path2.relative(rootDir, caller);
+  const cleaned = relative.replace(/\\/g, "/").replace(/\.(ts|tsx|js|mjs|cjs)$/, "");
+  return normalizeNamespace(cleaned || "default");
+}
+function getCallerFilePath() {
+  const stack = new Error().stack;
+  if (!stack) return null;
+  const lines = stack.split("\n").slice(2);
+  for (const line of lines) {
+    const match = line.match(/\((.*):(\d+):(\d+)\)/) || line.match(/at\s+(.*):(\d+):(\d+)/);
+    if (!match) continue;
+    const rawPath = match[1];
+    if (!rawPath) continue;
+    if (rawPath.includes("node:internal")) continue;
+    if (rawPath.includes("node_modules")) continue;
+    if (rawPath.includes("/opensteer-oss/src/")) continue;
+    try {
+      if (rawPath.startsWith("file://")) {
+        return fileURLToPath(rawPath);
+      }
+      return rawPath;
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+// src/cloud/errors.ts
+var OpensteerCloudError = class extends Error {
+  code;
+  status;
+  details;
+  constructor(code, message, status, details) {
+    super(message);
+    this.name = "OpensteerCloudError";
+    this.code = code;
+    this.status = status;
+    this.details = details;
+  }
+};
+function cloudUnsupportedMethodError(method, message) {
+  return new OpensteerCloudError(
+    "CLOUD_UNSUPPORTED_METHOD",
+    message || `${method} is not supported in cloud mode.`
+  );
+}
+function cloudNotLaunchedError() {
+  return new OpensteerCloudError(
+    "CLOUD_SESSION_NOT_FOUND",
+    "Cloud session is not connected. Call launch() first."
+  );
+}
+
+// src/cloud/cdp-client.ts
+import {
+  chromium
+} from "playwright";
+var CloudCdpClient = class {
+  async connect(args) {
+    const endpoint = withTokenQuery(args.wsUrl, args.token);
+    let browser;
+    try {
+      browser = await chromium.connectOverCDP(endpoint);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Failed to connect to cloud CDP endpoint.";
+      throw new OpensteerCloudError("CLOUD_TRANSPORT_ERROR", message);
+    }
+    const contexts = browser.contexts();
+    const context = contexts[0];
+    if (!context) {
+      await browser.close();
+      throw new OpensteerCloudError(
+        "CLOUD_INTERNAL",
+        "Cloud browser returned no context."
+      );
+    }
+    const preferred = selectPreferredContextPage(browser, contexts);
+    if (preferred) {
+      return preferred;
+    }
+    const page = context.pages()[0] || await context.newPage();
+    return { browser, context, page };
+  }
+};
+function selectPreferredContextPage(browser, contexts) {
+  let aboutBlankCandidate = null;
+  for (const context of contexts) {
+    for (const page of context.pages()) {
+      const url = safePageUrl(page);
+      if (!isInternalOrEmptyUrl(url)) {
+        return { browser, context, page };
+      }
+      if (!aboutBlankCandidate && url === "about:blank") {
+        aboutBlankCandidate = { browser, context, page };
+      }
+    }
+  }
+  return aboutBlankCandidate;
+}
+function safePageUrl(page) {
+  try {
+    return page.url();
+  } catch {
+    return "";
+  }
+}
+function isInternalOrEmptyUrl(url) {
+  if (!url) return true;
+  if (url === "about:blank") return true;
+  return url.startsWith("chrome://") || url.startsWith("devtools://") || url.startsWith("edge://");
+}
+function withTokenQuery(wsUrl, token) {
+  const url = new URL(wsUrl);
+  url.searchParams.set("token", token);
+  return url.toString();
+}
+
+// src/utils/strip-trailing-slashes.ts
+function stripTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end -= 1;
+  }
+  return end === value.length ? value : value.slice(0, end);
+}
+
+// src/cloud/http-client.ts
+function normalizeCloudBaseUrl(baseUrl) {
+  return stripTrailingSlashes(baseUrl);
+}
+function cloudAuthHeaders(key, authScheme) {
+  if (authScheme === "bearer") {
+    return {
+      authorization: `Bearer ${key}`
+    };
+  }
+  return {
+    "x-api-key": key
+  };
+}
+async function parseCloudHttpError(response) {
+  let body = null;
+  try {
+    body = await response.json();
+  } catch {
+    body = null;
+  }
+  const code = typeof body?.code === "string" ? toCloudErrorCode(body.code) : "CLOUD_TRANSPORT_ERROR";
+  const message = typeof body?.error === "string" ? body.error : `Cloud request failed with status ${response.status}.`;
+  return new OpensteerCloudError(code, message, response.status, body?.details);
+}
+function toCloudErrorCode(code) {
+  if (code === "CLOUD_AUTH_FAILED" || code === "CLOUD_SESSION_NOT_FOUND" || code === "CLOUD_SESSION_CLOSED" || code === "CLOUD_UNSUPPORTED_METHOD" || code === "CLOUD_INVALID_REQUEST" || code === "CLOUD_MODEL_NOT_ALLOWED" || code === "CLOUD_ACTION_FAILED" || code === "CLOUD_INTERNAL" || code === "CLOUD_CAPACITY_EXHAUSTED" || code === "CLOUD_RUNTIME_UNAVAILABLE" || code === "CLOUD_RUNTIME_MISMATCH" || code === "CLOUD_SESSION_STALE" || code === "CLOUD_CONTRACT_MISMATCH" || code === "CLOUD_CONTROL_PLANE_ERROR" || code === "CLOUD_PROXY_UNAVAILABLE" || code === "CLOUD_PROXY_REQUIRED" || code === "CLOUD_BILLING_LIMIT_REACHED" || code === "CLOUD_RATE_LIMITED" || code === "CLOUD_BROWSER_PROFILE_NOT_FOUND" || code === "CLOUD_BROWSER_PROFILE_BUSY" || code === "CLOUD_BROWSER_PROFILE_DISABLED" || code === "CLOUD_BROWSER_PROFILE_PROXY_UNAVAILABLE" || code === "CLOUD_BROWSER_PROFILE_SYNC_FAILED") {
+    return code;
+  }
+  return "CLOUD_TRANSPORT_ERROR";
+}
+
+// src/cloud/session-client.ts
+var CACHE_IMPORT_BATCH_SIZE = 200;
+var CloudSessionClient = class {
+  baseUrl;
+  key;
+  authScheme;
+  constructor(baseUrl, key, authScheme = "api-key") {
+    this.baseUrl = normalizeCloudBaseUrl(baseUrl);
+    this.key = key;
+    this.authScheme = authScheme;
+  }
+  async create(request) {
+    const response = await fetch(`${this.baseUrl}/sessions`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...cloudAuthHeaders(this.key, this.authScheme)
+      },
+      body: JSON.stringify(request)
+    });
+    if (!response.ok) {
+      throw await parseCloudHttpError(response);
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch {
+      throw new OpensteerCloudError(
+        "CLOUD_CONTRACT_MISMATCH",
+        "Invalid cloud session create response: expected a JSON object.",
+        response.status
+      );
+    }
+    return parseCreateResponse(body, response.status);
+  }
+  async close(sessionId) {
+    const response = await fetch(`${this.baseUrl}/sessions/${sessionId}`, {
+      method: "DELETE",
+      headers: {
+        ...cloudAuthHeaders(this.key, this.authScheme)
+      }
+    });
+    if (response.status === 204) {
+      return;
+    }
+    if (!response.ok) {
+      throw await parseCloudHttpError(response);
+    }
+  }
+  async importSelectorCache(request) {
+    if (!request.entries.length) {
+      return zeroImportResponse();
+    }
+    let totals = zeroImportResponse();
+    for (let offset = 0; offset < request.entries.length; offset += CACHE_IMPORT_BATCH_SIZE) {
+      const batch = request.entries.slice(
+        offset,
+        offset + CACHE_IMPORT_BATCH_SIZE
+      );
+      const response = await this.importSelectorCacheBatch(batch);
+      totals = mergeImportResponse(totals, response);
+    }
+    return totals;
+  }
+  async importSelectorCacheBatch(entries) {
+    const response = await fetch(`${this.baseUrl}/selector-cache/import`, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...cloudAuthHeaders(this.key, this.authScheme)
+      },
+      body: JSON.stringify({ entries })
+    });
+    if (!response.ok) {
+      throw await parseCloudHttpError(response);
+    }
+    return await response.json();
+  }
+};
+function parseCreateResponse(body, status) {
+  const root = requireObject(
+    body,
+    "Invalid cloud session create response: expected a JSON object.",
+    status
+  );
+  const sessionId = requireString(root, "sessionId", status);
+  const actionWsUrl = requireString(root, "actionWsUrl", status);
+  const cdpWsUrl = requireString(root, "cdpWsUrl", status);
+  const actionToken = requireString(root, "actionToken", status);
+  const cdpToken = requireString(root, "cdpToken", status);
+  const cloudSessionUrl = requireString(root, "cloudSessionUrl", status);
+  const cloudSessionRoot = requireObject(
+    root.cloudSession,
+    "Invalid cloud session create response: cloudSession must be an object.",
+    status
+  );
+  const cloudSession = {
+    sessionId: requireString(cloudSessionRoot, "sessionId", status, "cloudSession"),
+    workspaceId: requireString(
+      cloudSessionRoot,
+      "workspaceId",
+      status,
+      "cloudSession"
+    ),
+    state: requireString(cloudSessionRoot, "state", status, "cloudSession"),
+    createdAt: requireNumber(cloudSessionRoot, "createdAt", status, "cloudSession"),
+    sourceType: requireSourceType(cloudSessionRoot, "sourceType", status, "cloudSession"),
+    sourceRef: optionalString(cloudSessionRoot, "sourceRef", status, "cloudSession"),
+    label: optionalString(cloudSessionRoot, "label", status, "cloudSession")
+  };
+  const expiresAt = optionalNumber(root, "expiresAt", status);
+  return {
+    sessionId,
+    actionWsUrl,
+    cdpWsUrl,
+    actionToken,
+    cdpToken,
+    expiresAt,
+    cloudSessionUrl,
+    cloudSession
+  };
+}
+function requireObject(value, message, status) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new OpensteerCloudError("CLOUD_CONTRACT_MISMATCH", message, status);
+  }
+  return value;
+}
+function requireString(source, field, status, parent) {
+  const value = source[field];
+  if (typeof value !== "string" || !value.trim()) {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a non-empty string.`,
+      status
+    );
+  }
+  return value;
+}
+function requireNumber(source, field, status, parent) {
+  const value = source[field];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a finite number.`,
+      status
+    );
+  }
+  return value;
+}
+function optionalString(source, field, status, parent) {
+  const value = source[field];
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value !== "string") {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a string when present.`,
+      status
+    );
+  }
+  return value;
+}
+function optionalNumber(source, field, status, parent) {
+  const value = source[field];
+  if (value == null) {
+    return void 0;
+  }
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new OpensteerCloudError(
+      "CLOUD_CONTRACT_MISMATCH",
+      `Invalid cloud session create response: ${formatFieldPath(
+        field,
+        parent
+      )} must be a finite number when present.`,
+      status
+    );
+  }
+  return value;
+}
+function requireSourceType(source, field, status, parent) {
+  const value = source[field];
+  if (value === "agent-thread" || value === "agent-run" || value === "local-cloud" || value === "manual") {
+    return value;
+  }
+  throw new OpensteerCloudError(
+    "CLOUD_CONTRACT_MISMATCH",
+    `Invalid cloud session create response: ${formatFieldPath(
+      field,
+      parent
+    )} must be one of "agent-thread", "agent-run", "local-cloud", or "manual".`,
+    status
+  );
+}
+function formatFieldPath(field, parent) {
+  return parent ? `"${parent}.${field}"` : `"${field}"`;
+}
+function zeroImportResponse() {
+  return {
+    imported: 0,
+    inserted: 0,
+    updated: 0,
+    skipped: 0
+  };
+}
+function mergeImportResponse(first, second) {
+  return {
+    imported: first.imported + second.imported,
+    inserted: first.inserted + second.inserted,
+    updated: first.updated + second.updated,
+    skipped: first.skipped + second.skipped
+  };
+}
+
+// src/cloud/runtime.ts
+var DEFAULT_CLOUD_BASE_URL = "https://api.opensteer.com";
+function createCloudRuntimeState(key, baseUrl = resolveCloudBaseUrl(), authScheme = "api-key") {
+  const normalizedBaseUrl = normalizeCloudBaseUrl(baseUrl);
+  return {
+    sessionClient: new CloudSessionClient(
+      normalizedBaseUrl,
+      key,
+      authScheme
+    ),
+    cdpClient: new CloudCdpClient(),
+    baseUrl: normalizedBaseUrl,
+    actionClient: null,
+    sessionId: null,
+    localRunId: null,
+    cloudSessionUrl: null
+  };
+}
+function resolveCloudBaseUrl() {
+  const value = process.env.OPENSTEER_BASE_URL?.trim();
+  if (!value) return DEFAULT_CLOUD_BASE_URL;
+  return normalizeCloudBaseUrl(value);
+}
+function readCloudActionDescription(payload) {
+  const description = payload.description;
+  if (typeof description !== "string") return void 0;
+  const normalized = description.trim();
+  return normalized.length ? normalized : void 0;
+}
+
+// src/auth/keychain-store.ts
+import { spawnSync } from "child_process";
+function commandExists(command) {
+  const result = spawnSync(command, ["--help"], {
+    encoding: "utf8",
+    stdio: "ignore"
+  });
+  return result.error == null;
+}
+function commandFailed(result) {
+  return typeof result.status === "number" && result.status !== 0;
+}
+function sanitizeCommandArgs(command, args) {
+  if (command !== "security") {
+    return args;
+  }
+  const sanitized = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const value = args[index];
+    sanitized.push(value);
+    if (value === "-w" && index + 1 < args.length) {
+      sanitized.push("[REDACTED]");
+      index += 1;
+    }
+  }
+  return sanitized;
+}
+function buildCommandError(command, args, result) {
+  const stderr = typeof result.stderr === "string" && result.stderr.trim() ? result.stderr.trim() : `Command "${command}" failed with status ${String(result.status)}.`;
+  const sanitizedArgs = sanitizeCommandArgs(command, args);
+  return new Error(
+    [
+      `Unable to persist credential via ${command}.`,
+      `${command} ${sanitizedArgs.join(" ")}`,
+      stderr
+    ].join(" ")
+  );
+}
+function createMacosSecurityStore() {
+  return {
+    backend: "macos-security",
+    get(service, account) {
+      const result = spawnSync(
+        "security",
+        ["find-generic-password", "-s", service, "-a", account, "-w"],
+        { encoding: "utf8" }
+      );
+      if (commandFailed(result)) {
+        return null;
+      }
+      const secret = result.stdout.trim();
+      return secret.length ? secret : null;
+    },
+    set(service, account, secret) {
+      const args = [
+        "add-generic-password",
+        "-U",
+        "-s",
+        service,
+        "-a",
+        account,
+        "-w",
+        secret
+      ];
+      const result = spawnSync("security", args, { encoding: "utf8" });
+      if (commandFailed(result)) {
+        throw buildCommandError("security", args, result);
+      }
+    },
+    delete(service, account) {
+      const args = ["delete-generic-password", "-s", service, "-a", account];
+      const result = spawnSync("security", args, { encoding: "utf8" });
+      if (commandFailed(result)) {
+        return;
+      }
+    }
+  };
+}
+function createLinuxSecretToolStore() {
+  return {
+    backend: "linux-secret-tool",
+    get(service, account) {
+      const result = spawnSync(
+        "secret-tool",
+        ["lookup", "service", service, "account", account],
+        {
+          encoding: "utf8"
+        }
+      );
+      if (commandFailed(result)) {
+        return null;
+      }
+      const secret = result.stdout.trim();
+      return secret.length ? secret : null;
+    },
+    set(service, account, secret) {
+      const args = [
+        "store",
+        "--label",
+        "Opensteer CLI",
+        "service",
+        service,
+        "account",
+        account
+      ];
+      const result = spawnSync("secret-tool", args, {
+        encoding: "utf8",
+        input: secret
+      });
+      if (commandFailed(result)) {
+        throw buildCommandError("secret-tool", args, result);
+      }
+    },
+    delete(service, account) {
+      const args = ["clear", "service", service, "account", account];
+      spawnSync("secret-tool", args, {
+        encoding: "utf8"
+      });
+    }
+  };
+}
+function createKeychainStore() {
+  if (process.platform === "darwin") {
+    if (!commandExists("security")) {
+      return null;
+    }
+    return createMacosSecurityStore();
+  }
+  if (process.platform === "linux") {
+    if (!commandExists("secret-tool")) {
+      return null;
+    }
+    return createLinuxSecretToolStore();
+  }
+  return null;
+}
+
+export {
+  createKeychainStore,
+  extractErrorMessage,
+  normalizeError,
+  normalizeNamespace,
+  resolveNamespaceDir,
+  resolveCloudSelection,
+  resolveConfigWithEnv,
+  resolveNamespace,
+  OpensteerCloudError,
+  cloudUnsupportedMethodError,
+  cloudNotLaunchedError,
+  CloudCdpClient,
+  stripTrailingSlashes,
+  normalizeCloudBaseUrl,
+  cloudAuthHeaders,
+  parseCloudHttpError,
+  CloudSessionClient,
+  DEFAULT_CLOUD_BASE_URL,
+  createCloudRuntimeState,
+  readCloudActionDescription
+};