@mutagent/cli 0.1.379 → 0.1.381

package/dist/index.js

@@ -255,6 +255,164 @@ var init_known_secrets = __esm(() => {
   known = new Set;
 });
 
+// src/lib/config.ts
+import { cosmiconfigSync } from "cosmiconfig";
+import { z } from "zod";
+import { homedir } from "os";
+import { join } from "path";
+import { existsSync, readFileSync, mkdirSync } from "fs";
+function parseJsonSafe(content, schema) {
+  try {
+    const parsed = JSON.parse(content);
+    return schema.parse(parsed);
+  } catch {
+    return null;
+  }
+}
+function loadConfig() {
+  const explorer = cosmiconfigSync("mutagent");
+  const result = explorer.search();
+  const rcConfig = result?.config;
+  let credentials = null;
+  if (existsSync(CREDENTIALS_FILE)) {
+    credentials = parseJsonSafe(readFileSync(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
+  }
+  const envKey = process.env.MUTAGENT_API_KEY;
+  const fileDescribesKey = envKey === undefined || envKey === credentials?.apiKey;
+  const envWorkspace = process.env.MUTAGENT_WORKSPACE_ID?.trim() ?? "";
+  const fileSelection = fileDescribesKey ? credentials?.defaultWorkspace : undefined;
+  const selected = fileSelection ?? rcConfig?.defaultWorkspace;
+  const defaultWorkspace = envWorkspace !== "" ? envWorkspace : selected;
+  const merged = {
+    providers: {},
+    environment: "production",
+    ...rcConfig,
+    ...credentials,
+    apiKey: envKey ?? credentials?.apiKey ?? rcConfig?.apiKey,
+    endpoint: process.env.MUTAGENT_ENDPOINT ?? credentials?.endpoint ?? rcConfig?.endpoint,
+    defaultWorkspace,
+    workspaceOrigin: envWorkspace !== "" ? "override" : selected ? "selection" : undefined,
+    workspaceName: envWorkspace === "" && fileSelection !== undefined && fileSelection === selected ? credentials?.workspaceName : undefined,
+    defaultOrganization: fileDescribesKey ? credentials?.defaultOrganization ?? rcConfig?.defaultOrganization : undefined,
+    organizationName: fileDescribesKey ? credentials?.organizationName : undefined,
+    organizationSlug: fileDescribesKey ? credentials?.organizationSlug : undefined,
+    keyScope: fileDescribesKey ? credentials?.keyScope : undefined
+  };
+  return configSchema.parse(merged);
+}
+function readCredentialsFile() {
+  if (!existsSync(CREDENTIALS_FILE))
+    return {};
+  try {
+    return JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8"));
+  } catch {
+    return {};
+  }
+}
+function updateCredentials(patch) {
+  if (!existsSync(CREDENTIALS_DIR)) {
+    mkdirSync(CREDENTIALS_DIR, { recursive: true });
+  }
+  const updated = Object.fromEntries(Object.entries({ ...readCredentialsFile(), ...patch }).filter(([key, value]) => value !== undefined && key !== "defaultWorkspaceSource"));
+  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
+}
+function saveCredentials(apiKey, endpoint) {
+  if (!existsSync(CREDENTIALS_DIR)) {
+    mkdirSync(CREDENTIALS_DIR, { recursive: true });
+  }
+  const config = loadConfig();
+  const credentials = {
+    apiKey,
+    endpoint: endpoint ?? config.endpoint
+  };
+  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
+}
+function saveFullCredentials(creds) {
+  const existing = readCredentialsFile();
+  updateCredentials({
+    apiKey: creds.apiKey,
+    endpoint: creds.endpoint ?? existing.endpoint ?? "https://api.mutagent.io",
+    defaultWorkspace: creds.workspaceId,
+    workspaceName: creds.workspaceName,
+    defaultOrganization: creds.organizationId,
+    organizationName: creds.organizationName,
+    organizationSlug: creds.organizationSlug,
+    keyScope: creds.keyScope,
+    expiresAt: creds.expiresAt
+  });
+}
+function clearCredentials() {
+  if (existsSync(CREDENTIALS_FILE)) {
+    writeSecureFile(CREDENTIALS_FILE, JSON.stringify({}));
+  }
+}
+function hasCredentials() {
+  if (process.env.MUTAGENT_API_KEY)
+    return true;
+  if (!existsSync(CREDENTIALS_FILE))
+    return false;
+  const credentials = parseJsonSafe(readFileSync(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
+  return credentials?.apiKey !== undefined && credentials.apiKey !== "";
+}
+function envKeyReplacesFile() {
+  const envKey = process.env.MUTAGENT_API_KEY;
+  if (envKey === undefined)
+    return false;
+  if (!existsSync(CREDENTIALS_FILE))
+    return true;
+  const credentials = parseJsonSafe(readFileSync(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
+  return envKey !== credentials?.apiKey;
+}
+function getApiKey() {
+  const apiKey = process.env.MUTAGENT_API_KEY ?? loadConfig().apiKey;
+  registerSecret(apiKey);
+  return apiKey;
+}
+function setWorkspaceSelection(workspaceId, workspaceName) {
+  updateCredentials({ defaultWorkspace: workspaceId, workspaceName });
+}
+function recordKeyScope(self) {
+  updateCredentials({
+    keyScope: self.scope,
+    defaultOrganization: self.organization?.id,
+    organizationName: self.organization?.name,
+    organizationSlug: self.organization?.slug,
+    ...self.scope === "workspace" && self.workspace ? { defaultWorkspace: self.workspace.id, workspaceName: self.workspace.name } : {}
+  });
+}
+var keyScopeSchema, configSchema, credentialsSchema, CREDENTIALS_DIR, CREDENTIALS_FILE;
+var init_config = __esm(() => {
+  init_secure_file();
+  init_known_secrets();
+  keyScopeSchema = z.enum(["organization", "workspace", "user"]);
+  configSchema = z.object({
+    apiKey: z.string().optional(),
+    endpoint: z.string().default("https://api.mutagent.io"),
+    format: z.enum(["table", "json"]).default("table"),
+    timeout: z.number().default(30000),
+    defaultWorkspace: z.string().optional(),
+    workspaceOrigin: z.enum(["override", "selection"]).optional(),
+    workspaceName: z.string().optional(),
+    defaultOrganization: z.string().optional(),
+    organizationName: z.string().optional(),
+    organizationSlug: z.string().optional(),
+    keyScope: keyScopeSchema.optional()
+  });
+  credentialsSchema = z.object({
+    apiKey: z.string().optional(),
+    endpoint: z.string().optional(),
+    defaultWorkspace: z.string().optional(),
+    workspaceName: z.string().optional(),
+    defaultOrganization: z.string().optional(),
+    organizationName: z.string().optional(),
+    organizationSlug: z.string().optional(),
+    keyScope: keyScopeSchema.optional(),
+    expiresAt: z.string().optional()
+  }).loose();
+  CREDENTIALS_DIR = join(homedir(), ".config", "mutagent");
+  CREDENTIALS_FILE = join(CREDENTIALS_DIR, "credentials.json");
+});
+
 // src/lib/errors.ts
 function createErrorFromUnknown(error) {
   if (error instanceof MutagentError) {
@@ -278,7 +436,7 @@ function handleError(error, isJson) {
       }
       if (error instanceof WorkspaceContextError) {
         jsonOutput.remediation = {
-          setWorkspace: "mutagent config set workspace <workspace-id>",
+          setWorkspace: "mutagent workspaces use <name>",
           listWorkspaces: "mutagent workspaces list"
         };
       }
@@ -300,7 +458,7 @@ function handleError(error, isJson) {
       console.log(JSON.stringify(scrubKnownDeep(jsonOutput), null, 2));
     } else {
       console.error(`Error: ${scrubKnown(error.message)}`);
-      if (error instanceof AuthenticationError) {
+      if (error.name === "TenancyError") {} else if (error instanceof AuthenticationError) {
         console.error("");
         console.error(AUTH_REMEDIATION_MESSAGE);
       } else if (error instanceof WorkspaceContextError) {
@@ -403,14 +561,14 @@ var init_errors = __esm(() => {
     }
   };
   WORKSPACE_REMEDIATION_MESSAGE = [
-    "Workspace context missing. To fix:",
-    "  mutagent config set workspace <workspace-id>   # Set default workspace",
-    "  mutagent workspaces list                        # List available workspaces"
+    "No workspace selected. To fix:",
+    "  mutagent workspaces use <name>    # Select the workspace every later command works in",
+    "  mutagent workspaces list          # Your workspaces"
   ].join(`
 `);
   WorkspaceContextError = class WorkspaceContextError extends MutagentError {
     constructor(message) {
-      super("WORKSPACE_REQUIRED", message ?? "Workspace context is required but not configured", "Run: mutagent config set workspace <workspace-id>", 3);
+      super("WORKSPACE_REQUIRED", message ?? "Workspace context is required but not configured", "Run: mutagent workspaces use <name>", 3);
     }
   };
   ValidationError = class ValidationError extends MutagentError {
@@ -444,6 +602,290 @@ var init_errors = __esm(() => {
   };
 });
 
+// src/lib/organization-scope.ts
+var exports_organization_scope = {};
+__export(exports_organization_scope, {
+  unreachableServerError: () => unreachableServerError,
+  tenancyHeaders: () => tenancyHeaders,
+  tenancyFailure: () => tenancyFailure,
+  setWorkspaceFlag: () => setWorkspaceFlag,
+  setOrgAssertion: () => setOrgAssertion,
+  resolveKeyTenancy: () => resolveKeyTenancy,
+  otherOrganizationHint: () => otherOrganizationHint,
+  orgMismatch: () => orgMismatch,
+  noWorkspaceSelected: () => noWorkspaceSelected,
+  matchesOrganization: () => matchesOrganization,
+  looksLikeWorkspaceId: () => looksLikeWorkspaceId,
+  listKeyWorkspaces: () => listKeyWorkspaces,
+  findWorkspace: () => findWorkspace,
+  fetchOrganizations: () => fetchOrganizations,
+  fetchKeySelf: () => fetchKeySelf,
+  envKeyHasNoSelection: () => envKeyHasNoSelection,
+  deadKeyError: () => deadKeyError,
+  configTenancyHeaders: () => configTenancyHeaders,
+  TenancyError: () => TenancyError,
+  TENANCY_DENIED: () => TENANCY_DENIED
+});
+function looksLikeWorkspaceId(value) {
+  return UUID_PATTERN.test(value);
+}
+function tenancyHeaders(t) {
+  const headers = {};
+  if (!t.workspaceId)
+    return headers;
+  if (t.keyScope === "workspace") {
+    if (t.workspaceOrigin === "override")
+      headers["x-workspace-id"] = t.workspaceId;
+    return headers;
+  }
+  headers["x-workspace-id"] = t.workspaceId;
+  if (t.keyScope === "user" && t.organizationId)
+    headers["x-organization-id"] = t.organizationId;
+  return headers;
+}
+function configTenancyHeaders(config) {
+  return tenancyHeaders({
+    keyScope: config.keyScope,
+    workspaceId: config.defaultWorkspace,
+    workspaceOrigin: config.workspaceOrigin,
+    organizationId: config.defaultOrganization
+  });
+}
+function parseBody(body) {
+  try {
+    const parsed = JSON.parse(body);
+    if (parsed && typeof parsed === "object")
+      return parsed;
+  } catch {}
+  return {};
+}
+function deadKeyError() {
+  return new TenancyError("AUTH_EXPIRED", "Your CLI key expired or was revoked.", "Run: mutagent login", 2);
+}
+function tenancyFailure(status, body, ctx) {
+  const parsed = parseBody(body);
+  if (status === 401)
+    return deadKeyError();
+  if (status === 403 && parsed.code === TENANCY_DENIED) {
+    const shown = ctx.workspaceName ?? ctx.workspaceId ?? "workspace";
+    if (ctx.workspaceOrigin === "selection") {
+      return new TenancyError(TENANCY_DENIED, `Your saved workspace ${shown} is no longer available to you.`, "Run: mutagent workspaces use <name>");
+    }
+    const where = ctx.organizationName ? ` in ${ctx.organizationName}` : "";
+    return new TenancyError(TENANCY_DENIED, `No workspace "${shown}" among your workspaces${where}.`, "See: mutagent workspaces list");
+  }
+  if (status === 403 && ctx.keyScope === "workspace" && ctx.workspaceOrigin === "override") {
+    return new TenancyError("WORKSPACE_KEY_MISMATCH", "This API key only works in its own workspace.", "Run: mutagent login (for a key that can switch workspaces)");
+  }
+  if (status === 400 && (parsed.message ?? body).toLowerCase().includes("x-workspace-id")) {
+    return noWorkspaceSelected();
+  }
+  return;
+}
+function noWorkspaceSelected() {
+  const fix = envKeyReplacesFile() ? ENV_KEY_WORKSPACE_FIX : "Run: mutagent workspaces use <name>";
+  return new TenancyError("WORKSPACE_REQUIRED", "No workspace selected.", fix, 3);
+}
+function envKeyHasNoSelection() {
+  return new TenancyError("WORKSPACE_FROM_ENV", "With MUTAGENT_API_KEY set, the workspace comes from --workspace or MUTAGENT_WORKSPACE_ID.", ENV_KEY_WORKSPACE_FIX);
+}
+async function tenancyFetch(url, init) {
+  try {
+    return await fetch(url, init);
+  } catch {
+    throw unreachableServerError(url);
+  }
+}
+function unreachableServerError(url) {
+  let origin = url;
+  try {
+    origin = new URL(url).origin;
+  } catch {}
+  return new MutagentError("REQUEST_FAILED", `Unable to connect to the Mutagent server at ${origin}.`, "Check your connection and the endpoint: mutagent config get endpoint");
+}
+async function fetchKeySelf(apiKey, endpoint, opts = {}) {
+  const response = await tenancyFetch(`${endpoint}/api/api-keys/self`, {
+    headers: { "x-api-key": apiKey, ...opts.headers }
+  });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw tenancyFailure(response.status, body, opts.ctx ?? {}) ?? new MutagentError("KEY_SCOPE_UNAVAILABLE", `Could not read this API key's scope (${String(response.status)}).`, "Check the endpoint with: mutagent config get endpoint");
+  }
+  return await response.json();
+}
+async function fetchOrganizations(apiKey, endpoint) {
+  try {
+    const response = await fetch(`${endpoint}/api/organizations`, {
+      headers: { "x-api-key": apiKey }
+    });
+    if (!response.ok)
+      return [];
+    const data = await response.json();
+    return data.data ?? [];
+  } catch {
+    return [];
+  }
+}
+function matchesOrganization(value, org) {
+  if (!org)
+    return false;
+  if (value === org.id || org.slug !== undefined && value === org.slug)
+    return true;
+  return org.name !== undefined && value.toLowerCase() === org.name.toLowerCase();
+}
+function orgMismatch(value, org) {
+  const shown = org.slug ? `${org.name} (${org.slug})` : org.name;
+  return new TenancyError("ORG_MISMATCH", `Your key is for ${shown}.`, `Run: mutagent login --org ${value}`);
+}
+function otherOrganizationHint(wanted, keyOrg, orgs) {
+  const others = orgs.filter((o) => o.id !== keyOrg?.id);
+  const where = keyOrg ? ` in ${keyOrg.name}` : "";
+  const what = `No workspace "${wanted}"${where}.`;
+  const named = others.map((o) => `${o.name} (${o.slug ?? o.id})`).join(", ");
+  if (others.length === 1 && others[0]) {
+    const only = others[0];
+    return new TenancyError("WORKSPACE_NOT_FOUND", `${what} Your other organization: ${named}.`, `To switch: mutagent login --org ${only.slug ?? only.id}`);
+  }
+  if (others.length > 1) {
+    return new TenancyError("WORKSPACE_NOT_FOUND", `${what} Your other organizations: ${named}.`, "To switch: mutagent login --org <slug>");
+  }
+  return new TenancyError("WORKSPACE_NOT_FOUND", what, "See: mutagent workspaces list");
+}
+function setOrgAssertion(value) {
+  const trimmed = value?.trim();
+  orgAssertion = trimmed === "" ? undefined : trimmed;
+}
+function setWorkspaceFlag(value) {
+  const trimmed = value?.trim();
+  workspaceFlag = trimmed === "" ? undefined : trimmed;
+}
+function endpointOf(configured) {
+  const trimmed = configured?.trim();
+  return (trimmed === undefined || trimmed === "" ? "https://api.mutagent.io" : trimmed).replace(/\/+$/, "");
+}
+async function probeKeyScope(apiKey, endpoint, workspaceNamed) {
+  const fromFile = !envKeyReplacesFile();
+  if (!fromFile && workspaceNamed && orgAssertion === undefined)
+    return;
+  try {
+    const self = await fetchKeySelf(apiKey, endpoint);
+    if (fromFile)
+      recordKeyScope(self);
+    return self;
+  } catch (error) {
+    if (error instanceof MutagentError && (error.code === "AUTH_EXPIRED" || error.code === "REQUEST_FAILED"))
+      throw error;
+    return;
+  }
+}
+function enforceOrgAssertion(org) {
+  if (orgAssertion === undefined)
+    return;
+  if (org === undefined) {
+    throw new TenancyError("ORG_UNKNOWN", "This key's organization is unknown, so --org cannot be checked.", "Run: mutagent workspaces current");
+  }
+  if (!matchesOrganization(orgAssertion, org)) {
+    throw orgMismatch(orgAssertion, org);
+  }
+}
+async function resolveKeyTenancy(apiKey, opts = {}) {
+  const config = loadConfig();
+  const endpoint = endpointOf(config.endpoint);
+  let keyScope = config.keyScope;
+  let organization = config.defaultOrganization ? { id: config.defaultOrganization, name: config.organizationName ?? config.defaultOrganization, slug: config.organizationSlug } : undefined;
+  let workspaceId = config.defaultWorkspace;
+  let workspaceName = config.workspaceName;
+  const workspaceOrigin = config.workspaceOrigin;
+  if (keyScope === undefined && (opts.probe !== false || orgAssertion !== undefined)) {
+    const self = await probeKeyScope(apiKey, endpoint, workspaceId !== undefined);
+    if (self) {
+      keyScope = self.scope;
+      organization = self.organization ?? undefined;
+      if (self.scope === "workspace" && self.workspace && workspaceOrigin !== "override") {
+        workspaceId = self.workspace.id;
+        workspaceName = self.workspace.name;
+      }
+    }
+  }
+  enforceOrgAssertion(organization);
+  if (opts.resolveOverride !== false && workspaceFlag !== undefined && workspaceId === workspaceFlag && !looksLikeWorkspaceId(workspaceId)) {
+    const found = await findWorkspace(workspaceId, { apiKey, endpoint, keyScope, organization, workspaceId: config.defaultWorkspace, workspaceName });
+    workspaceId = found.id;
+    workspaceName = found.name;
+    process.env.MUTAGENT_WORKSPACE_ID = found.id;
+  }
+  return { endpoint, keyScope, organization, workspaceId, workspaceName, workspaceOrigin };
+}
+async function listKeyWorkspaces(apiKey, endpoint, t) {
+  const headers = { "x-api-key": apiKey };
+  if (t.keyScope === "user" && t.organization)
+    headers["x-organization-id"] = t.organization.id;
+  const response = await tenancyFetch(`${endpoint}/api/workspaces`, { headers });
+  if (!response.ok) {
+    const body = await response.text().catch(() => "");
+    throw tenancyFailure(response.status, body, { keyScope: t.keyScope, organizationName: t.organization?.name }) ?? new MutagentError("REQUEST_FAILED", `Could not list workspaces (${String(response.status)}).`, "Run: mutagent workspaces current");
+  }
+  const data = await response.json();
+  return data.workspaces ?? [];
+}
+async function findWorkspace(wanted, t) {
+  if (t.keyScope === "workspace") {
+    if (t.workspaceId && (wanted === t.workspaceId || wanted === t.workspaceName)) {
+      return { id: t.workspaceId, name: t.workspaceName ?? t.workspaceId };
+    }
+    throw new TenancyError("WORKSPACE_KEY_MISMATCH", `This key only works in ${t.workspaceName ?? t.workspaceId ?? "its own workspace"}.`, "Run: mutagent login (for a key that can switch workspaces)");
+  }
+  const rows = await listKeyWorkspaces(t.apiKey, t.endpoint, t);
+  const byId = rows.find((w) => w.id === wanted);
+  if (byId)
+    return { id: byId.id, name: byId.name };
+  let matches = rows.filter((w) => w.name === wanted || w.slug === wanted);
+  if (matches.length === 0)
+    matches = rows.filter((w) => w.name.toLowerCase() === wanted.toLowerCase());
+  if (matches.length === 1 && matches[0])
+    return { id: matches[0].id, name: matches[0].name };
+  if (matches.length > 1) {
+    throw new TenancyError("WORKSPACE_AMBIGUOUS", `Several workspaces are named "${wanted}": ${matches.map((w) => `${w.name} (${w.id})`).join(", ")}.`, "Run: mutagent workspaces use <id>");
+  }
+  const orgs = await fetchOrganizations(t.apiKey, t.endpoint);
+  throw otherOrganizationHint(wanted, t.organization, orgs);
+}
+var TENANCY_DENIED = "TENANCY_DENIED", UUID_PATTERN, TenancyError, ENV_KEY_WORKSPACE_FIX = "Pass --workspace <name|id> or set MUTAGENT_WORKSPACE_ID", orgAssertion, workspaceFlag;
+var init_organization_scope = __esm(() => {
+  init_errors();
+  init_config();
+  UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+  TenancyError = class TenancyError extends MutagentError {
+    constructor(code, what, fix, exitCode = 1) {
+      super(code, `${what} ${fix}`, fix.replace(/^(Run|See|To switch): /, ""), exitCode);
+      this.name = "TenancyError";
+    }
+  };
+});
+
+// src/lib/provider-request.ts
+function buildCreateProviderBody(data) {
+  const body = {
+    name: data.name,
+    provider: data.provider,
+    isDefault: data.isDefault ?? false
+  };
+  if (data.apiKey)
+    body.apiKey = data.apiKey;
+  if (data.baseUrl)
+    body.baseUrl = data.baseUrl;
+  if (data.hostedFamily)
+    body.hostedFamily = data.hostedFamily;
+  if (data.credentialFields && Object.keys(data.credentialFields).length > 0) {
+    body.credentialFields = data.credentialFields;
+  }
+  if (data.metadata && Object.keys(data.metadata).length > 0)
+    body.metadata = data.metadata;
+  if (data.supportedModels !== undefined)
+    body.supportedModels = data.supportedModels;
+  return body;
+}
+
 // src/lib/sdk-debug.ts
 function isDebugEnabled(env = process.env) {
   return TRUTHY.has((env.MUTAGENT_DEBUG ?? "").trim().toLowerCase());
@@ -538,282 +980,6 @@ var init_sdk_debug = __esm(() => {
   };
 });
 
-// src/lib/organization-scope.ts
-function isWellFormedOrganizationId(id) {
-  return ORGANIZATION_ID_PATTERN.test(id);
-}
-function isOrganizationScopeMismatch(status, body) {
-  if (status !== 403)
-    return false;
-  return body.toLowerCase().includes("organization scope mismatch");
-}
-async function lookupOrganizations(apiKey, endpoint) {
-  try {
-    const response = await fetch(`${endpoint}/api/organizations`, {
-      headers: { "x-api-key": apiKey }
-    });
-    if (!response.ok)
-      return [];
-    const data = await response.json();
-    return data.data ?? [];
-  } catch {
-    return [];
-  }
-}
-async function fetchOrganizations(apiKey, endpoint) {
-  return lookupOrganizations(apiKey, endpoint);
-}
-async function assertUsableOrganizationId(id, lookup) {
-  const orgs = lookup.apiKey ? await lookup.fetchOrganizations(lookup.apiKey, lookup.endpoint).catch(() => []) : [];
-  if (orgs.length === 0) {
-    if (isWellFormedOrganizationId(id))
-      return;
-    throw new MutagentError("INVALID_ORGANIZATION_ID", `"${id}" is not an organization id.`, `Organization ids look like org_xxxxxxxxxxxxxxxxxxxxx.
-` + "Log in so the id can be checked against your account: mutagent auth login --browser");
-  }
-  if (orgs.some((org) => org.id === id))
-    return;
-  throw new MutagentError("UNKNOWN_ORGANIZATION", `"${id}" is not an organization this API key can access.`, `Available: ${orgs.map((org) => org.id).join(", ")}
-` + "A stored organization that does not match the key makes every request fail with 403.");
-}
-function createOrgScopeRecoveringFetcher(hooks) {
-  let recoveryUsed = false;
-  async function recover() {
-    if (recoveryUsed)
-      return;
-    recoveryUsed = true;
-    const stale = hooks.currentOrganization();
-    if (!stale)
-      return;
-    hooks.adoptOrganization(undefined);
-    hooks.forgetStoredOrganization?.();
-    const orgs = await lookupOrganizations(hooks.apiKey, hooks.endpoint);
-    const resolved = orgs[0]?.id;
-    if (!resolved || resolved === stale)
-      return;
-    hooks.adoptOrganization(resolved);
-    if (isDebugEnabled()) {
-      process.stderr.write(`[mutagent] Stored organization was rejected by the API; re-resolved and retried once.
-`);
-    }
-    return resolved;
-  }
-  return async function fetchWithOrgRecovery(input, init) {
-    const retryTemplate = input instanceof Request ? input.clone() : undefined;
-    const response = init == null ? await fetch(input) : await fetch(input, init);
-    if (response.status !== 403)
-      return response;
-    const body = await response.clone().text().catch(() => "");
-    if (!isOrganizationScopeMismatch(response.status, body))
-      return response;
-    const resolved = await recover();
-    if (!resolved)
-      return response;
-    if (retryTemplate) {
-      retryTemplate.headers.set("x-organization-id", resolved);
-      return fetch(retryTemplate);
-    }
-    const headers = new Headers(init?.headers);
-    headers.set("x-organization-id", resolved);
-    return fetch(input, { ...init, headers });
-  };
-}
-var ORGANIZATION_ID_PATTERN;
-var init_organization_scope = __esm(() => {
-  init_errors();
-  init_sdk_debug();
-  ORGANIZATION_ID_PATTERN = /^org_[A-Za-z0-9_-]{8,}$/;
-});
-
-// src/lib/config.ts
-import { cosmiconfigSync } from "cosmiconfig";
-import { z } from "zod";
-import { homedir } from "os";
-import { join } from "path";
-import { existsSync, readFileSync, mkdirSync } from "fs";
-function parseJsonSafe(content, schema) {
-  try {
-    const parsed = JSON.parse(content);
-    return schema.parse(parsed);
-  } catch {
-    return null;
-  }
-}
-function loadConfig() {
-  const explorer = cosmiconfigSync("mutagent");
-  const result = explorer.search();
-  const rcConfig = result?.config;
-  let credentials = null;
-  if (existsSync(CREDENTIALS_FILE)) {
-    credentials = parseJsonSafe(readFileSync(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
-  }
-  const merged = {
-    providers: {},
-    environment: "production",
-    ...rcConfig,
-    ...credentials,
-    apiKey: process.env.MUTAGENT_API_KEY ?? credentials?.apiKey ?? rcConfig?.apiKey,
-    endpoint: process.env.MUTAGENT_ENDPOINT ?? credentials?.endpoint ?? rcConfig?.endpoint,
-    defaultWorkspace: process.env.MUTAGENT_WORKSPACE_ID ?? credentials?.defaultWorkspace ?? rcConfig?.defaultWorkspace,
-    defaultWorkspaceSource: process.env.MUTAGENT_WORKSPACE_ID ? "user" : credentials?.defaultWorkspace ? credentials.defaultWorkspaceSource ?? "login-inferred" : rcConfig?.defaultWorkspace ? "login-inferred" : undefined,
-    defaultOrganization: credentials?.defaultOrganization ?? rcConfig?.defaultOrganization
-  };
-  return configSchema.parse(merged);
-}
-function saveCredentials(apiKey, endpoint) {
-  if (!existsSync(CREDENTIALS_DIR)) {
-    mkdirSync(CREDENTIALS_DIR, { recursive: true });
-  }
-  const config = loadConfig();
-  const credentials = {
-    apiKey,
-    endpoint: endpoint ?? config.endpoint
-  };
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
-}
-function saveFullCredentials(creds) {
-  if (!existsSync(CREDENTIALS_DIR)) {
-    mkdirSync(CREDENTIALS_DIR, { recursive: true });
-  }
-  let existingCredentials = {};
-  if (existsSync(CREDENTIALS_FILE)) {
-    try {
-      existingCredentials = JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8"));
-    } catch {}
-  }
-  const existingSource = existingCredentials.defaultWorkspaceSource;
-  const workspaceChanged = creds.workspaceId !== undefined && creds.workspaceId !== existingCredentials.defaultWorkspace;
-  const source = creds.workspaceId === undefined ? existingSource : workspaceChanged ? "login-inferred" : existingSource ?? "login-inferred";
-  const credentials = {
-    ...existingCredentials,
-    apiKey: creds.apiKey,
-    endpoint: creds.endpoint ?? existingCredentials.endpoint ?? "https://api.mutagent.io",
-    defaultWorkspace: creds.workspaceId ?? existingCredentials.defaultWorkspace,
-    defaultWorkspaceSource: source,
-    defaultOrganization: creds.organizationId ?? existingCredentials.defaultOrganization,
-    expiresAt: creds.expiresAt
-  };
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(credentials, null, 2));
-}
-function clearCredentials() {
-  if (existsSync(CREDENTIALS_FILE)) {
-    writeSecureFile(CREDENTIALS_FILE, JSON.stringify({}));
-  }
-}
-function hasCredentials() {
-  if (process.env.MUTAGENT_API_KEY)
-    return true;
-  if (!existsSync(CREDENTIALS_FILE))
-    return false;
-  const credentials = parseJsonSafe(readFileSync(CREDENTIALS_FILE, "utf-8"), credentialsSchema);
-  return credentials?.apiKey !== undefined && credentials.apiKey !== "";
-}
-function getApiKey() {
-  const apiKey = process.env.MUTAGENT_API_KEY ?? loadConfig().apiKey;
-  registerSecret(apiKey);
-  return apiKey;
-}
-function setDefaultWorkspace(workspaceId, source = "user") {
-  if (!existsSync(CREDENTIALS_DIR)) {
-    mkdirSync(CREDENTIALS_DIR, { recursive: true });
-  }
-  let existingCredentials = {};
-  if (existsSync(CREDENTIALS_FILE)) {
-    try {
-      existingCredentials = JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8"));
-    } catch {}
-  }
-  const updated = {
-    ...existingCredentials,
-    defaultWorkspace: workspaceId,
-    defaultWorkspaceSource: source
-  };
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
-}
-function setDefaultOrganization(organizationId) {
-  if (!isWellFormedOrganizationId(organizationId)) {
-    throw new MutagentError("INVALID_ORGANIZATION_ID", `"${organizationId}" is not an organization id.`, `Organization ids look like org_xxxxxxxxxxxxxxxxxxxxx.
-` + "List the ones you can use with: mutagent auth status");
-  }
-  if (!existsSync(CREDENTIALS_DIR)) {
-    mkdirSync(CREDENTIALS_DIR, { recursive: true });
-  }
-  let existingCredentials = {};
-  if (existsSync(CREDENTIALS_FILE)) {
-    try {
-      existingCredentials = JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8"));
-    } catch {}
-  }
-  const updated = {
-    ...existingCredentials,
-    defaultOrganization: organizationId
-  };
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(updated, null, 2));
-}
-function clearDefaultOrganization() {
-  if (!existsSync(CREDENTIALS_FILE))
-    return;
-  let existingCredentials;
-  try {
-    existingCredentials = JSON.parse(readFileSync(CREDENTIALS_FILE, "utf-8"));
-  } catch {
-    return;
-  }
-  if (!("defaultOrganization" in existingCredentials))
-    return;
-  delete existingCredentials.defaultOrganization;
-  writeSecureFile(CREDENTIALS_FILE, JSON.stringify(existingCredentials, null, 2));
-}
-var configSchema, credentialsSchema, CREDENTIALS_DIR, CREDENTIALS_FILE;
-var init_config = __esm(() => {
-  init_secure_file();
-  init_known_secrets();
-  init_organization_scope();
-  init_errors();
-  configSchema = z.object({
-    apiKey: z.string().optional(),
-    endpoint: z.string().default("https://api.mutagent.io"),
-    format: z.enum(["table", "json"]).default("table"),
-    timeout: z.number().default(30000),
-    defaultWorkspace: z.string().optional(),
-    defaultWorkspaceSource: z.enum(["user", "login-inferred"]).optional(),
-    defaultOrganization: z.string().optional()
-  });
-  credentialsSchema = z.object({
-    apiKey: z.string().optional(),
-    endpoint: z.string().optional(),
-    defaultWorkspace: z.string().optional(),
-    defaultWorkspaceSource: z.enum(["user", "login-inferred"]).optional(),
-    defaultOrganization: z.string().optional(),
-    expiresAt: z.string().optional()
-  }).loose();
-  CREDENTIALS_DIR = join(homedir(), ".config", "mutagent");
-  CREDENTIALS_FILE = join(CREDENTIALS_DIR, "credentials.json");
-});
-
-// src/lib/provider-request.ts
-function buildCreateProviderBody(data) {
-  const body = {
-    name: data.name,
-    provider: data.provider,
-    isDefault: data.isDefault ?? false
-  };
-  if (data.apiKey)
-    body.apiKey = data.apiKey;
-  if (data.baseUrl)
-    body.baseUrl = data.baseUrl;
-  if (data.hostedFamily)
-    body.hostedFamily = data.hostedFamily;
-  if (data.credentialFields && Object.keys(data.credentialFields).length > 0) {
-    body.credentialFields = data.credentialFields;
-  }
-  if (data.metadata && Object.keys(data.metadata).length > 0)
-    body.metadata = data.metadata;
-  if (data.supportedModels !== undefined)
-    body.supportedModels = data.supportedModels;
-  return body;
-}
-
 // src/lib/sdk-mappers.ts
 import { LlmProviderType as SDKProviderEnum } from "@mutagent/sdk/models";
 function isProviderType(value) {
@@ -902,15 +1068,6 @@ var init_sdk_mappers = __esm(() => {
 });
 
 // src/lib/sdk-client.ts
-var exports_sdk_client = {};
-__export(exports_sdk_client, {
-  validateApiKey: () => validateApiKey,
-  resetSDKClient: () => resetSDKClient,
-  getSDKClient: () => getSDKClient,
-  fetchWorkspaces: () => fetchWorkspaces,
-  fetchOrganizations: () => fetchOrganizations,
-  MutagentSDK: () => SDKClientWrapper
-});
 import { Mutagent, HTTPClient } from "@mutagent/sdk";
 
 class SDKClientWrapper {
@@ -919,32 +1076,24 @@ class SDKClientWrapper {
   endpoint;
   workspaceId;
   organizationId;
-  workspaceResolution = "none";
+  tenancy;
   debugSecrets = new Set;
-  recoveringFetch;
   constructor(opts) {
     this.apiKey = opts.apiKey;
     this.endpoint = opts.serverURL ?? "http://localhost:3003";
     this.workspaceId = opts.workspaceId;
     this.organizationId = opts.organizationId;
-    if (opts.workspaceId && opts.workspaceSource === "user") {
-      this.workspaceResolution = "configured";
-    }
-    this.recoveringFetch = createOrgScopeRecoveringFetcher({
-      apiKey: this.apiKey,
-      endpoint: this.endpoint,
-      currentOrganization: () => this.organizationId,
-      adoptOrganization: (id) => {
-        this.organizationId = id;
-      },
-      forgetStoredOrganization: opts.clearStoredOrganization
-    });
-    const httpClient = new HTTPClient({ fetcher: this.recoveringFetch });
+    this.tenancy = {
+      keyScope: opts.keyScope,
+      workspaceId: opts.workspaceId,
+      workspaceName: opts.workspaceName,
+      workspaceOrigin: opts.workspaceOrigin ?? (opts.workspaceId ? "selection" : undefined),
+      organizationName: opts.organizationName
+    };
+    const httpClient = new HTTPClient;
     httpClient.addHook("beforeRequest", (req) => {
-      if (this.workspaceId)
-        req.headers.set("x-workspace-id", this.workspaceId);
-      if (this.organizationId)
-        req.headers.set("x-organization-id", this.organizationId);
+      for (const [name, value] of Object.entries(this.tenancyHeaders()))
+        req.headers.set(name, value);
       return req;
     });
     this.debugSecrets.add(this.apiKey);
@@ -959,8 +1108,16 @@ class SDKClientWrapper {
     });
   }
   handleError(error) {
+    if (error instanceof Error && SDK_TRANSPORT_ERRORS.has(error.name)) {
+      throw unreachableServerError(this.endpoint);
+    }
     if (error && typeof error === "object") {
       const err = error;
+      if (err.statusCode) {
+        const tenancy = tenancyFailure(err.statusCode, err.body ?? "", this.tenancy);
+        if (tenancy)
+          throw tenancy;
+      }
       if (err.statusCode === 401) {
         throw new AuthenticationError;
       }
@@ -981,7 +1138,7 @@ class SDKClientWrapper {
     }
     if (error instanceof TypeError && typeof error.message === "string") {
       if (error.message.includes("fetch") || error.message.includes("network") || error.message.includes("ECONNREFUSED")) {
-        throw new MutagentError("NETWORK_ERROR", "Unable to connect to the Mutagent server", "Check your internet connection and verify the server URL with: mutagent config list");
+        throw unreachableServerError(this.endpoint);
       }
     }
     if (error instanceof Error) {
@@ -999,28 +1156,31 @@ class SDKClientWrapper {
     } else if (optHeaders) {
       extraHeaders = optHeaders;
     }
-    const tenancyHeaders = {};
-    if (this.workspaceId)
-      tenancyHeaders["x-workspace-id"] = this.workspaceId;
-    if (this.organizationId)
-      tenancyHeaders["x-organization-id"] = this.organizationId;
-    const response = await this.recoveringFetch(`${this.endpoint}${path}`, {
-      ...options,
-      headers: {
-        "x-api-key": this.apiKey,
-        "Content-Type": "application/json",
-        ...tenancyHeaders,
-        ...extraHeaders
-      }
-    });
+    let response;
+    try {
+      response = await fetch(`${this.endpoint}${path}`, {
+        ...options,
+        headers: {
+          "x-api-key": this.apiKey,
+          "Content-Type": "application/json",
+          ...this.tenancyHeaders(),
+          ...extraHeaders
+        }
+      });
+    } catch {
+      throw unreachableServerError(this.endpoint);
+    }
     if (!response.ok) {
+      const error = await response.text();
+      const tenancy = tenancyFailure(response.status, error, this.tenancy);
+      if (tenancy)
+        throw tenancy;
       if (response.status === 401) {
         throw new AuthenticationError;
       }
       if (response.status === 403) {
-        throw new ApiError(403, await response.text() || "Access denied");
+        throw new ApiError(403, error || "Access denied");
       }
-      const error = await response.text();
       const errorLower = error.toLowerCase();
       if (errorLower.includes("workspace") && (errorLower.includes("missing") || errorLower.includes("required")) || errorLower.includes("x-workspace-id")) {
         throw new WorkspaceContextError(error);
@@ -1166,11 +1326,9 @@ class SDKClientWrapper {
   }
   async getModelsCatalog() {
     try {
-      const wsId = this.workspaceId;
-      if (!wsId)
+      if (!this.workspaceId)
         return { models: [] };
-      const qs = `?workspaceId=${encodeURIComponent(wsId)}`;
-      return await this.request(`/api/providers/catalog${qs}`);
+      return await this.request("/api/providers/catalog");
     } catch {
       return { models: [] };
     }
@@ -1178,56 +1336,17 @@ class SDKClientWrapper {
   getCurrentWorkspaceId() {
     return this.workspaceId;
   }
-  getCurrentOrgId() {
-    return this.organizationId;
-  }
-  async ensureContext() {
-    const needsWorkspaceClassification = !this.workspaceId || this.workspaceResolution === "none";
-    if (this.organizationId && !needsWorkspaceClassification)
-      return;
-    if (!this.organizationId) {
-      let orgs = await fetchOrganizations(this.apiKey, this.endpoint).catch(() => []);
-      if (orgs.length === 0) {
-        await new Promise((r) => setTimeout(r, 1000));
-        orgs = await fetchOrganizations(this.apiKey, this.endpoint).catch(() => []);
-      }
-      if (orgs.length > 0 && orgs[0]) {
-        this.organizationId = orgs[0].id;
-      }
-    }
-    if (this.workspaceResolution === "none" && this.organizationId) {
-      try {
-        const response = await this.sdk.workspaces.listWorkspaces({ includeInactive: false });
-        const workspaces = toWorkspaceList(response.workspaces);
-        if (workspaces.length === 1 && workspaces[0]) {
-          this.workspaceId = workspaces[0].id;
-          this.workspaceResolution = "sole";
-        } else if (workspaces.length > 1) {
-          const defaultWs = workspaces.find((ws) => ws.isDefault);
-          if (defaultWs) {
-            this.workspaceId = defaultWs.id;
-            this.workspaceResolution = "configured";
-          } else {
-            const first = workspaces[0] ?? undefined;
-            if (first) {
-              this.workspaceId = this.workspaceId ?? first.id;
-              this.workspaceResolution = "ambiguous";
-            }
-          }
-        }
-      } catch {}
-    }
-  }
-  getWorkspaceResolution() {
-    return this.workspaceResolution;
+  tenancyHeaders() {
+    return tenancyHeaders({
+      keyScope: this.tenancy.keyScope,
+      workspaceId: this.workspaceId,
+      workspaceOrigin: this.tenancy.workspaceOrigin,
+      organizationId: this.organizationId
+    });
   }
-  requireUnambiguousWorkspace() {
-    if (!this.workspaceId || this.workspaceResolution === "none") {
-      throw new MutagentError("WORKSPACE_REQUIRED", "No workspace configured.", "Set one with: mutagent config set workspace <workspace-id>  (list them with: mutagent workspaces list)");
-    }
-    if (this.workspaceResolution === "ambiguous") {
-      throw new MutagentError("WORKSPACE_AMBIGUOUS", "Several workspaces are available and none is marked default, so the target for this write is ambiguous.", "Choose one explicitly: mutagent config set workspace <workspace-id>  (list them with: mutagent workspaces list)");
-    }
+  requireSelectedWorkspace() {
+    if (!this.workspaceId)
+      throw noWorkspaceSelected();
     return this.workspaceId;
   }
   async testProvider(id) {
@@ -1241,7 +1360,7 @@ class SDKClientWrapper {
     }
   }
   async createProvider(data) {
-    this.requireUnambiguousWorkspace();
+    this.requireSelectedWorkspace();
     registerSecret(data.apiKey);
     registerSecretFields(data.credentialFields);
     const body = buildCreateProviderBody(data);
@@ -1256,7 +1375,7 @@ class SDKClientWrapper {
     }
   }
   async updateProvider(id, data) {
-    const workspaceId = this.requireUnambiguousWorkspace();
+    const workspaceId = this.requireSelectedWorkspace();
     if (data.apiKey)
       this.debugSecrets.add(data.apiKey);
     registerSecret(data.apiKey);
@@ -1295,7 +1414,7 @@ class SDKClientWrapper {
     }
   }
   async deleteProvider(id) {
-    const workspaceId = this.requireUnambiguousWorkspace();
+    const workspaceId = this.requireSelectedWorkspace();
     try {
       await this.sdk.llmProviders.deleteProviderConfig({ id });
       return { workspaceId };
@@ -1310,21 +1429,18 @@ async function getSDKClient() {
     if (!apiKey) {
       throw new AuthenticationError;
     }
-    const config = loadConfig();
+    const tenancy = await resolveKeyTenancy(apiKey);
+    if (tenancy.keyScope === "organization" && !tenancy.workspaceId)
+      throw noWorkspaceSelected();
     sdkClient = new SDKClientWrapper({
       apiKey,
-      serverURL: config.endpoint,
-      workspaceId: config.defaultWorkspace,
-      organizationId: config.defaultOrganization,
-      workspaceSource: config.defaultWorkspaceSource,
-      clearStoredOrganization: clearDefaultOrganization
-    });
-    await sdkClient.ensureContext().catch((err) => {
-      if (isDebugEnabled()) {
-        const message = err instanceof Error ? err.message : String(err);
-        process.stderr.write(`[mutagent] Context resolution failed: ${message}
-`);
-      }
+      serverURL: tenancy.endpoint,
+      workspaceId: tenancy.workspaceId,
+      workspaceName: tenancy.workspaceName,
+      workspaceOrigin: tenancy.workspaceOrigin,
+      organizationId: tenancy.organization?.id,
+      organizationName: tenancy.organization?.name,
+      keyScope: tenancy.keyScope
     });
   }
   return sdkClient;
@@ -1342,20 +1458,7 @@ async function validateApiKey(apiKey, endpoint) {
     return false;
   }
 }
-async function fetchWorkspaces(apiKey, endpoint, orgId) {
-  try {
-    const response = await fetch(`${endpoint}/api/workspaces`, {
-      headers: { "x-api-key": apiKey, "x-organization-id": orgId }
-    });
-    if (!response.ok)
-      return [];
-    const data = await response.json();
-    return data.workspaces ?? [];
-  } catch {
-    return [];
-  }
-}
-var sdkClient = null;
+var SDK_TRANSPORT_ERRORS, sdkClient = null;
 var init_sdk_client = __esm(() => {
   init_errors();
   init_config();
@@ -1364,6 +1467,7 @@ var init_sdk_client = __esm(() => {
   init_known_secrets();
   init_sdk_mappers();
   init_organization_scope();
+  SDK_TRANSPORT_ERRORS = new Set(["ConnectionError", "RequestTimeoutError", "RequestAbortedError", "UnexpectedClientError"]);
 });
 
 // src/index.ts
@@ -1587,4 +1691,4 @@ export {
   ApiError
 };
 
-//# debugId=437AE9F8B6FD0C9364756E2164756E21
+//# debugId=6C0EFE359421B56964756E2164756E21