@agentuity/core 2.0.6 → 2.0.8

package/src/services/coder/users.ts

@@ -0,0 +1,59 @@
+import { z } from 'zod/v4';
+import { type APIClient } from '../api.ts';
+import {
+	CoderListUsersParamsSchema,
+	CoderListUsersResponseSchema,
+	CoderUserSchema,
+	type CoderListUsersParams,
+	type CoderListUsersResponse,
+} from './types.ts';
+
+const CoderListUsersPayloadSchema = z
+	.union([
+		z.array(CoderUserSchema).describe('Array-only users payload from service'),
+		CoderListUsersResponseSchema.describe('Object users payload from service'),
+	])
+	.describe('Raw users list payload shape returned by service');
+
+export const CoderListUsersParamsWithOrgSchema = CoderListUsersParamsSchema.describe(
+	'Parameters for listing coder users'
+);
+export type CoderListUsersParamsWithOrg = z.infer<typeof CoderListUsersParamsWithOrgSchema>;
+
+function normalizeUsers(
+	payload: z.infer<typeof CoderListUsersPayloadSchema>
+): CoderListUsersResponse {
+	if (Array.isArray(payload)) {
+		return {
+			users: payload,
+			total: payload.length,
+		};
+	}
+
+	return CoderListUsersResponseSchema.parse(payload);
+}
+
+export async function coderListUsers(
+	client: APIClient,
+	params?: CoderListUsersParams
+): Promise<CoderListUsersResponse> {
+	const query = new URLSearchParams();
+	if (params?.search) {
+		query.set('search', params.search);
+	}
+	if (params?.limit !== undefined) {
+		query.set('limit', String(params.limit));
+	}
+	if (params?.offset !== undefined) {
+		query.set('offset', String(params.offset));
+	}
+
+	const queryString = query.toString();
+	const path = `/hub/users${queryString ? `?${queryString}` : ''}`;
+	const payload = await client.get<z.infer<typeof CoderListUsersPayloadSchema>>(
+		path,
+		CoderListUsersPayloadSchema
+	);
+
+	return normalizeUsers(payload);
+}

package/src/services/coder/util.ts

@@ -0,0 +1,87 @@
+import { StructuredError } from '../../error.ts';
+import { z } from 'zod/v4';
+
+export const CoderErrorCodeSchema = z
+	.enum([
+		'CODER_SESSION_NOT_FOUND',
+		'CODER_SESSION_ARCHIVED',
+		'CODER_SESSION_CONFLICT',
+		'CODER_INVALID_REQUEST',
+	])
+	.describe('Machine-readable error codes returned by coder APIs');
+export type CoderErrorCode = z.infer<typeof CoderErrorCodeSchema>;
+
+export const CoderResponseError = StructuredError('CoderResponseError')<{
+	/** Coder session id involved in the failed operation */
+	coderSessionId?: string;
+	/** x-session-id header value used for trace correlation */
+	requestSessionId?: string | null;
+	/** Backend machine-readable error code, if provided */
+	code?: CoderErrorCode;
+}>();
+
+export const CoderSessionNotFoundError = StructuredError('CoderSessionNotFoundError')<{
+	coderSessionId: string;
+}>();
+
+export const CoderSessionArchivedError = StructuredError('CoderSessionArchivedError')<{
+	coderSessionId?: string;
+}>();
+
+export const CoderSessionConflictError = StructuredError('CoderSessionConflictError')<{
+	coderSessionId?: string;
+}>();
+
+export const CoderErrorContextSchema = z
+	.object({
+		sessionId: z.string().optional().describe('Coder session id involved in the operation'),
+		requestSessionId: z
+			.string()
+			.nullish()
+			.describe('Request trace session id from x-session-id header'),
+	})
+	.describe('Context used when mapping coder API errors');
+export type CoderErrorContext = z.infer<typeof CoderErrorContextSchema>;
+
+export function throwCoderError(
+	resp: { message?: string; code?: string },
+	context: CoderErrorContext
+): never {
+	const code = resp.code as CoderErrorCode | undefined;
+
+	switch (code) {
+		case 'CODER_SESSION_NOT_FOUND':
+			throw new CoderSessionNotFoundError({
+				message: resp.message,
+				coderSessionId: context.sessionId ?? '',
+			});
+		case 'CODER_SESSION_ARCHIVED':
+			throw new CoderSessionArchivedError({
+				message: resp.message,
+				coderSessionId: context.sessionId,
+			});
+		case 'CODER_SESSION_CONFLICT':
+			throw new CoderSessionConflictError({
+				message: resp.message,
+				coderSessionId: context.sessionId,
+			});
+		default:
+			throw new CoderResponseError({
+				message: resp.message,
+				coderSessionId: context.sessionId,
+				requestSessionId: context.requestSessionId,
+				code,
+			});
+	}
+}
+
+export function normalizeCoderUrl(url: string): string {
+	return url.replace(/\/$/, '');
+}
+
+export function withOrgId(params: URLSearchParams, orgId?: string): URLSearchParams {
+	if (orgId) {
+		params.set('orgId', orgId);
+	}
+	return params;
+}

package/src/services/coder/workspaces.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod/v4';
+import { type APIClient } from '../api.ts';
+import {
+	CoderCreateWorkspaceRequestSchema,
+	CoderWorkspaceDetailSchema,
+	CoderWorkspaceListResponseSchema,
+	type CoderCreateWorkspaceRequest,
+	type CoderWorkspaceDetail,
+	type CoderWorkspaceListResponse,
+} from './types.ts';
+
+const WorkspaceGetResponseSchema = z
+	.object({
+		workspace: CoderWorkspaceDetailSchema.describe('Workspace payload returned by coder hub'),
+	})
+	.passthrough()
+	.describe('Wrapped workspace response from coder hub');
+
+const WorkspaceCreateResponseSchema = z
+	.object({
+		workspace: CoderWorkspaceDetailSchema.describe(
+			'Created workspace payload returned by coder hub'
+		),
+	})
+	.passthrough()
+	.describe('Wrapped workspace create response from coder hub');
+
+const OkResponseSchema = z
+	.object({
+		ok: z.boolean().describe('Operation success indicator'),
+	})
+	.passthrough()
+	.describe('Generic ok response from coder hub');
+
+export async function coderListWorkspaces(client: APIClient): Promise<CoderWorkspaceListResponse> {
+	return client.get<CoderWorkspaceListResponse>(
+		'/hub/workspaces',
+		CoderWorkspaceListResponseSchema
+	);
+}
+
+export async function coderGetWorkspace(
+	client: APIClient,
+	params: { workspaceId: string }
+): Promise<CoderWorkspaceDetail> {
+	const path = `/hub/workspaces/${encodeURIComponent(params.workspaceId)}`;
+	const resp = await client.get<z.infer<typeof WorkspaceGetResponseSchema>>(
+		path,
+		WorkspaceGetResponseSchema
+	);
+	return resp.workspace;
+}
+
+export async function coderCreateWorkspace(
+	client: APIClient,
+	params: { body: CoderCreateWorkspaceRequest }
+): Promise<CoderWorkspaceDetail> {
+	const resp = await client.post<
+		z.infer<typeof WorkspaceCreateResponseSchema>,
+		CoderCreateWorkspaceRequest
+	>(
+		'/hub/workspaces',
+		params.body,
+		WorkspaceCreateResponseSchema,
+		CoderCreateWorkspaceRequestSchema
+	);
+
+	return resp.workspace;
+}
+
+export async function coderDeleteWorkspace(
+	client: APIClient,
+	params: { workspaceId: string }
+): Promise<void> {
+	const path = `/hub/workspaces/${encodeURIComponent(params.workspaceId)}`;
+	await client.delete(path, OkResponseSchema);
+}

package/src/services/index.ts

@@ -9,6 +9,7 @@ export * from './task/index.ts';
 export * from './vector/index.ts';
 
 export * from './config.ts';
+export * from './coder/index.ts';
 export * from './env.ts';
 export * from './logger.ts';
 export * from './api.ts';

package/src/services/oauth/types.ts

@@ -313,6 +313,7 @@ export const OAuthUserInfoSchema = z
 		name: z.string().optional(),
 		given_name: z.string().optional(),
 		family_name: z.string().optional(),
+		picture: z.string().optional(),
 		email: z.string().optional(),
 		email_verified: z.boolean().optional(),
 	})

package/src/services/queue/service.ts

@@ -308,6 +308,14 @@ export interface QueueService {
  */
 export const QueuePublishError = StructuredError('QueuePublishError');
 
+/**
+ * Error thrown when a queue creation operation fails.
+ *
+ * This is a general error for create failures that aren't specifically
+ * validation, not-found, or conflict (409) errors.
+ */
+export const QueueCreateError = StructuredError('QueueCreateError');
+
 /**
  * Error thrown when a queue is not found.
  *
@@ -389,6 +397,33 @@ function validatePayloadInternal(payload: string): void {
 	}
 }
 
+/**
+ * Unwraps the standard API response envelope.
+ *
+ * The queue server returns responses wrapped in:
+ *   { success: true, data: { [key]: { ...actual data... } } }
+ *
+ * Since `fromResponse()` parses the raw JSON body, `res.data` from the
+ * adapter is the full envelope. This helper extracts the nested data by key.
+ *
+ * Falls back to treating the input as already-unwrapped data (e.g., in tests
+ * using mock adapters that provide flat data directly).
+ *
+ * @internal
+ */
+function unwrapApiResponse<T>(data: unknown, key: string): T {
+	if (data !== null && typeof data === 'object') {
+		const body = data as Record<string, unknown>;
+		if (body.success === true && typeof body.data === 'object' && body.data !== null) {
+			const envelope = body.data as Record<string, unknown>;
+			if (key in envelope) {
+				return envelope[key] as T;
+			}
+		}
+	}
+	return data as T;
+}
+
 // ============================================================================
 // QueueStorageService Implementation
 // ============================================================================
@@ -496,16 +531,18 @@ export class QueueStorageService implements QueueService {
 		});
 
 		if (res.ok) {
-			const data = res.data as unknown as {
-				id: string;
-				offset: number;
-				published_at: string;
-			};
-			return {
+			const data = unwrapApiResponse<Record<string, unknown>>(res.data, 'message');
+			const result = QueuePublishResultSchema.safeParse({
 				id: data.id,
 				offset: data.offset,
 				publishedAt: data.published_at,
-			};
+			});
+			if (result.success) {
+				return result.data;
+			}
+			throw new QueuePublishError({
+				message: `Queue publish returned an unexpected response format: ${result.error.message}`,
+			});
 		}
 
 		if (res.response.status === 404) {
@@ -579,12 +616,18 @@ export class QueueStorageService implements QueueService {
 		});
 
 		if (res.ok) {
-			const data = res.data as unknown as Record<string, unknown>;
-			this.#knownQueues.add(queueName);
-			return {
-				name: (data.name as string) ?? queueName,
-				queueType: (data.queue_type as string) ?? params?.queueType ?? 'worker',
-			};
+			const data = unwrapApiResponse<Record<string, unknown>>(res.data, 'queue');
+			const result = QueueCreateResultSchema.safeParse({
+				name: data.name,
+				queueType: data.queue_type,
+			});
+			if (result.success) {
+				this.#knownQueues.add(queueName);
+				return result.data;
+			}
+			throw new QueueCreateError({
+				message: `Queue create returned an unexpected response format: ${result.error.message}`,
+			});
 		}
 
 		if (res.response.status === 409) {

package/src/services/sandbox/client.ts

@@ -257,14 +257,16 @@ export interface SandboxInstance {
 	mkDir(path: string, recursive?: boolean): Promise<void>;
 
 	/**
-	 * Remove a file from the sandbox workspace
+	 * Remove a file from the sandbox workspace.
+	 * @returns Object with `found` indicating whether the file existed before removal
 	 */
-	rmFile(path: string): Promise<void>;
+	rmFile(path: string): Promise<{ found: boolean }>;
 
 	/**
-	 * Remove a directory from the sandbox workspace
+	 * Remove a directory from the sandbox workspace.
+	 * @returns Object with `found` indicating whether the directory existed before removal
 	 */
-	rmDir(path: string, recursive?: boolean): Promise<void>;
+	rmDir(path: string, recursive?: boolean): Promise<{ found: boolean }>;
 
 	/**
 	 * Set environment variables on the sandbox. Pass null to delete a variable.
@@ -380,12 +382,12 @@ function createSandboxInstanceMethods(
 			await sandboxMkDir(client, { sandboxId, path, recursive, orgId });
 		},
 
-		async rmFile(path: string): Promise<void> {
-			await sandboxRmFile(client, { sandboxId, path, orgId });
+		async rmFile(path: string): Promise<{ found: boolean }> {
+			return sandboxRmFile(client, { sandboxId, path, orgId });
 		},
 
-		async rmDir(path: string, recursive?: boolean): Promise<void> {
-			await sandboxRmDir(client, { sandboxId, path, recursive, orgId });
+		async rmDir(path: string, recursive?: boolean): Promise<{ found: boolean }> {
+			return sandboxRmDir(client, { sandboxId, path, recursive, orgId });
 		},
 
 		async setEnv(env: Record<string, string | null>): Promise<Record<string, string>> {

package/src/services/sandbox/files.ts

@@ -217,6 +217,13 @@ export const RmDirResponseSchema = z.discriminatedUnion('success', [
 	}),
 	z.object({
 		success: z.literal<true>(true),
+		found: z
+			.boolean()
+			.optional()
+			.default(true)
+			.describe(
+				'Whether the directory existed before removal. False when already removed (idempotent).'
+			),
 	}),
 ]);
 
@@ -235,9 +242,13 @@ export type RmDirParams = z.infer<typeof RmDirParamsSchema>;
  *
  * @param client - The API client to use for the request
  * @param params - Parameters including sandbox ID, path, and recursive flag
+ * @returns Object with `found` indicating whether the directory existed before removal
  * @throws {SandboxResponseError} If the rmdir request fails
  */
-export async function sandboxRmDir(client: APIClient, params: RmDirParams): Promise<void> {
+export async function sandboxRmDir(
+	client: APIClient,
+	params: RmDirParams
+): Promise<{ found: boolean }> {
 	const { sandboxId, path, recursive, orgId, signal } = params;
 
 	const body: z.infer<typeof RmDirRequestSchema> = {
@@ -263,6 +274,8 @@ export async function sandboxRmDir(client: APIClient, params: RmDirParams): Prom
 	if (!resp.success) {
 		throwSandboxError(resp, { sandboxId });
 	}
+
+	return { found: resp.found };
 }
 
 export const RmFileRequestSchema = z
@@ -278,6 +291,13 @@ export const RmFileResponseSchema = z.discriminatedUnion('success', [
 	}),
 	z.object({
 		success: z.literal<true>(true),
+		found: z
+			.boolean()
+			.optional()
+			.default(true)
+			.describe(
+				'Whether the file existed before removal. False when already removed (idempotent).'
+			),
 	}),
 ]);
 
@@ -295,9 +315,13 @@ export type RmFileParams = z.infer<typeof RmFileParamsSchema>;
  *
  * @param client - The API client to use for the request
  * @param params - Parameters including sandbox ID and path
+ * @returns Object with `found` indicating whether the file existed before removal
  * @throws {SandboxResponseError} If the rm request fails
  */
-export async function sandboxRmFile(client: APIClient, params: RmFileParams): Promise<void> {
+export async function sandboxRmFile(
+	client: APIClient,
+	params: RmFileParams
+): Promise<{ found: boolean }> {
 	const { sandboxId, path, orgId, signal } = params;
 
 	const body: z.infer<typeof RmFileRequestSchema> = {
@@ -322,6 +346,8 @@ export async function sandboxRmFile(client: APIClient, params: RmFileParams): Pr
 	if (!resp.success) {
 		throwSandboxError(resp, { sandboxId });
 	}
+
+	return { found: resp.found };
 }
 
 export const FileInfoSchema = z.object({

package/src/services/sandbox/types.ts

@@ -383,14 +383,16 @@ export const SandboxSchema = z.object({
 	mkDir: z
 		.custom<(path: string, recursive?: boolean) => Promise<void>>()
 		.describe('Create a directory in the sandbox workspace.'),
-	/** Remove a file from the sandbox workspace. */
+	/** Remove a file from the sandbox workspace. Returns whether the file was found. */
 	rmFile: z
-		.custom<(path: string) => Promise<void>>()
-		.describe('Remove a file from the sandbox workspace.'),
-	/** Remove a directory from the sandbox workspace. */
+		.custom<(path: string) => Promise<{ found: boolean }>>()
+		.describe('Remove a file from the sandbox workspace. Returns whether the file was found.'),
+	/** Remove a directory from the sandbox workspace. Returns whether the directory was found. */
 	rmDir: z
-		.custom<(path: string, recursive?: boolean) => Promise<void>>()
-		.describe('Remove a directory from the sandbox workspace.'),
+		.custom<(path: string, recursive?: boolean) => Promise<{ found: boolean }>>()
+		.describe(
+			'Remove a directory from the sandbox workspace. Returns whether the directory was found.'
+		),
 	/** Set environment variables on the sandbox. Pass null to delete a variable. */
 	setEnv: z
 		.custom<(env: Record<string, string | null>) => Promise<Record<string, string>>>()