@agentuity/core 1.0.48 → 1.0.50

package/dist/services/sandbox/util.js.map

@@ -1 +1 @@
-{"version":3,"file":"util.js","sourceRoot":"","sources":["../../../src/services/sandbox/util.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"util.js","sourceRoot":"","sources":["../../../src/services/sandbox/util.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@agentuity/core",
-	"version": "1.0.48",
+	"version": "1.0.50",
 	"license": "Apache-2.0",
 	"author": "Agentuity employees and contributors",
 	"type": "module",
@@ -89,7 +89,7 @@
 		"zod": "^4.3.5"
 	},
 	"devDependencies": {
-		"@agentuity/test-utils": "1.0.48",
+		"@agentuity/test-utils": "1.0.50",
 		"@types/bun": "latest",
 		"bun-types": "latest",
 		"esbuild": "^0.25.0",

package/src/services/api.ts

@@ -272,7 +272,7 @@ export class APIClient {
 		signal?: AbortSignal,
 		extraHeaders?: Record<string, string>
 	): Promise<Response> {
-		return this.#makeRequest('GET', endpoint, undefined, signal, undefined, extraHeaders);
+		return this.#makeRequest('GET', endpoint, undefined, signal, undefined, extraHeaders, true);
 	}
 
 	/**
@@ -285,7 +285,7 @@ export class APIClient {
 		contentType: string,
 		signal?: AbortSignal
 	): Promise<Response> {
-		return this.#makeRequest('POST', endpoint, body, signal, contentType);
+		return this.#makeRequest('POST', endpoint, body, signal, contentType, undefined, true);
 	}
 
 	/**
@@ -299,7 +299,7 @@ export class APIClient {
 		signal?: AbortSignal,
 		extraHeaders?: Record<string, string>
 	): Promise<Response> {
-		return this.#makeRequest('PUT', endpoint, body, signal, contentType, extraHeaders);
+		return this.#makeRequest('PUT', endpoint, body, signal, contentType, extraHeaders, true);
 	}
 
 	/**
@@ -375,7 +375,8 @@ export class APIClient {
 		body?: unknown,
 		signal?: AbortSignal,
 		contentType?: string,
-		extraHeaders?: Record<string, string>
+		extraHeaders?: Record<string, string>,
+		raw?: boolean
 	): Promise<Response> {
 		this.#logger.trace('sending %s to %s%s', method, this.#baseUrl, endpoint);
 
@@ -599,7 +600,10 @@ export class APIClient {
 				}
 
 				// Handle error responses
-				if (!response.ok) {
+				// When raw mode is set, skip error handling and return the response as-is
+				// so callers (e.g., sandboxReadFile) can inspect the status and provide
+				// context-aware error messages (including sandbox ID, file path, etc.).
+				if (!raw && !response.ok) {
 					const responseBody = await response.text();
 					const contentType = response.headers.get('content-type');
 
@@ -722,6 +726,12 @@ export class APIClient {
 
 				this.#logger.debug('%s succeeded with status: %d', url, response.status);
 
+				// In raw mode, return the untouched Response (status, headers, body)
+				// so callers can inspect everything themselves.
+				if (raw) {
+					return response;
+				}
+
 				// Successful response; handle empty bodies (e.g., 204 No Content)
 				if (response.status === 204 || response.headers.get('content-length') === '0') {
 					return new Response(null, { status: 204 });

package/src/services/oauth/flow.ts

@@ -0,0 +1,215 @@
+import { getEnv } from '../env.ts';
+import { OAuthResponseError } from './util.ts';
+import { OAuthTokenResponseSchema, OAuthUserInfoSchema } from './types.ts';
+import type { OAuthFlowConfig, OAuthTokenResponse, OAuthUserInfo } from './types.ts';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/**
+ * Resolve OAuth configuration by merging explicit config with environment variables.
+ * Priority: explicit config > env vars > issuer-derived URLs > defaults.
+ */
+function resolveConfig(config?: OAuthFlowConfig) {
+	const clientId = config?.clientId ?? getEnv('OAUTH_CLIENT_ID');
+	const clientSecret = config?.clientSecret ?? getEnv('OAUTH_CLIENT_SECRET');
+	const issuer = config?.issuer ?? getEnv('OAUTH_ISSUER');
+	const authorizeUrl =
+		config?.authorizeUrl ??
+		getEnv('OAUTH_AUTHORIZE_URL') ??
+		(issuer ? `${issuer}/authorize` : undefined);
+	const tokenUrl =
+		config?.tokenUrl ??
+		getEnv('OAUTH_TOKEN_URL') ??
+		(issuer ? `${issuer}/oauth/token` : undefined);
+	const userinfoUrl =
+		config?.userinfoUrl ??
+		getEnv('OAUTH_USERINFO_URL') ??
+		(issuer ? `${issuer}/userinfo` : undefined);
+	const scopes = config?.scopes ?? getEnv('OAUTH_SCOPES') ?? 'openid profile email';
+
+	const prompt = config?.prompt;
+
+	return { clientId, clientSecret, issuer, authorizeUrl, tokenUrl, userinfoUrl, scopes, prompt };
+}
+
+/**
+ * Build an OAuth 2.0 authorization URL for redirecting the user to the OIDC provider.
+ *
+ * @param redirectUri - The callback URL the provider will redirect to after authentication
+ * @param config - Optional OAuth configuration. Falls back to environment variables.
+ * @returns The full authorization URL to redirect the user to
+ *
+ * @example
+ * ```typescript
+ * // Uses OAUTH_CLIENT_ID, OAUTH_AUTHORIZE_URL (or OAUTH_ISSUER) from env
+ * const url = buildAuthorizeUrl('http://localhost:3500/api/oauth/login');
+ *
+ * // Or with explicit config
+ * const url = buildAuthorizeUrl('http://localhost:3500/api/oauth/login', {
+ *   issuer: 'https://auth.agentuity.cloud',
+ *   clientId: 'my-client-id',
+ * });
+ * ```
+ */
+export function buildAuthorizeUrl(redirectUri: string, config?: OAuthFlowConfig): string {
+	const resolved = resolveConfig(config);
+
+	if (!resolved.authorizeUrl) {
+		throw new OAuthResponseError({
+			message:
+				'No authorize URL configured. Set OAUTH_AUTHORIZE_URL or OAUTH_ISSUER environment variable.',
+		});
+	}
+	if (!resolved.clientId) {
+		throw new OAuthResponseError({
+			message: 'No client ID configured. Set OAUTH_CLIENT_ID environment variable.',
+		});
+	}
+
+	const params = new URLSearchParams({
+		client_id: resolved.clientId,
+		redirect_uri: redirectUri,
+		response_type: 'code',
+		scope: resolved.scopes,
+	});
+
+	if (resolved.prompt) {
+		params.set('prompt', resolved.prompt);
+	}
+
+	return `${resolved.authorizeUrl}?${params.toString()}`;
+}
+
+/**
+ * Exchange an authorization code for an access token.
+ *
+ * @param code - The authorization code received from the OAuth callback
+ * @param redirectUri - The same redirect URI used in the authorization request
+ * @param config - Optional OAuth configuration. Falls back to environment variables.
+ * @returns The token response including access_token, and optionally refresh_token, id_token, etc.
+ *
+ * @example
+ * ```typescript
+ * const token = await exchangeToken(code, 'http://localhost:3500/api/oauth/login');
+ * console.log(token.access_token);
+ * ```
+ */
+export async function exchangeToken(
+	code: string,
+	redirectUri: string,
+	config?: OAuthFlowConfig
+): Promise<OAuthTokenResponse> {
+	const resolved = resolveConfig(config);
+
+	if (!resolved.tokenUrl) {
+		throw new OAuthResponseError({
+			message:
+				'No token URL configured. Set OAUTH_TOKEN_URL or OAUTH_ISSUER environment variable.',
+		});
+	}
+	if (!resolved.clientId) {
+		throw new OAuthResponseError({
+			message: 'No client ID configured. Set OAUTH_CLIENT_ID environment variable.',
+		});
+	}
+	if (!resolved.clientSecret) {
+		throw new OAuthResponseError({
+			message: 'No client secret configured. Set OAUTH_CLIENT_SECRET environment variable.',
+		});
+	}
+
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+
+	let response: Response;
+	try {
+		response = await fetch(resolved.tokenUrl, {
+			method: 'POST',
+			headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+			body: new URLSearchParams({
+				grant_type: 'authorization_code',
+				code,
+				redirect_uri: redirectUri,
+				client_id: resolved.clientId,
+				client_secret: resolved.clientSecret,
+			}),
+			signal: controller.signal,
+		});
+	} catch (err) {
+		clearTimeout(timer);
+		if (err instanceof DOMException && err.name === 'AbortError') {
+			throw new OAuthResponseError({
+				message: `Token exchange timed out after ${DEFAULT_TIMEOUT_MS}ms`,
+			});
+		}
+		throw err;
+	}
+	clearTimeout(timer);
+
+	if (!response.ok) {
+		const error = await response.text();
+		throw new OAuthResponseError({
+			message: `Token exchange failed (${response.status}): ${error}`,
+		});
+	}
+
+	const data = await response.json();
+	return OAuthTokenResponseSchema.parse(data);
+}
+
+/**
+ * Fetch user information from the OIDC userinfo endpoint using an access token.
+ *
+ * @param accessToken - The access token obtained from the token exchange
+ * @param config - Optional OAuth configuration. Falls back to environment variables.
+ * @returns The user info including sub, name, email, and any additional claims
+ *
+ * @example
+ * ```typescript
+ * const user = await fetchUserInfo(token.access_token);
+ * console.log(user.name, user.email);
+ * ```
+ */
+export async function fetchUserInfo(
+	accessToken: string,
+	config?: OAuthFlowConfig
+): Promise<OAuthUserInfo> {
+	const resolved = resolveConfig(config);
+
+	if (!resolved.userinfoUrl) {
+		throw new OAuthResponseError({
+			message:
+				'No userinfo URL configured. Set OAUTH_USERINFO_URL or OAUTH_ISSUER environment variable.',
+		});
+	}
+
+	const controller = new AbortController();
+	const timer = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+
+	let response: Response;
+	try {
+		response = await fetch(resolved.userinfoUrl, {
+			headers: { Authorization: `Bearer ${accessToken}` },
+			signal: controller.signal,
+		});
+	} catch (err) {
+		clearTimeout(timer);
+		if (err instanceof DOMException && err.name === 'AbortError') {
+			throw new OAuthResponseError({
+				message: `Userinfo request timed out after ${DEFAULT_TIMEOUT_MS}ms`,
+			});
+		}
+		throw err;
+	}
+	clearTimeout(timer);
+
+	if (!response.ok) {
+		const error = await response.text();
+		throw new OAuthResponseError({
+			message: `Failed to fetch user info (${response.status}): ${error}`,
+		});
+	}
+
+	const data = await response.json();
+	return OAuthUserInfoSchema.parse(data);
+}

package/src/services/oauth/index.ts

@@ -6,3 +6,4 @@ export * from './scopes.ts';
 export * from './members.ts';
 export * from './keys.ts';
 export * from './util.ts';
+export * from './flow.ts';

package/src/services/oauth/types.ts

@@ -238,3 +238,69 @@ export type OAuthUserConsentRevokeResponse = z.infer<typeof OAuthUserConsentRevo
 export type OAuthScopesResponse = z.infer<typeof OAuthScopesResponseSchema>;
 export type OAuthOrgMembersResponse = z.infer<typeof OAuthOrgMembersResponseSchema>;
 export type OAuthKeysRotateResponse = z.infer<typeof OAuthKeysRotateResponseSchema>;
+
+// ============================================================================
+// OAuth 2.0 Authorization Code Flow Types
+// ============================================================================
+
+export const OAuthFlowConfigSchema = z.object({
+	clientId: z.string().optional().describe('OAuth client ID. Defaults to OAUTH_CLIENT_ID env var'),
+	clientSecret: z
+		.string()
+		.optional()
+		.describe('OAuth client secret. Defaults to OAUTH_CLIENT_SECRET env var'),
+	issuer: z
+		.string()
+		.optional()
+		.describe(
+			'OIDC issuer base URL. Defaults to OAUTH_ISSUER env var. Used to derive authorize/token/userinfo URLs'
+		),
+	authorizeUrl: z
+		.string()
+		.optional()
+		.describe('Authorization endpoint. Defaults to OAUTH_AUTHORIZE_URL or {issuer}/authorize'),
+	tokenUrl: z
+		.string()
+		.optional()
+		.describe('Token endpoint. Defaults to OAUTH_TOKEN_URL or {issuer}/oauth/token'),
+	userinfoUrl: z
+		.string()
+		.optional()
+		.describe('UserInfo endpoint. Defaults to OAUTH_USERINFO_URL or {issuer}/userinfo'),
+	scopes: z
+		.string()
+		.optional()
+		.describe('Space-separated scopes. Defaults to OAUTH_SCOPES or "openid profile email"'),
+	prompt: z
+		.enum(['none', 'login', 'consent', 'select_account'])
+		.optional()
+		.describe(
+			'OIDC prompt parameter. Controls authentication UX: "login" forces re-auth, "consent" forces consent screen, "none" fails if not authenticated, "select_account" lets user pick an account'
+		),
+});
+
+export type OAuthFlowConfig = z.infer<typeof OAuthFlowConfigSchema>;
+
+export const OAuthTokenResponseSchema = z.object({
+	access_token: z.string(),
+	token_type: z.string().optional(),
+	expires_in: z.number().optional(),
+	refresh_token: z.string().optional(),
+	scope: z.string().optional(),
+	id_token: z.string().optional(),
+});
+
+export type OAuthTokenResponse = z.infer<typeof OAuthTokenResponseSchema>;
+
+export const OAuthUserInfoSchema = z
+	.object({
+		sub: z.string(),
+		name: z.string().optional(),
+		given_name: z.string().optional(),
+		family_name: z.string().optional(),
+		email: z.string().optional(),
+		email_verified: z.boolean().optional(),
+	})
+	.catchall(z.unknown());
+
+export type OAuthUserInfo = z.infer<typeof OAuthUserInfoSchema>;

package/src/services/sandbox/client.ts

@@ -5,6 +5,7 @@ import {
 	type SandboxInfo,
 	type SandboxStatus,
 	type Execution,
+	type ExecutionStatus,
 	type FileToWrite,
 	type SandboxRunOptions,
 	type SandboxRunResult,
@@ -35,13 +36,25 @@ import { createMinimalLogger } from '../logger.ts';
 import { getServiceUrls } from '../config.ts';
 import { writeAndDrain } from './util.ts';
 
-// Server-side long-poll wait duration (max 5 minutes supported by server)
+// Server-side long-poll wait duration per iteration (max 5 minutes supported by server)
 const EXECUTION_WAIT_DURATION = '5m';
 
+/** Terminal execution statuses that indicate the command has finished. */
+const TERMINAL_STATUSES: Set<ExecutionStatus> = new Set([
+	'completed',
+	'failed',
+	'timeout',
+	'cancelled',
+]);
+
 /**
- * Wait for execution completion using server-side long-polling.
- * This is more efficient than client-side polling and provides immediate
- * error detection if the sandbox is terminated.
+ * Wait for execution completion using server-side long-polling with automatic retry.
+ *
+ * Each iteration asks the server to hold the connection for up to
+ * EXECUTION_WAIT_DURATION. If the execution is still running when the
+ * server-side wait expires, we loop and issue another long-poll request.
+ * This continues until the execution reaches a terminal state or the
+ * caller's AbortSignal fires.
  */
 async function waitForExecution(
 	client: APIClient,
@@ -49,17 +62,30 @@ async function waitForExecution(
 	orgId?: string,
 	signal?: AbortSignal
 ): Promise<ExecutionInfo> {
-	if (signal?.aborted) {
-		throw new DOMException('The operation was aborted.', 'AbortError');
-	}
+	while (true) {
+		if (signal?.aborted) {
+			throw new DOMException('The operation was aborted.', 'AbortError');
+		}
+
+		// Use server-side long-polling - the server will hold the connection
+		// until the execution reaches a terminal state or the wait duration expires.
+		// The signal is forwarded so the in-flight fetch is cancelled immediately
+		// when the caller aborts, rather than waiting the full poll duration.
+		const result = await executionGet(client, {
+			executionId,
+			orgId,
+			wait: EXECUTION_WAIT_DURATION,
+			signal,
+		});
 
-	// Use server-side long-polling - the server will hold the connection
-	// until the execution reaches a terminal state or the wait duration expires
-	return executionGet(client, {
-		executionId,
-		orgId,
-		wait: EXECUTION_WAIT_DURATION,
-	});
+		// If the execution reached a terminal state, return immediately
+		if (TERMINAL_STATUSES.has(result.status as ExecutionStatus)) {
+			return result;
+		}
+
+		// Non-terminal status (e.g., 'running', 'queued') — the server-side
+		// long-poll expired before the command finished. Loop to poll again.
+	}
 }
 
 /**

package/src/services/sandbox/create.ts

@@ -133,6 +133,10 @@ export const SandboxCreateDataSchema = z
 				'failed',
 			])
 			.describe('Current status of the sandbox'),
+		url: z
+			.string()
+			.optional()
+			.describe('Public URL for the sandbox (only set when a network port is configured)'),
 		stdoutStreamId: z.string().optional().describe('Stream ID for reading stdout'),
 		stdoutStreamUrl: z.string().optional().describe('URL for streaming stdout output'),
 		stderrStreamId: z.string().optional().describe('Stream ID for reading stderr'),

package/src/services/sandbox/execution.ts

@@ -44,6 +44,8 @@ export const ExecutionGetParamsSchema = z.object({
 	orgId: z.string().optional().describe('organization id'),
 	/** Optional wait duration for long-polling. */
 	wait: z.string().optional().describe('wait duration for long-polling'),
+	/** Optional AbortSignal to cancel the in-flight request. */
+	signal: z.custom<AbortSignal>().optional().describe('abort signal for cancellation'),
 });
 export type ExecutionGetParams = z.infer<typeof ExecutionGetParamsSchema>;
 
@@ -67,7 +69,7 @@ export async function executionGet(
 	client: APIClient,
 	params: ExecutionGetParams
 ): Promise<ExecutionInfo> {
-	const { executionId, orgId, wait } = params;
+	const { executionId, orgId, wait, signal } = params;
 	const queryParams = new URLSearchParams();
 	if (orgId) {
 		queryParams.set('orgId', orgId);
@@ -80,7 +82,8 @@ export async function executionGet(
 
 	const resp = await client.get<z.infer<typeof ExecutionGetResponseSchema>>(
 		url,
-		ExecutionGetResponseSchema
+		ExecutionGetResponseSchema,
+		signal
 	);
 
 	if (resp.success) {

package/src/services/sandbox/files.ts

@@ -124,7 +124,7 @@ export async function sandboxReadFile(
 	if (!response.ok) {
 		const text = await response.text().catch(() => 'Unknown error');
 		throw new SandboxResponseError({
-			message: `Failed to read file: ${response.status} ${text}`,
+			message: `Failed to read file "${path}": ${response.status} ${text}`,
 			sandboxId,
 			sessionId,
 		});

package/src/services/sandbox/index.ts

@@ -78,6 +78,24 @@ export {
 	executionGet,
 	executionList,
 } from './execution.ts';
+export type {
+	JobCreateParams,
+	JobGetParams,
+	JobListParams,
+	JobListResponse,
+	JobStopParams,
+} from './job.ts';
+export {
+	JobCreateParamsSchema,
+	JobGetParamsSchema,
+	JobListParamsSchema,
+	JobListResponseSchema,
+	JobStopParamsSchema,
+	jobCreate,
+	jobGet,
+	jobList,
+	jobStop,
+} from './job.ts';
 export type {
 	SandboxEventInfo,
 	SandboxEventListParams,