@agentuity/server 1.0.9 → 1.0.11

package/src/api/project/hostname.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+import { type APIClient, APIResponseSchema } from '../api';
+import { ProjectResponseError } from './util';
+
+// --- GET hostname ---
+
+export const ProjectHostnameGetRequestSchema = z.object({
+	projectId: z.string().describe('the project id'),
+});
+
+const HostnameGetDataSchema = z.object({
+	hostname: z.string().nullable(),
+	url: z.string().nullable(),
+});
+
+const ProjectHostnameGetResponseSchema = APIResponseSchema(HostnameGetDataSchema);
+
+type ProjectHostnameGetRequest = z.infer<typeof ProjectHostnameGetRequestSchema>;
+type ProjectHostnameGetResponse = z.infer<typeof ProjectHostnameGetResponseSchema>;
+
+export type ProjectHostnameGetResult = z.infer<typeof HostnameGetDataSchema>;
+
+export async function projectHostnameGet(
+	client: APIClient,
+	request: ProjectHostnameGetRequest
+): Promise<ProjectHostnameGetResult> {
+	const resp = await client.get<ProjectHostnameGetResponse>(
+		`/cli/project/${request.projectId}/hostname`,
+		ProjectHostnameGetResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new ProjectResponseError({ message: resp.message });
+}
+
+// --- SET hostname ---
+
+export const ProjectHostnameSetRequestSchema = z.object({
+	projectId: z.string().describe('the project id'),
+	hostname: z.string().describe('the vanity hostname to set'),
+});
+
+const HostnameSetDataSchema = z.object({
+	hostname: z.string(),
+	url: z.string(),
+});
+
+const ProjectHostnameSetResponseSchema = APIResponseSchema(HostnameSetDataSchema);
+
+type ProjectHostnameSetRequest = z.infer<typeof ProjectHostnameSetRequestSchema>;
+type ProjectHostnameSetResponse = z.infer<typeof ProjectHostnameSetResponseSchema>;
+
+export type ProjectHostnameSetResult = z.infer<typeof HostnameSetDataSchema>;
+
+export async function projectHostnameSet(
+	client: APIClient,
+	request: ProjectHostnameSetRequest
+): Promise<ProjectHostnameSetResult> {
+	const resp = await client.put<ProjectHostnameSetResponse>(
+		`/cli/project/${request.projectId}/hostname`,
+		{ hostname: request.hostname },
+		ProjectHostnameSetResponseSchema
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throw new ProjectResponseError({ message: resp.message });
+}

package/src/api/project/index.ts

@@ -7,6 +7,7 @@ export * from './env-delete';
 export * from './env-update';
 export * from './exists';
 export * from './get';
+export * from './hostname';
 export * from './list';
 export * from './malware';
 export * from './update-region';

package/src/api/project/malware.ts

@@ -41,7 +41,8 @@ export type MalwareCheckResult = z.infer<typeof MalwareCheckResultSchema>;
 export async function projectDeploymentMalwareCheck(
 	client: APIClient,
 	deploymentId: string,
-	packages: PackageRef[]
+	packages: PackageRef[],
+	signal?: AbortSignal
 ): Promise<MalwareCheckResult> {
 	const resp = await client.request<z.infer<typeof MalwareCheckResponseSchema>>(
 		'POST',
@@ -50,7 +51,9 @@ export async function projectDeploymentMalwareCheck(
 		{
 			ecosystem: 'npm',
 			packages,
-		}
+		},
+		undefined,
+		signal
 	);
 
 	if (!resp.success) {

package/src/api/queue/queues.ts

@@ -201,6 +201,12 @@ export async function listQueues(
 	if (params?.offset !== undefined) {
 		searchParams.set('offset', String(params.offset));
 	}
+	if (params?.sort) {
+		searchParams.set('sort', params.sort);
+	}
+	if (params?.direction) {
+		searchParams.set('direction', params.direction);
+	}
 
 	const queryString = searchParams.toString();
 	const url = queueApiPathWithQuery('list', queryString || undefined);

package/src/api/queue/types.ts

@@ -18,6 +18,8 @@ export const QueueTypeSchema = z.enum(['worker', 'pubsub']);
  */
 export type QueueType = z.infer<typeof QueueTypeSchema>;
 
+export type QueueSortField = 'name' | 'created' | 'updated';
+
 /**
  * Base queue settings schema without defaults - used for partial updates.
  *
@@ -476,6 +478,10 @@ export const ListQueuesRequestSchema = z.object({
 	limit: z.number().optional(),
 	/** Number of queues to skip for pagination. */
 	offset: z.number().optional(),
+	/** Field to sort by. */
+	sort: z.enum(['name', 'created', 'updated']).optional(),
+	/** Sort direction (asc or desc). */
+	direction: z.enum(['asc', 'desc']).optional(),
 });
 
 /** Request type for listing queues. */

package/src/api/sandbox/cli-list.ts

@@ -46,6 +46,14 @@ export interface CLISandboxListOptions {
 	 * Number of sandboxes to skip for pagination
 	 */
 	offset?: number;
+	/**
+	 * Field to sort by
+	 */
+	sort?: string;
+	/**
+	 * Sort direction (default: 'desc')
+	 */
+	direction?: 'asc' | 'desc';
 }
 
 /**
@@ -75,7 +83,7 @@ export async function cliSandboxList(
 	client: APIClient,
 	options: CLISandboxListOptions = {}
 ): Promise<CLISandboxListData> {
-	const { projectId, orgId, status, limit, offset } = options;
+	const { projectId, orgId, status, limit, offset, sort, direction } = options;
 	const params = new URLSearchParams();
 
 	if (projectId) params.set('projectId', projectId);
@@ -83,6 +91,8 @@ export async function cliSandboxList(
 	if (status) params.set('status', status);
 	if (limit !== undefined) params.set('limit', limit.toString());
 	if (offset !== undefined) params.set('offset', offset.toString());
+	if (sort) params.set('sort', sort);
+	if (direction) params.set('direction', direction);
 
 	const queryString = params.toString();
 	const resp = await client.request<CLISandboxListResponse>(

package/src/api/sandbox/client.ts

@@ -244,7 +244,9 @@ export class SandboxClient {
 
 		const logger = options.logger ?? new ConsoleLogger('warn');
 
-		this.#client = new APIClient(url, logger, apiKey ?? '', {});
+		// Disable retries for sandbox operations - 409 Conflict means sandbox is busy,
+		// not a retryable rate limit. Retrying would waste ~360s (4 attempts × 90s timeout).
+		this.#client = new APIClient(url, logger, apiKey ?? '', { maxRetries: 0 });
 		this.#orgId = options.orgId;
 		this.#apiKey = apiKey;
 		this.#region = region;

package/src/api/sandbox/execute.ts

@@ -1,7 +1,7 @@
 import type { ExecuteOptions, Execution, ExecutionStatus } from '@agentuity/core';
 import { z } from 'zod';
 import { type APIClient, APIResponseSchema } from '../api';
-import { API_VERSION, throwSandboxError } from './util';
+import { API_VERSION, SandboxBusyError, throwSandboxError } from './util';
 
 export const ExecuteRequestSchema = z
 	.object({
@@ -86,13 +86,36 @@ export async function sandboxExecute(
 	const queryString = queryParams.toString();
 	const url = `/sandbox/${API_VERSION}/${sandboxId}/execute${queryString ? `?${queryString}` : ''}`;
 
-	const resp = await client.post<z.infer<typeof ExecuteResponseSchema>>(
-		url,
-		body,
-		ExecuteResponseSchema,
-		ExecuteRequestSchema,
-		signal ?? options.signal
-	);
+	let resp: z.infer<typeof ExecuteResponseSchema>;
+	try {
+		resp = await client.post<z.infer<typeof ExecuteResponseSchema>>(
+			url,
+			body,
+			ExecuteResponseSchema,
+			ExecuteRequestSchema,
+			signal ?? options.signal
+		);
+	} catch (error: unknown) {
+		// Detect 409 Conflict (sandbox busy) and throw a specific error.
+		// The sandbox API client is configured with maxRetries: 0 to fail fast
+		// when sandbox is busy (retrying wouldn't help - sandbox is still busy).
+		// Convert APIErrorResponse with status 409 to SandboxBusyError for clarity.
+		if (
+			error &&
+			typeof error === 'object' &&
+			'_tag' in error &&
+			(error as { _tag: string })._tag === 'APIErrorResponse' &&
+			'status' in error &&
+			(error as { status: number }).status === 409
+		) {
+			throw new SandboxBusyError({
+				message:
+					'Sandbox is currently busy executing another command. Please wait for the current execution to complete before submitting a new one.',
+				sandboxId,
+			});
+		}
+		throw error;
+	}
 
 	if (resp.success) {
 		return {

package/src/api/sandbox/index.ts

@@ -177,6 +177,7 @@ export {
 	ExecutionCancelledError,
 	ExecutionNotFoundError,
 	ExecutionTimeoutError,
+	SandboxBusyError,
 	SandboxNotFoundError,
 	SandboxResponseError,
 	SandboxTerminatedError,

package/src/api/sandbox/list.ts

@@ -157,6 +157,12 @@ export async function sandboxList(
 	if (params?.offset !== undefined) {
 		queryParams.set('offset', params.offset.toString());
 	}
+	if (params?.sort) {
+		queryParams.set('sort', params.sort);
+	}
+	if (params?.direction) {
+		queryParams.set('direction', params.direction);
+	}
 	if (params?.deletedOnly) {
 		queryParams.set('deletedOnly', 'true');
 	}

package/src/api/sandbox/runtime.ts

@@ -62,6 +62,12 @@ export async function runtimeList(
 	if (params?.offset !== undefined) {
 		queryParams.set('offset', params.offset.toString());
 	}
+	if (params?.sort) {
+		queryParams.set('sort', params.sort);
+	}
+	if (params?.direction) {
+		queryParams.set('direction', params.direction);
+	}
 
 	const queryString = queryParams.toString();
 	const url = `/sandbox/${API_VERSION}/runtimes${queryString ? `?${queryString}` : ''}`;

package/src/api/sandbox/snapshot.ts

@@ -162,6 +162,8 @@ const _SnapshotListParamsSchema = z
 		sandboxId: z.string().optional().describe('Filter by sandbox ID'),
 		limit: z.number().optional().describe('Maximum number of snapshots to return'),
 		offset: z.number().optional().describe('Number of snapshots to skip'),
+		sort: z.string().optional().describe('Field to sort by'),
+		direction: z.enum(['asc', 'desc']).optional().describe('Sort direction (asc or desc)'),
 		orgId: z.string().optional().describe('Organization ID'),
 	})
 	.describe('Parameters for listing snapshots');
@@ -303,8 +305,8 @@ export async function snapshotList(
 	client: APIClient,
 	params: SnapshotListParams = {}
 ): Promise<SnapshotListResponse> {
-	const { sandboxId, limit, offset, orgId } = params;
-	const queryString = buildQueryString({ sandboxId, limit, offset, orgId });
+	const { sandboxId, limit, offset, sort, direction, orgId } = params;
+	const queryString = buildQueryString({ sandboxId, limit, offset, sort, direction, orgId });
 	const url = `/sandbox/${API_VERSION}/snapshots${queryString}`;
 
 	const resp = await client.get<z.infer<typeof SnapshotListResponseSchema>>(

package/src/api/sandbox/util.ts

@@ -12,6 +12,7 @@ interface WritableWithDrain extends EventEmitter {
 export type SandboxErrorCode =
 	| 'SANDBOX_NOT_FOUND'
 	| 'SANDBOX_TERMINATED'
+	| 'SANDBOX_BUSY'
 	| 'EXECUTION_NOT_FOUND'
 	| 'EXECUTION_TIMEOUT'
 	| 'EXECUTION_CANCELLED'
@@ -69,6 +70,29 @@ export const SandboxTerminatedError = StructuredError('SandboxTerminatedError')<
 	sandboxId: string;
 }>();
 
+/**
+ * Error thrown when a sandbox is currently busy executing another command.
+ *
+ * This typically occurs when a second execute request is sent before the
+ * previous execution has completed. Sandbox executions are serialized -
+ * wait for the current execution to complete before sending a new one.
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await sandbox.execute({ command: ['ls'] });
+ * } catch (error) {
+ *   if (error._tag === 'SandboxBusyError') {
+ *     console.error('Sandbox is busy, waiting for current execution to finish');
+ *     // Wait and retry, or use executionGet with long-polling to wait for completion
+ *   }
+ * }
+ * ```
+ */
+export const SandboxBusyError = StructuredError('SandboxBusyError')<{
+	sandboxId?: string;
+}>();
+
 /**
  * Error thrown when an execution is not found.
  *
@@ -164,6 +188,7 @@ export interface SandboxErrorContext {
  * @param context - Context about the operation (sandbox ID, execution ID, etc.)
  * @throws {SandboxNotFoundError} When code is 'SANDBOX_NOT_FOUND'
  * @throws {SandboxTerminatedError} When code is 'SANDBOX_TERMINATED'
+ * @throws {SandboxBusyError} When code is 'SANDBOX_BUSY'
  * @throws {ExecutionNotFoundError} When code is 'EXECUTION_NOT_FOUND'
  * @throws {ExecutionTimeoutError} When code is 'EXECUTION_TIMEOUT'
  * @throws {ExecutionCancelledError} When code is 'EXECUTION_CANCELLED'
@@ -182,6 +207,8 @@ export function throwSandboxError(
 			throw new SandboxNotFoundError({ message: resp.message, sandboxId: sandboxId ?? '' });
 		case 'SANDBOX_TERMINATED':
 			throw new SandboxTerminatedError({ message: resp.message, sandboxId: sandboxId ?? '' });
+		case 'SANDBOX_BUSY':
+			throw new SandboxBusyError({ message: resp.message, sandboxId });
 		case 'EXECUTION_NOT_FOUND':
 			throw new ExecutionNotFoundError({
 				message: resp.message,

package/src/api/session/list.ts

@@ -1,3 +1,4 @@
+import type { SortDirection } from '@agentuity/core';
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
 import { SessionResponseError } from './util';
@@ -32,10 +33,10 @@ const SessionSchema = z.object({
 	llm_prompt_token_count: z.number().nullable().describe('the LLM prompt token count'),
 	llm_completion_token_count: z.number().nullable().describe('the LLM completion token count'),
 	total_cost: z.number().nullable().describe('the total cost'),
-	method: z.string().describe('the HTTP method'),
-	url: z.string().describe('the request URL'),
-	route_id: z.string().describe('the route id'),
-	thread_id: z.string().describe('the thread id'),
+	method: z.string().nullable().describe('the HTTP method'),
+	url: z.string().nullable().describe('the request URL'),
+	route_id: z.string().nullable().describe('the route id'),
+	thread_id: z.string().nullable().describe('the thread id'),
 	timeline: z.unknown().nullable().optional().describe('the session timeline tree'),
 	user_data: z.string().nullable().optional().describe('the user data as JSON'),
 });
@@ -50,8 +51,15 @@ export type SessionListResponse = z.infer<typeof SessionListResponseSchema>;
 export type SessionList = z.infer<typeof SessionListResponse>;
 export type Session = z.infer<typeof SessionSchema>;
 
+export type SessionSortField = 'created' | 'updated' | 'duration' | 'startTime';
+
 export interface SessionListOptions {
+	/** @deprecated Use `limit` instead. Will be removed in a future version. */
 	count?: number;
+	limit?: number;
+	offset?: number;
+	sort?: SessionSortField;
+	direction?: SortDirection;
 	orgId?: string;
 	projectId?: string;
 	deploymentId?: string;
@@ -78,7 +86,11 @@ export async function sessionList(
 	options: SessionListOptions = {}
 ): Promise<SessionList> {
 	const {
-		count = 10,
+		count,
+		limit,
+		offset,
+		sort,
+		direction,
 		orgId,
 		projectId,
 		deploymentId,
@@ -92,12 +104,16 @@ export async function sessionList(
 		startBefore,
 		metadata,
 	} = options;
-	const params = new URLSearchParams({ count: count.toString() });
+	const resolvedLimit = limit ?? count ?? 10;
+	const params = new URLSearchParams({ limit: resolvedLimit.toString() });
 	if (orgId) params.set('orgId', orgId);
 	if (projectId) params.set('projectId', projectId);
 	if (deploymentId) params.set('deploymentId', deploymentId);
 	if (trigger) params.set('trigger', trigger);
 	if (env) params.set('env', env);
+	if (offset !== undefined) params.set('offset', offset.toString());
+	if (sort) params.set('sort', sort);
+	if (direction) params.set('direction', direction);
 	if (devmode !== undefined) params.set('devmode', devmode.toString());
 	if (success !== undefined) params.set('success', success.toString());
 	if (threadId) params.set('threadId', threadId);

package/src/api/stream/list.ts

@@ -1,3 +1,4 @@
+import type { SortDirection } from '@agentuity/core';
 import { z } from 'zod';
 import { type APIClient, APIResponseSchema } from '../api';
 import { StreamResponseError } from './util';
@@ -50,6 +51,14 @@ export interface StreamListOptions {
 	 * Filter by metadata key-value pairs
 	 */
 	metadata?: Record<string, string>;
+	/**
+	 * Field to sort by
+	 */
+	sort?: string;
+	/**
+	 * Sort direction (default: 'desc')
+	 */
+	direction?: SortDirection;
 }
 
 /**
@@ -95,6 +104,8 @@ export async function streamList(
 	if (metadata && Object.keys(metadata).length > 0) {
 		params.set('metadata', JSON.stringify(metadata));
 	}
+	if (options.sort) params.set('sort', options.sort);
+	if (options.direction) params.set('direction', options.direction);
 
 	const queryString = params.toString();
 	const resp = await client.request<StreamListResponse>(

package/src/api/thread/list.ts

@@ -1,3 +1,4 @@
+import type { SortDirection } from '@agentuity/core';
 import { z } from 'zod';
 import { APIClient, APIResponseSchema } from '../api';
 import { ThreadResponseError } from './util';
@@ -27,8 +28,14 @@ export type ThreadListResponse = z.infer<typeof ThreadListResponseSchema>;
 export type ThreadList = z.infer<typeof ThreadListResponseData>;
 export type Thread = z.infer<typeof ThreadSchema>;
 
+export type ThreadSortField = 'created' | 'updated';
+
 export interface ThreadListOptions {
 	count?: number;
+	limit?: number;
+	offset?: number;
+	sort?: ThreadSortField;
+	direction?: SortDirection;
 	orgId?: string;
 	projectId?: string;
 	metadata?: Record<string, unknown>;
@@ -45,10 +52,14 @@ export async function threadList(
 	client: APIClient,
 	options: ThreadListOptions = {}
 ): Promise<ThreadList> {
-	const { count = 10, orgId, projectId, metadata } = options;
-	const params = new URLSearchParams({ count: count.toString() });
+	const { limit, count, offset, sort, direction, orgId, projectId, metadata } = options;
+	const resolvedLimit = limit ?? count ?? 10;
+	const params = new URLSearchParams({ limit: resolvedLimit.toString() });
 	if (orgId) params.set('orgId', orgId);
 	if (projectId) params.set('projectId', projectId);
+	if (offset !== undefined) params.set('offset', offset.toString());
+	if (sort) params.set('sort', sort);
+	if (direction) params.set('direction', direction);
 	if (metadata) params.set('metadata', JSON.stringify(metadata));
 
 	const resp = await client.request<ThreadListResponse>(