@agentuity/cli 2.0.5 → 2.0.7

package/src/cmd/cloud/task/list.ts

@@ -1,9 +1,9 @@
 import { z } from 'zod';
 import { createCommand } from '../../../types';
 import * as tui from '../../../tui';
-import { createStorageAdapter } from './util';
+import { createStorageAdapter, resolveMeId } from './util';
 import { getCommand } from '../../../command-prefix';
-import type { TaskPriority, TaskStatus, TaskType, Task } from '@agentuity/core';
+import type { TaskPriority, TaskStatus, TaskType, Task, TaskIncludeField } from '@agentuity/core';
 
 const TaskListResponseSchema = z.object({
 	success: z.boolean().describe('Whether the operation succeeded'),
@@ -14,6 +14,12 @@ const TaskListResponseSchema = z.object({
 			type: z.string(),
 			status: z.string(),
 			priority: z.string(),
+			description: z.string().optional(),
+			metadata: z.record(z.string(), z.unknown()).optional(),
+			tags: z.array(z.object({ id: z.string(), name: z.string() })).optional(),
+			subtask_count: z.number().optional(),
+			created_id: z.string().optional(),
+			deleted: z.boolean().optional(),
 			creator: z
 				.object({
 					id: z.string(),
@@ -73,6 +79,38 @@ function truncate(s: string, max: number): string {
 	return `${s.slice(0, max - 1)}…`;
 }
 
+const VALID_INCLUDE_FIELDS = new Set<TaskIncludeField>([
+	'description',
+	'metadata',
+	'tags',
+	'subtask_count',
+	'created_id',
+	'deleted',
+]);
+
+function parseIncludeParam(include: string | undefined): TaskIncludeField[] | undefined {
+	if (!include) return undefined;
+	const fields: TaskIncludeField[] = [];
+	for (const f of include.split(',')) {
+		const trimmed = f.trim() as TaskIncludeField;
+		if (VALID_INCLUDE_FIELDS.has(trimmed)) {
+			fields.push(trimmed);
+		} else {
+			tui.fatal(
+				`Invalid include field: "${trimmed}". Valid fields are: ${[...VALID_INCLUDE_FIELDS].join(', ')}`
+			);
+		}
+	}
+	return fields.length > 0 ? fields : undefined;
+}
+
+function hasIncludeField(
+	include: TaskIncludeField[] | undefined,
+	field: TaskIncludeField
+): boolean {
+	return include?.includes(field) ?? false;
+}
+
 export const listSubcommand = createCommand({
 	name: 'list',
 	aliases: ['ls'],
@@ -103,6 +141,14 @@ export const listSubcommand = createCommand({
 			command: getCommand('cloud task list --assigned-id agent_001 --limit 10'),
 			description: 'List first 10 tasks assigned to an agent',
 		},
+		{
+			command: getCommand('cloud task list --created-id me --include description,metadata,tags'),
+			description: 'List tasks created by me with full details',
+		},
+		{
+			command: getCommand('cloud task list --project-id proj_abc123'),
+			description: 'List tasks for a specific project',
+		},
 	],
 	schema: {
 		options: z.object({
@@ -118,8 +164,24 @@ export const listSubcommand = createCommand({
 				.enum(['high', 'medium', 'low', 'none'])
 				.optional()
 				.describe('filter by priority'),
-			assignedId: z.string().optional().describe('filter by assigned agent or user ID'),
+			assignedId: z
+				.string()
+				.optional()
+				.describe('filter by assigned agent or user ID (use "me" for current user)'),
+			createdId: z
+				.string()
+				.optional()
+				.describe('filter by creator ID (use "me" for current user)'),
 			parentId: z.string().optional().describe('filter by parent task ID'),
+			projectId: z.string().optional().describe('filter by project ID'),
+			tagId: z.string().optional().describe('filter by tag ID'),
+			deleted: z.boolean().optional().describe('include soft-deleted tasks'),
+			include: z
+				.string()
+				.optional()
+				.describe(
+					'comma-separated fields to include: description,metadata,tags,subtask_count,created_id,deleted'
+				),
 			sort: z
 				.enum(['created_at', 'updated_at', 'priority'])
 				.optional()
@@ -127,6 +189,7 @@ export const listSubcommand = createCommand({
 			order: z.enum(['asc', 'desc']).optional().describe('sort order (default: desc)'),
 			limit: z.coerce.number().optional().describe('max results to return (default: 50)'),
 			offset: z.coerce.number().optional().describe('offset for pagination'),
+			orgId: z.string().optional().describe('organization ID (uses default if not specified)'),
 		}),
 		response: TaskListResponseSchema,
 	},
@@ -136,12 +199,22 @@ export const listSubcommand = createCommand({
 		const started = Date.now();
 		const storage = await createStorageAdapter(ctx);
 
+		const createdId = resolveMeId(opts.createdId, ctx);
+		const assignedId = resolveMeId(opts.assignedId, ctx);
+
+		const includeFields = parseIncludeParam(opts.include);
+
 		const result = await storage.list({
 			status: opts.status as TaskStatus | undefined,
 			type: opts.type as TaskType | undefined,
 			priority: opts.priority as TaskPriority | undefined,
-			assigned_id: opts.assignedId,
+			assigned_id: assignedId,
+			created_id: createdId,
 			parent_id: opts.parentId,
+			project_id: opts.projectId,
+			tag_id: opts.tagId,
+			deleted: opts.deleted,
+			include: includeFields,
 			sort: opts.sort,
 			order: opts.order,
 			limit: opts.limit,
@@ -154,6 +227,10 @@ export const listSubcommand = createCommand({
 			if (result.tasks.length === 0) {
 				tui.info('No tasks found');
 			} else {
+				const showDescription = hasIncludeField(includeFields, 'description');
+				const showTags = hasIncludeField(includeFields, 'tags');
+				const showMetadata = hasIncludeField(includeFields, 'metadata');
+
 				const tableData = result.tasks.map((task: Task) => ({
 					ID: tui.muted(truncate(task.id, 28)),
 					Title: truncate(task.title, 40),
@@ -176,6 +253,30 @@ export const listSubcommand = createCommand({
 					{ name: 'Updated', alignment: 'left' },
 				]);
 
+				// Show extra details for each task if included
+				if (showDescription || showTags || showMetadata) {
+					for (const task of result.tasks) {
+						const extras: string[] = [];
+						if (showDescription && task.description) {
+							extras.push(`${tui.muted('Desc:')} ${truncate(task.description, 80)}`);
+						}
+						if (showTags && task.tags && task.tags.length > 0) {
+							const tagList = task.tags.map((t) => t.name).join(', ');
+							extras.push(`${tui.muted('Tags:')} ${tagList}`);
+						}
+						if (showMetadata && task.metadata) {
+							const metaStr =
+								typeof task.metadata === 'object'
+									? JSON.stringify(task.metadata)
+									: String(task.metadata);
+							extras.push(`${tui.muted('Meta:')} ${truncate(metaStr, 80)}`);
+						}
+						if (extras.length > 0) {
+							tui.output(`  ${tui.muted(truncate(task.id, 28))} → ${extras.join(' | ')}`);
+						}
+					}
+				}
+
 				tui.info(
 					`Showing ${result.tasks.length} of ${result.total} ${tui.plural(result.total, 'task', 'tasks')} (${durationMs.toFixed(1)}ms)`
 				);
@@ -190,6 +291,12 @@ export const listSubcommand = createCommand({
 				type: task.type,
 				status: task.status,
 				priority: task.priority,
+				description: task.description,
+				metadata: task.metadata,
+				tags: task.tags,
+				subtask_count: task.subtask_count,
+				created_id: task.created_id,
+				deleted: task.deleted,
 				creator: task.creator,
 				assignee: task.assignee,
 				project: task.project,

package/src/cmd/cloud/task/util.ts

@@ -11,11 +11,14 @@ export interface TaskContext {
 	auth: AuthData;
 	config: Config | null;
 	options: GlobalOptions;
+	project?: {
+		projectId: string;
+		orgId: string;
+	};
 }
 
 export async function createStorageAdapter(ctx: TaskContext) {
-	const orgId =
-		ctx.options.orgId ?? (process.env.AGENTUITY_CLOUD_ORG_ID || ctx.config?.preferences?.orgId);
+	const orgId = resolveOrgId(ctx);
 	if (!orgId) {
 		tui.fatal('Organization ID is required. Use --org-id flag or set AGENTUITY_CLOUD_ORG_ID.');
 	}
@@ -37,8 +40,7 @@ export async function createStorageAdapter(ctx: TaskContext) {
 }
 
 export async function createStorageAdapterOptionalOrg(ctx: TaskContext) {
-	const orgId =
-		ctx.options.orgId ?? (process.env.AGENTUITY_CLOUD_ORG_ID || ctx.config?.preferences?.orgId);
+	const orgId = resolveOrgId(ctx);
 
 	const headers: Record<string, string> = {
 		Authorization: `Bearer ${ctx.auth.apiKey}`,
@@ -54,17 +56,30 @@ export async function createStorageAdapterOptionalOrg(ctx: TaskContext) {
 	return new TaskStorageService(baseUrl, adapter);
 }
 
+function resolveOrgId(ctx: TaskContext): string | undefined {
+	return (
+		ctx.options.orgId ??
+		process.env.AGENTUITY_CLOUD_ORG_ID ??
+		ctx.project?.orgId ??
+		ctx.config?.preferences?.orgId
+	);
+}
+
 export async function cacheTaskId(
 	ctx: {
 		config: Config | null;
 		options: GlobalOptions;
+		project?: { orgId: string };
 	},
 	taskId: string
 ) {
 	const profileName = ctx.config?.name ?? defaultProfileName;
 	const region = await getDefaultRegion(profileName, ctx.config);
 	const orgId =
-		ctx.options.orgId ?? (process.env.AGENTUITY_CLOUD_ORG_ID || ctx.config?.preferences?.orgId);
+		ctx.options.orgId ??
+		process.env.AGENTUITY_CLOUD_ORG_ID ??
+		ctx.project?.orgId ??
+		ctx.config?.preferences?.orgId;
 	await setResourceInfo('task', profileName, taskId, region, orgId);
 }
 
@@ -76,3 +91,42 @@ export function parseMetadataFlag(raw: string | undefined): Record<string, unkno
 		tui.fatal('Invalid JSON for --metadata flag');
 	}
 }
+
+const DURATION_UNITS: Record<string, number> = {
+	s: 1000,
+	m: 60 * 1000,
+	h: 60 * 60 * 1000,
+	d: 24 * 60 * 60 * 1000,
+	w: 7 * 24 * 60 * 60 * 1000,
+};
+
+export function parseDuration(duration: string): number {
+	const match = duration.match(/^(\d+)([smhdw])$/);
+	if (!match) {
+		tui.fatal(
+			`Invalid duration format: "${duration}". Use a number followed by s (seconds), m (minutes), h (hours), d (days), or w (weeks). Examples: 30s, 30m, 24h, 7d, 2w`
+		);
+		throw new Error('unreachable');
+	}
+	const value = parseInt(match[1]!, 10);
+	const unit = match[2]!;
+	const ms = DURATION_UNITS[unit];
+	if (!ms) {
+		tui.fatal(`Unknown duration unit: "${unit}"`);
+		throw new Error('unreachable');
+	}
+	return value * ms;
+}
+
+export function truncate(s: string, max: number): string {
+	if (s.length <= max) return s;
+	return `${s.slice(0, max - 1)}…`;
+}
+
+export function resolveMeId(id: string | undefined, ctx: TaskContext): string | undefined {
+	if (!id) return undefined;
+	if (id === 'me') {
+		return ctx.auth.userId;
+	}
+	return id;
+}

package/src/cmd/coder/config/index.ts

@@ -0,0 +1,20 @@
+import { createCommand } from '../../../types';
+import { getCommand } from '../../../command-prefix';
+import { setSubcommand } from './set';
+
+export const configSubcommand = createCommand({
+	name: 'config',
+	description: 'Manage stored Coder Hub configuration',
+	tags: ['fast'],
+	examples: [
+		{
+			command: getCommand('coder config set url https://hub.example.com'),
+			description: 'Set the default Coder Hub URL for the active profile',
+		},
+		{
+			command: getCommand('coder config set apikey agc_...'),
+			description: 'Set the default Coder Hub API key for the active profile',
+		},
+	],
+	subcommands: [setSubcommand],
+});

package/src/cmd/coder/config/set.ts

@@ -0,0 +1,112 @@
+import { z } from 'zod';
+import { saveCoderApiKey, saveCoderHubUrl } from '../../../coder-config';
+import { normalizeCoderHubHttpUrl } from '../../../coder-hub-url';
+import { getCommand } from '../../../command-prefix';
+import * as tui from '../../../tui';
+import { createCommand, createSubcommand } from '../../../types';
+
+const setUrlSubcommand = createSubcommand({
+	name: 'url',
+	description: 'Set the default Coder Hub URL for the active profile',
+	tags: ['mutating', 'fast'],
+	examples: [
+		{
+			command: getCommand('coder config set url https://hub.example.com'),
+			description: 'Set the default Coder Hub URL',
+		},
+		{
+			command: getCommand('coder config set url ws://127.0.0.1:3650/api/ws'),
+			description: 'Store a local dev Hub URL using a WebSocket input',
+		},
+	],
+	schema: {
+		args: z.object({
+			url: z.string().min(1).describe('Hub URL to store for the active profile'),
+		}),
+		response: z.object({
+			profile: z.string().describe('Active CLI profile name'),
+			hubUrl: z.string().describe('Normalized stored Hub HTTP URL'),
+		}),
+	},
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const normalized = normalizeCoderHubHttpUrl(args.url);
+
+		try {
+			new URL(normalized);
+		} catch {
+			tui.fatal(
+				`Invalid Hub URL: ${args.url}\n\nExpected a full URL such as https://hub.example.com or ws://127.0.0.1:3650/api/ws`
+			);
+		}
+
+		const result = await saveCoderHubUrl(normalized);
+
+		if (!options.json) {
+			tui.success(
+				`Default Coder Hub URL set to ${tui.bold(result.hubUrl)} for profile ${tui.bold(result.profileName)}`
+			);
+		}
+
+		return {
+			profile: result.profileName,
+			hubUrl: result.hubUrl,
+		};
+	},
+});
+
+const setApiKeySubcommand = createSubcommand({
+	name: 'apikey',
+	description: 'Set the default Coder Hub API key for the active profile',
+	tags: ['mutating', 'fast'],
+	examples: [
+		{
+			command: getCommand('coder config set apikey agc_...'),
+			description: 'Set the default Coder Hub API key',
+		},
+	],
+	schema: {
+		args: z.object({
+			apikey: z.string().min(1).describe('Hub API key to store for the active profile'),
+		}),
+		response: z.object({
+			profile: z.string().describe('Active CLI profile name'),
+			stored: z.boolean().describe('Whether the API key was stored successfully'),
+		}),
+	},
+	async handler(ctx) {
+		const { args, options } = ctx;
+		const trimmed = args.apikey.trim();
+		if (!trimmed) {
+			tui.fatal('Hub API key cannot be empty');
+		}
+
+		const result = await saveCoderApiKey(trimmed);
+
+		if (!options.json) {
+			tui.success(`Coder Hub API key stored for profile ${tui.bold(result.profileName)}`);
+		}
+
+		return {
+			profile: result.profileName,
+			stored: true,
+		};
+	},
+});
+
+export const setSubcommand = createCommand({
+	name: 'set',
+	description: 'Set stored Coder Hub configuration values',
+	tags: ['mutating', 'fast'],
+	examples: [
+		{
+			command: getCommand('coder config set url https://hub.example.com'),
+			description: 'Store the default Hub URL',
+		},
+		{
+			command: getCommand('coder config set apikey agc_...'),
+			description: 'Store the default Hub API key',
+		},
+	],
+	subcommands: [setUrlSubcommand, setApiKeySubcommand],
+});

package/src/cmd/coder/hub-url.ts

@@ -4,11 +4,27 @@
  * Resolution priority:
  *   1. --hub-url flag (explicit per-command override)
  *   2. AGENTUITY_CODER_HUB_URL env var
- *   3. AGENTUITY_DEVMODE_URL env var (dev tunnel URL)
+ *   3. Stored per-profile Hub URL
+ *   4. AGENTUITY_DEVMODE_URL env var (dev tunnel URL)
  */
 
+import {
+	clearStoredCoderApiKey,
+	getStoredCoderApiKey,
+	getStoredCoderHubUrl,
+} from '../../coder-config';
+import { normalizeCoderHubHttpUrl, toCoderHubWsUrl } from '../../coder-hub-url';
+import { getCommand } from '../../command-prefix';
+import type { Config } from '../../types';
 import { getVersion } from '../../version';
 
+export type HubApiKeySource = 'env' | 'stored' | 'none';
+
+export interface ResolvedHubApiKey {
+	apiKey: string | null;
+	source: HubApiKeySource;
+}
+
 /**
  * Resolve the Hub HTTP base URL for REST API calls.
  * Converts ws:// URLs to http:// automatically.
@@ -16,17 +32,24 @@ import { getVersion } from '../../version';
  * @param flagUrl  Optional --hub-url flag value
  * @returns HTTP base URL (e.g. "http://localhost:3500") or null if Hub is unreachable
  */
-export async function resolveHubUrl(flagUrl?: string): Promise<string | null> {
+export async function resolveHubUrl(
+	flagUrl?: string,
+	config?: Config | null
+): Promise<string | null> {
 	// 1. Explicit flag
-	if (flagUrl) return normalizeToHttp(flagUrl);
+	if (flagUrl) return normalizeCoderHubHttpUrl(flagUrl);
 
 	// 2. Env var (explicit)
 	const envUrl = process.env.AGENTUITY_CODER_HUB_URL;
-	if (envUrl) return normalizeToHttp(envUrl);
+	if (envUrl) return normalizeCoderHubHttpUrl(envUrl);
+
+	// 3. Stored profile config
+	const storedUrl = await getStoredCoderHubUrl(config);
+	if (storedUrl) return storedUrl;
 
-	// 3. Dev mode URL (tunnel)
+	// 4. Dev mode URL (tunnel)
 	const devUrl = process.env.AGENTUITY_DEVMODE_URL;
-	if (devUrl) return normalizeToHttp(devUrl);
+	if (devUrl) return normalizeCoderHubHttpUrl(devUrl);
 
 	return null;
 }
@@ -38,74 +61,145 @@ export async function resolveHubUrl(flagUrl?: string): Promise<string | null> {
  * @param flagUrl  Optional --hub-url flag value
  * @returns WebSocket URL (e.g. "ws://127.0.0.1:3500/api/ws") or null
  */
-export async function resolveHubWsUrl(flagUrl?: string): Promise<string | null> {
-	const httpUrl = await resolveHubUrl(flagUrl);
+export async function resolveHubWsUrl(
+	flagUrl?: string,
+	config?: Config | null
+): Promise<string | null> {
+	const httpUrl = await resolveHubUrl(flagUrl, config);
 	if (!httpUrl) return null;
 	return toHubWsUrl(httpUrl);
 }
 
 export function toHubWsUrl(hubHttpUrl: string): string {
-	return normalizeToWs(hubHttpUrl);
+	return toCoderHubWsUrl(hubHttpUrl);
 }
 
 /**
- * Convert any URL form to an HTTP base URL (strip paths, convert ws->http).
+ * Resolve the API key for Hub authentication.
  */
-function normalizeToHttp(url: string): string {
-	let normalized = url.trim().replace(/\/+$/, '');
+function resolveEnvApiKey(): string | null {
+	return process.env.AGENTUITY_CODER_API_KEY || null;
+}
 
-	// ws:// -> http://
-	if (normalized.startsWith('ws://')) normalized = 'http://' + normalized.slice(5);
-	else if (normalized.startsWith('wss://')) normalized = 'https://' + normalized.slice(6);
+export async function resolveHubApiKey(config?: Config | null): Promise<ResolvedHubApiKey> {
+	const envApiKey = resolveEnvApiKey();
+	if (envApiKey) {
+		return {
+			apiKey: envApiKey,
+			source: 'env',
+		};
+	}
 
-	// Strip known Hub transport/helper paths to get the HTTP base URL.
-	// Accept `/ws` as a convenience alias because users often copy the raw route name.
-	normalized = normalized.replace(/\/api\/ws\b.*$/, '');
-	normalized = normalized.replace(/\/ws\b.*$/, '');
-	normalized = normalized.replace(/\/api\/hub\b.*$/, '');
+	const storedApiKey = await getStoredCoderApiKey(config);
+	if (storedApiKey) {
+		return {
+			apiKey: storedApiKey,
+			source: 'stored',
+		};
+	}
 
-	return normalized.replace(/\/+$/, '');
+	return {
+		apiKey: null,
+		source: 'none',
+	};
 }
 
 /**
- * Convert an HTTP base URL to a WebSocket URL with /api/ws path.
+ * Build headers object with API key if available.
  */
-function normalizeToWs(httpUrl: string): string {
-	let wsUrl = httpUrl;
-	if (wsUrl.startsWith('http://')) wsUrl = 'ws://' + wsUrl.slice(7);
-	else if (wsUrl.startsWith('https://')) wsUrl = 'wss://' + wsUrl.slice(8);
+export function hubFetchHeaders(
+	extra?: Record<string, string>,
+	apiKey?: string | null
+): Record<string, string> {
+	const headers: Record<string, string> = { ...extra };
+	headers['User-Agent'] = `Agentuity Coder/${getVersion()}`;
+	const resolvedApiKey = apiKey === undefined ? resolveEnvApiKey() : apiKey;
+	if (resolvedApiKey) headers['x-agentuity-auth-api-key'] = resolvedApiKey;
+	return headers;
+}
 
-	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');
-		}
+export function isHubUnauthorizedStatus(status: number): boolean {
+	return status === 401 || status === 403;
+}
+
+export async function clearStoredHubApiKeyOnUnauthorized(
+	status: number,
+	resolvedApiKey: ResolvedHubApiKey,
+	config?: Config | null,
+	clearStoredApiKey: (config?: Config | null) => Promise<unknown> = clearStoredCoderApiKey
+): Promise<boolean> {
+	if (!isHubUnauthorizedStatus(status) || resolvedApiKey.source !== 'stored') {
+		return false;
 	}
 
-	return wsUrl;
+	await clearStoredApiKey(config);
+	return true;
 }
 
-/**
- * Resolve the API key for Hub authentication.
- * TODO: Remove/Change when we get Agentuity service level auth enabled, this is just temporary
- */
-export function resolveApiKey(): string | null {
-	return process.env.AGENTUITY_CODER_API_KEY || null;
+export function getHubUrlSetupGuidance(): string {
+	return (
+		`Set a default Hub URL with:\n` +
+		`  ${getCommand('coder config set url <url>')}\n\n` +
+		`Or pass --hub-url for a one-off override, or use AGENTUITY_CODER_HUB_URL.`
+	);
 }
 
-/**
- * Build headers object with API key if available.
- * TODO: Remove/Change when we get Agentuity service level auth enabled, this is just temporary
- */
-export function hubFetchHeaders(extra?: Record<string, string>): Record<string, string> {
-	const headers: Record<string, string> = { ...extra };
-	headers['User-Agent'] = `Agentuity Coder/${getVersion()}`;
-	const apiKey = resolveApiKey();
-	if (apiKey) headers['x-agentuity-auth-api-key'] = apiKey;
-	return headers;
+export function getHubApiKeySetupGuidance(): string {
+	return (
+		`Set a Hub API key with:\n` +
+		`  ${getCommand('coder config set apikey <apikey>')}\n\n` +
+		`Or use AGENTUITY_CODER_API_KEY as an override.`
+	);
+}
+
+export function formatMissingHubUrlMessage(): string {
+	return `Could not find a configured Coder Hub URL.\n\n${getHubUrlSetupGuidance()}`;
+}
+
+export function formatHubUnauthorizedMessage(
+	hubUrl: string,
+	serverMessage: string,
+	options?: {
+		clearedStoredKey?: boolean;
+	}
+): string {
+	const clearedStoredKey = options?.clearedStoredKey ? 'Stored Hub API key cleared.\n\n' : '';
+
+	return (
+		`Coder Hub at ${hubUrl} requires a valid API key.\n\n` +
+		`${clearedStoredKey}${getHubApiKeySetupGuidance()}\n\n` +
+		`Server said: ${serverMessage}`
+	);
+}
+
+export async function getHubResponseErrorMessage(response: Response): Promise<string> {
+	const fallback = `${response.status} ${response.statusText}`;
+
+	try {
+		const payload = (await response.clone().json()) as {
+			error?: unknown;
+			message?: unknown;
+			details?: unknown;
+		};
+		if (typeof payload.error === 'string' && payload.error.trim()) {
+			return payload.error.trim();
+		}
+		if (typeof payload.message === 'string' && payload.message.trim()) {
+			return payload.message.trim();
+		}
+		if (typeof payload.details === 'string' && payload.details.trim()) {
+			return payload.details.trim();
+		}
+	} catch {
+		// Fall back to the response text below.
+	}
+
+	try {
+		const text = (await response.text()).trim();
+		if (text) return text;
+	} catch {
+		// Fall back to the status text below.
+	}
+
+	return fallback;
 }