@agentuity/cli 2.0.5 → 2.0.7

package/src/cmd/coder/index.ts

@@ -1,4 +1,5 @@
 import { createCommand } from '../../types';
+import { configSubcommand } from './config';
 import { listSubcommand } from './list';
 import { inspectSubcommand } from './inspect';
 import { startSubcommand } from './start';
@@ -21,7 +22,11 @@ export const command = createCommand({
 			command: getCommand('coder inspect <session-id>'),
 			description: 'Show detailed session information',
 		},
+		{
+			command: getCommand('coder config set url https://hub.example.com'),
+			description: 'Set the default Coder Hub URL for this profile',
+		},
 	],
-	subcommands: [startSubcommand, listSubcommand, inspectSubcommand],
+	subcommands: [startSubcommand, listSubcommand, inspectSubcommand, configSubcommand],
 	optional: { auth: true },
 });

package/src/cmd/coder/inspect.ts

@@ -3,7 +3,17 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
 import { ErrorCode } from '../../errors';
-import { resolveHubUrl, hubFetchHeaders } from './hub-url';
+import {
+	clearStoredHubApiKeyOnUnauthorized,
+	formatHubUnauthorizedMessage,
+	formatMissingHubUrlMessage,
+	getHubResponseErrorMessage,
+	getHubUrlSetupGuidance,
+	hubFetchHeaders,
+	isHubUnauthorizedStatus,
+	resolveHubApiKey,
+	resolveHubUrl,
+} from './hub-url';
 
 function formatRelativeTime(isoDate: string): string {
 	const diffMs = Date.now() - new Date(isoDate).getTime();
@@ -52,18 +62,17 @@ export const inspectSubcommand = createSubcommand({
 		}),
 	},
 	async handler(ctx) {
-		const { args, options, opts } = ctx;
+		const { args, options, opts, config } = ctx;
 		const sessionId = args.session_id;
-		const hubUrl = await resolveHubUrl(opts?.hubUrl);
+		const hubUrl = await resolveHubUrl(opts?.hubUrl, config);
 
 		if (!hubUrl) {
-			tui.fatal(
-				'Could not find a running Coder Hub.\n\nEither:\n  - Start the Hub with: bun run dev\n  - Set AGENTUITY_CODER_HUB_URL environment variable\n  - Pass --hub-url flag',
-				ErrorCode.NETWORK_ERROR
-			);
+			tui.fatal(formatMissingHubUrlMessage(), ErrorCode.NETWORK_ERROR);
 			return;
 		}
 
+		const resolvedHubApiKey = await resolveHubApiKey(config);
+
 		let data: {
 			sessionId: string;
 			label: string;
@@ -104,9 +113,22 @@ export const inspectSubcommand = createSubcommand({
 
 		try {
 			const resp = await fetch(`${hubUrl}/api/hub/session/${encodeURIComponent(sessionId)}`, {
-				headers: hubFetchHeaders(),
+				headers: hubFetchHeaders(undefined, resolvedHubApiKey.apiKey),
 				signal: AbortSignal.timeout(10_000),
 			});
+			if (isHubUnauthorizedStatus(resp.status)) {
+				const message = await getHubResponseErrorMessage(resp);
+				const clearedStoredKey = await clearStoredHubApiKeyOnUnauthorized(
+					resp.status,
+					resolvedHubApiKey,
+					config
+				);
+				tui.fatal(
+					formatHubUnauthorizedMessage(hubUrl, message, { clearedStoredKey }),
+					ErrorCode.API_ERROR
+				);
+				return;
+			}
 			if (resp.status === 404) {
 				tui.fatal(`Session not found: ${sessionId}`, ErrorCode.RESOURCE_NOT_FOUND);
 				return;
@@ -116,8 +138,9 @@ export const inspectSubcommand = createSubcommand({
 				return;
 			}
 			if (!resp.ok) {
+				const message = await getHubResponseErrorMessage(resp);
 				tui.fatal(
-					`Hub returned ${resp.status}: ${resp.statusText}. Is the Coder Hub running at ${hubUrl}?`,
+					`Hub returned ${resp.status}: ${message}. Is the Coder Hub running at ${hubUrl}?`,
 					ErrorCode.API_ERROR
 				);
 				return;
@@ -126,7 +149,7 @@ export const inspectSubcommand = createSubcommand({
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			tui.fatal(
-				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\nSet AGENTUITY_CODER_HUB_URL or start the Hub with: bun run dev`,
+				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\n${getHubUrlSetupGuidance()}`,
 				ErrorCode.NETWORK_ERROR
 			);
 			return;

package/src/cmd/coder/list.ts

@@ -3,7 +3,17 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
 import { ErrorCode } from '../../errors';
-import { resolveHubUrl, hubFetchHeaders } from './hub-url';
+import {
+	clearStoredHubApiKeyOnUnauthorized,
+	formatHubUnauthorizedMessage,
+	formatMissingHubUrlMessage,
+	getHubResponseErrorMessage,
+	getHubUrlSetupGuidance,
+	hubFetchHeaders,
+	isHubUnauthorizedStatus,
+	resolveHubApiKey,
+	resolveHubUrl,
+} from './hub-url';
 
 function formatRelativeTime(isoDate: string): string {
 	const diffMs = Date.now() - new Date(isoDate).getTime();
@@ -54,17 +64,16 @@ export const listSubcommand = createSubcommand({
 		response: SessionListResponseSchema,
 	},
 	async handler(ctx) {
-		const { options, opts } = ctx;
-		const hubUrl = await resolveHubUrl(opts?.hubUrl);
+		const { options, opts, config } = ctx;
+		const hubUrl = await resolveHubUrl(opts?.hubUrl, config);
 
 		if (!hubUrl) {
-			tui.fatal(
-				'Could not find a running Coder Hub.\n\nEither:\n  - Start the Hub with: bun run dev\n  - Set AGENTUITY_CODER_HUB_URL environment variable\n  - Pass --hub-url flag',
-				ErrorCode.NETWORK_ERROR
-			);
+			tui.fatal(formatMissingHubUrlMessage(), ErrorCode.NETWORK_ERROR);
 			return [];
 		}
 
+		const resolvedHubApiKey = await resolveHubApiKey(config);
+
 		let data: {
 			sessions: {
 				websocket: Array<{
@@ -85,12 +94,26 @@ export const listSubcommand = createSubcommand({
 
 		try {
 			const resp = await fetch(`${hubUrl}/api/hub/sessions`, {
-				headers: hubFetchHeaders(),
+				headers: hubFetchHeaders(undefined, resolvedHubApiKey.apiKey),
 				signal: AbortSignal.timeout(10_000),
 			});
 			if (!resp.ok) {
+				const message = await getHubResponseErrorMessage(resp);
+				if (isHubUnauthorizedStatus(resp.status)) {
+					const clearedStoredKey = await clearStoredHubApiKeyOnUnauthorized(
+						resp.status,
+						resolvedHubApiKey,
+						config
+					);
+					tui.fatal(
+						formatHubUnauthorizedMessage(hubUrl, message, { clearedStoredKey }),
+						ErrorCode.API_ERROR
+					);
+					return [];
+				}
+
 				tui.fatal(
-					`Hub returned ${resp.status}: ${resp.statusText}. Is the Coder Hub running at ${hubUrl}?`,
+					`Hub returned ${resp.status}: ${message}. Is the Coder Hub running at ${hubUrl}?`,
 					ErrorCode.API_ERROR
 				);
 				return [];
@@ -99,7 +122,7 @@ export const listSubcommand = createSubcommand({
 		} catch (err) {
 			const msg = err instanceof Error ? err.message : String(err);
 			tui.fatal(
-				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\nSet AGENTUITY_CODER_HUB_URL or start the Hub with: bun run dev`,
+				`Could not connect to Coder Hub at ${hubUrl}: ${msg}\n\n${getHubUrlSetupGuidance()}`,
 				ErrorCode.NETWORK_ERROR
 			);
 			return [];

package/src/cmd/coder/start.ts

@@ -5,7 +5,17 @@ import { createSubcommand } from '../../types';
 import * as tui from '../../tui';
 import { getCommand } from '../../command-prefix';
 import { ErrorCode } from '../../errors';
-import { toHubWsUrl, resolveHubUrl, hubFetchHeaders } from './hub-url';
+import {
+	clearStoredHubApiKeyOnUnauthorized,
+	formatHubUnauthorizedMessage,
+	formatMissingHubUrlMessage,
+	getHubResponseErrorMessage,
+	hubFetchHeaders,
+	isHubUnauthorizedStatus,
+	resolveHubApiKey,
+	resolveHubUrl,
+	toHubWsUrl,
+} from './hub-url';
 import { probeHubInitAccess } from './tui-init';
 
 /**
@@ -127,24 +137,44 @@ export const startSubcommand = createSubcommand({
 		}),
 	},
 	async handler(ctx) {
-		const { opts, options } = ctx;
+		const { opts, options, config } = ctx;
 
 		// Resolve Hub URL
-		const hubHttpUrl = await resolveHubUrl(opts?.hubUrl);
+		const hubHttpUrl = await resolveHubUrl(opts?.hubUrl, config);
 		if (!hubHttpUrl) {
-			tui.fatal(
-				'Could not find a running Coder Hub.\n\nEither:\n  - Start the Hub with: bun run dev\n  - Set AGENTUITY_CODER_HUB_URL environment variable\n  - Pass --hub-url flag',
-				ErrorCode.NETWORK_ERROR
-			);
+			tui.fatal(formatMissingHubUrlMessage(), ErrorCode.NETWORK_ERROR);
 			return;
 		}
 		const hubWsUrl = toHubWsUrl(hubHttpUrl);
+		const resolvedHubApiKey = await resolveHubApiKey(config);
+
+		const handleUnauthorizedResponse = async (
+			response: Response,
+			errorCode: ErrorCode = ErrorCode.NETWORK_ERROR
+		): Promise<void> => {
+			const message = await getHubResponseErrorMessage(response);
+			const clearedStoredKey = await clearStoredHubApiKeyOnUnauthorized(
+				response.status,
+				resolvedHubApiKey,
+				config
+			);
+			tui.fatal(
+				formatHubUnauthorizedMessage(hubHttpUrl, message, { clearedStoredKey }),
+				errorCode
+			);
+		};
 
-		const initProbe = await probeHubInitAccess(hubHttpUrl);
+		const initProbe = await probeHubInitAccess(hubHttpUrl, {
+			apiKey: resolvedHubApiKey.apiKey,
+		});
 		if (!initProbe.ok) {
 			if (initProbe.code === 'unauthorized') {
+				const clearedStoredKey =
+					resolvedHubApiKey.source === 'stored'
+						? await clearStoredHubApiKeyOnUnauthorized(401, resolvedHubApiKey, config)
+						: false;
 				tui.fatal(
-					`Coder Hub at ${hubHttpUrl} requires authentication.\n\nSet AGENTUITY_CODER_API_KEY in your shell and retry.\n\nServer said: ${initProbe.message}`,
+					formatHubUnauthorizedMessage(hubHttpUrl, initProbe.message, { clearedStoredKey }),
 					ErrorCode.NETWORK_ERROR
 				);
 				return;
@@ -192,11 +222,15 @@ export const startSubcommand = createSubcommand({
 						message: 'Fetching connectable sessions…',
 						callback: async () => {
 							const resp = await fetch(`${hubHttpUrl}/api/hub/sessions/connectable`, {
-								headers: hubFetchHeaders(),
+								headers: hubFetchHeaders(undefined, resolvedHubApiKey.apiKey),
 								signal: AbortSignal.timeout(10_000),
 							});
+							if (isHubUnauthorizedStatus(resp.status)) {
+								await handleUnauthorizedResponse(resp);
+								throw new Error('Hub authentication failed');
+							}
 							if (!resp.ok) {
-								throw new Error(`${resp.status} ${resp.statusText}`);
+								throw new Error(`${resp.status} ${await getHubResponseErrorMessage(resp)}`);
 							}
 							const data = (await resp.json()) as { sessions: SessionInfo[] };
 							return data.sessions;
@@ -205,7 +239,7 @@ export const startSubcommand = createSubcommand({
 
 					if (sessions.length === 0) {
 						tui.fatal(
-							'No connectable sandbox sessions found.\n\nCreate one with: ag-dev coder session create --task "your task"',
+							`No connectable sandbox sessions found.\n\nCreate one with:\n  ${getCommand('coder start --sandbox "your task"')}`,
 							ErrorCode.CONFIG_INVALID
 						);
 						return;
@@ -229,7 +263,7 @@ export const startSubcommand = createSubcommand({
 					});
 				} catch (err) {
 					const msg = err instanceof Error ? err.message : String(err);
-					if (msg === 'User cancelled') return;
+					if (msg === 'User cancelled' || msg === 'Hub authentication failed') return;
 					tui.fatal(`Failed to fetch connectable sessions: ${msg}`, ErrorCode.NETWORK_ERROR);
 					return;
 				}
@@ -273,12 +307,6 @@ export const startSubcommand = createSubcommand({
 				return;
 			}
 
-			const hubHttpUrl = await resolveHubUrl(opts?.hubUrl);
-			if (!hubHttpUrl) {
-				tui.fatal('Could not find Hub URL for sandbox creation.', ErrorCode.NETWORK_ERROR);
-				return;
-			}
-
 			// Build request body
 			const body: Record<string, unknown> = { task };
 			if (opts?.repo) {
@@ -293,14 +321,20 @@ export const startSubcommand = createSubcommand({
 			try {
 				const resp = await fetch(`${hubHttpUrl}/api/hub/session`, {
 					method: 'POST',
-					headers: hubFetchHeaders({ 'Content-Type': 'application/json' }),
+					headers: hubFetchHeaders(
+						{ 'Content-Type': 'application/json' },
+						resolvedHubApiKey.apiKey
+					),
 					body: JSON.stringify(body),
 					signal: AbortSignal.timeout(10_000),
 				});
+				if (isHubUnauthorizedStatus(resp.status)) {
+					await handleUnauthorizedResponse(resp);
+					return;
+				}
 				if (!resp.ok) {
-					const errText = await resp.text();
 					tui.fatal(
-						`Failed to create sandbox session: ${resp.status} ${errText}`,
+						`Failed to create sandbox session: ${resp.status} ${await getHubResponseErrorMessage(resp)}`,
 						ErrorCode.NETWORK_ERROR
 					);
 					return;
@@ -328,9 +362,13 @@ export const startSubcommand = createSubcommand({
 				await new Promise((r) => setTimeout(r, POLL_INTERVAL));
 				try {
 					const pollResp = await fetch(`${hubHttpUrl}/api/hub/session/${sessionId}`, {
-						headers: hubFetchHeaders(),
+						headers: hubFetchHeaders(undefined, resolvedHubApiKey.apiKey),
 						signal: AbortSignal.timeout(5_000),
 					});
+					if (isHubUnauthorizedStatus(pollResp.status)) {
+						await handleUnauthorizedResponse(pollResp);
+						return;
+					}
 					if (pollResp.ok) {
 						const data = (await pollResp.json()) as {
 							participants?: Array<{ role: string }>;
@@ -374,9 +412,7 @@ export const startSubcommand = createSubcommand({
 			...(process.env as Record<string, string>),
 			AGENTUITY_CODER_HUB_URL: hubWsUrl,
 		};
-		// TODO: Remove/Change when we get Agentuity service level auth enabled, this is just temporary
-		const cliApiKey = process.env.AGENTUITY_CODER_API_KEY;
-		if (cliApiKey) env.AGENTUITY_CODER_API_KEY = cliApiKey;
+		if (resolvedHubApiKey.apiKey) env.AGENTUITY_CODER_API_KEY = resolvedHubApiKey.apiKey;
 
 		if (opts?.agent) {
 			env.AGENTUITY_CODER_AGENT = opts.agent;

package/src/cmd/coder/tui-init.ts

@@ -21,11 +21,16 @@ function normalizeErrorMessage(payload: unknown, fallback: string): string {
 
 export async function probeHubInitAccess(
 	hubHttpUrl: string,
-	fetchImpl: typeof fetch = fetch
+	options?: {
+		apiKey?: string | null;
+		fetchImpl?: typeof fetch;
+	}
 ): Promise<HubInitProbeResult> {
+	const fetchImpl = options?.fetchImpl ?? fetch;
+
 	try {
 		const response = await fetchImpl(`${hubHttpUrl}/api/hub/init`, {
-			headers: hubFetchHeaders({ accept: 'application/json' }),
+			headers: hubFetchHeaders({ accept: 'application/json' }, options?.apiKey),
 			signal: AbortSignal.timeout(5_000),
 		});
 

package/src/cmd/dev/index.ts

@@ -552,6 +552,7 @@ export const command = createCommand({
 					port: viteInternalPort,
 					backendPort: bunBackendPort,
 					routePaths,
+					liveHostname: devmode?.hostname,
 				});
 				viteServer = viteResult.server;
 				vitePort = viteResult.port;

package/src/cmd/dev/sync.ts

@@ -169,7 +169,7 @@ class DevmodeSyncService implements IDevmodeSyncService {
 					}
 				}
 			}
-			this.logger.debug('Previous metadata found with %d eval(s)', prevEvalCount);
+			this.logger.debug('Previous metadata found with %d evaluations', prevEvalCount);
 		} else {
 			this.logger.debug('No previous metadata, all evals will be treated as new');
 		}
@@ -182,7 +182,7 @@ class DevmodeSyncService implements IDevmodeSyncService {
 			if (agent.evals) {
 				currentEvalCount += agent.evals.length;
 				this.logger.debug(
-					'[CLI EVAL SYNC] Agent "%s" has %d eval(s)',
+					'[CLI EVAL SYNC] Agent "%s" has %d evaluations',
 					agent.name,
 					agent.evals.length
 				);
@@ -196,7 +196,7 @@ class DevmodeSyncService implements IDevmodeSyncService {
 				}
 			}
 		}
-		this.logger.debug('[CLI EVAL SYNC] Total current eval(s): %d', currentEvalCount);
+		this.logger.debug('[CLI EVAL SYNC] Total current evaluations: %d', currentEvalCount);
 
 		// Get agents and evals to sync using shared diff logic
 		const { create: agentsToCreate, delete: agentsToDelete } = getAgentsToSync(
@@ -241,7 +241,7 @@ class DevmodeSyncService implements IDevmodeSyncService {
 			}
 			if (evalsToCreate.length > 0 || evalsToDelete.length > 0) {
 				this.logger.debug(
-					'Successfully bulk synced %d eval(s) to create, %d eval(s) to delete',
+					'Successfully bulk synced %d evaluations to create, %d evaluations to delete',
 					evalsToCreate.length,
 					evalsToDelete.length
 				);
@@ -369,7 +369,7 @@ class MockDevmodeSyncService implements IDevmodeSyncService {
 
 		if (evalsToCreate.length > 0 || evalsToDelete.length > 0) {
 			this.logger.debug(
-				'[MOCK] Would make request: POST /cli/devmode/eval with %d eval(s) to create, %d eval(s) to delete',
+				'[MOCK] Would make request: POST /cli/devmode/eval with %d evaluations to create, %d evaluations to delete',
 				evalsToCreate.length,
 				evalsToDelete.length
 			);

package/src/coder-config.ts

@@ -0,0 +1,141 @@
+import { defaultProfileName, getOrInitConfig, loadConfig, saveConfig } from './config';
+import { normalizeCoderHubHttpUrl } from './coder-hub-url';
+import {
+	deleteCoderApiKeyFromKeychain,
+	getCoderApiKeyFromKeychain,
+	isMacOS,
+	saveCoderApiKeyToKeychain,
+} from './keychain';
+import type { Config } from './types';
+
+function getProfileName(config?: Config | null): string {
+	return config?.name || defaultProfileName;
+}
+
+function pruneCoderConfig(config: Config): void {
+	if (!config.coder) return;
+
+	const nextCoder = { ...config.coder };
+	if (!nextCoder.hubUrl) delete nextCoder.hubUrl;
+	if (!nextCoder.apiKey) delete nextCoder.apiKey;
+
+	if (Object.keys(nextCoder).length === 0) {
+		delete config.coder;
+		return;
+	}
+
+	config.coder = nextCoder;
+}
+
+export async function saveCoderHubUrl(
+	hubUrl: string
+): Promise<{ profileName: string; hubUrl: string }> {
+	const normalized = normalizeCoderHubHttpUrl(hubUrl);
+	const config = await getOrInitConfig();
+	const profileName = getProfileName(config);
+
+	config.coder = {
+		...config.coder,
+		hubUrl: normalized,
+	};
+
+	await saveConfig(config);
+	return { profileName, hubUrl: normalized };
+}
+
+export async function getStoredCoderHubUrl(config?: Config | null): Promise<string | null> {
+	const loadedConfig = config ?? (await loadConfig());
+	const hubUrl = loadedConfig?.coder?.hubUrl?.trim();
+	if (!hubUrl) return null;
+	return normalizeCoderHubHttpUrl(hubUrl);
+}
+
+export async function saveCoderApiKey(apiKey: string): Promise<{ profileName: string }> {
+	const trimmed = apiKey.trim();
+	const config = await getOrInitConfig();
+	const profileName = getProfileName(config);
+
+	if (isMacOS()) {
+		try {
+			await saveCoderApiKeyToKeychain(profileName, trimmed);
+			if (config.coder?.apiKey) {
+				config.coder = {
+					...config.coder,
+				};
+				delete config.coder.apiKey;
+			}
+			pruneCoderConfig(config);
+			await saveConfig(config);
+			return { profileName };
+		} catch {
+			// Fall back to config-file storage below.
+		}
+	}
+
+	config.coder = {
+		...config.coder,
+		apiKey: trimmed,
+	};
+
+	await saveConfig(config);
+	return { profileName };
+}
+
+export async function getStoredCoderApiKey(config?: Config | null): Promise<string | null> {
+	const loadedConfig = config ?? (await loadConfig());
+	const profileName = getProfileName(loadedConfig);
+
+	if (isMacOS()) {
+		try {
+			const keychainValue = await getCoderApiKeyFromKeychain(profileName);
+			if (keychainValue) {
+				if (loadedConfig?.coder?.apiKey) {
+					const configCopy = {
+						...loadedConfig,
+						coder: {
+							...loadedConfig.coder,
+						},
+					};
+					delete configCopy.coder.apiKey;
+					pruneCoderConfig(configCopy);
+					await saveConfig(configCopy);
+				}
+				return keychainValue.trim() || null;
+			}
+		} catch {
+			// Fall back to config-file storage below.
+		}
+	}
+
+	const storedValue = loadedConfig?.coder?.apiKey?.trim();
+	return storedValue || null;
+}
+
+export async function clearStoredCoderApiKey(
+	config?: Config | null
+): Promise<{ profileName: string }> {
+	const loadedConfig = config ?? (await getOrInitConfig());
+	const profileName = getProfileName(loadedConfig);
+
+	if (isMacOS()) {
+		try {
+			await deleteCoderApiKeyFromKeychain(profileName);
+		} catch {
+			// Ignore keychain cleanup errors.
+		}
+	}
+
+	if (loadedConfig.coder?.apiKey) {
+		const configToSave = {
+			...loadedConfig,
+			coder: {
+				...loadedConfig.coder,
+			},
+		};
+		delete configToSave.coder.apiKey;
+		pruneCoderConfig(configToSave);
+		await saveConfig(configToSave);
+	}
+
+	return { profileName };
+}

package/src/coder-hub-url.ts

@@ -0,0 +1,32 @@
+export function normalizeCoderHubHttpUrl(url: string): string {
+	let normalized = url.trim().replace(/\/+$/, '');
+
+	if (normalized.startsWith('ws://')) normalized = 'http://' + normalized.slice(5);
+	else if (normalized.startsWith('wss://')) normalized = 'https://' + normalized.slice(6);
+
+	normalized = normalized.replace(/\/api\/ws\b.*$/, '');
+	normalized = normalized.replace(/\/ws\b.*$/, '');
+	normalized = normalized.replace(/\/api\/hub\b.*$/, '');
+
+	return normalized.replace(/\/+$/, '');
+}
+
+export function toCoderHubWsUrl(hubHttpUrl: string): string {
+	let wsUrl = hubHttpUrl;
+	if (wsUrl.startsWith('http://')) wsUrl = 'ws://' + wsUrl.slice(7);
+	else if (wsUrl.startsWith('https://')) wsUrl = 'wss://' + wsUrl.slice(8);
+
+	try {
+		const parsed = new URL(wsUrl);
+		if (parsed.pathname !== '/api/ws') {
+			parsed.pathname = '/api/ws';
+			wsUrl = parsed.toString().replace(/\/$/, '');
+		}
+	} catch {
+		if (!wsUrl.endsWith('/api/ws')) {
+			wsUrl = wsUrl.replace(/\/?$/, '/api/ws');
+		}
+	}
+
+	return wsUrl;
+}

package/src/config.ts

@@ -28,6 +28,14 @@ import { ConfigSchema, ProjectSchema } from './types';
 export const defaultProfileName = 'production';
 
 export function getDefaultConfigDir(): string {
+	const configDirOverride = process.env.AGENTUITY_CONFIG_DIR?.trim();
+	if (configDirOverride) {
+		if (configDirOverride.startsWith('~/')) {
+			return resolve(join(homedir(), configDirOverride.slice(2)));
+		}
+		return resolve(configDirOverride);
+	}
+
 	return join(homedir(), '.config', 'agentuity');
 }
 
@@ -144,6 +152,11 @@ let cachedConfig: Config | null | undefined;
 // Track the resolved config path so saveConfig writes back to the same file
 let cachedConfigPath: string | undefined;
 
+export function resetConfigCache(): void {
+	cachedConfig = undefined;
+	cachedConfigPath = undefined;
+}
+
 export async function loadConfig(
 	customPath?: string,
 	skipCache = false,