@agentuity/core 1.0.49 → 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.49",
+	"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.49",
+		"@agentuity/test-utils": "1.0.50",
 		"@types/bun": "latest",
 		"bun-types": "latest",
 		"esbuild": "^0.25.0",

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/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/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,

package/src/services/sandbox/job.ts

@@ -0,0 +1,161 @@
+import { type APIClient, APIResponseSchema } from '../api.ts';
+import { CreateJobOptionsSchema, JobSchema, type Job } from './types.ts';
+import { throwSandboxError } from './util.ts';
+import { z } from 'zod';
+
+export const CreateJobRequestSchema = CreateJobOptionsSchema;
+
+export const CreateJobDataSchema = JobSchema;
+
+export const CreateJobResponseSchema = APIResponseSchema(CreateJobDataSchema);
+
+export const JobCreateParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID where the job should run'),
+	options: CreateJobOptionsSchema.describe('Job creation options'),
+	orgId: z.string().optional().describe('Optional org id for CLI auth context'),
+	signal: z.custom<AbortSignal>().optional().describe('Optional abort signal for cancellation'),
+});
+export type JobCreateParams = z.infer<typeof JobCreateParamsSchema>;
+
+export async function jobCreate(client: APIClient, params: JobCreateParams): Promise<Job> {
+	const { sandboxId, options, orgId, signal } = params;
+	const body: z.infer<typeof CreateJobRequestSchema> = {
+		command: options.command,
+	};
+	if (options.streams) {
+		body.streams = options.streams;
+	}
+
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.post<z.infer<typeof CreateJobResponseSchema>>(
+		url,
+		body,
+		CreateJobResponseSchema,
+		CreateJobRequestSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+export const JobGetDataSchema = JobSchema;
+
+export const JobGetResponseSchema = APIResponseSchema(JobGetDataSchema);
+
+export const JobGetParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	jobId: z.string().describe('Job ID'),
+	orgId: z.string().optional().describe('Organization ID'),
+	signal: z.custom<AbortSignal>().optional().describe('Abort signal for cancellation'),
+});
+export type JobGetParams = z.infer<typeof JobGetParamsSchema>;
+
+export async function jobGet(client: APIClient, params: JobGetParams): Promise<Job> {
+	const { sandboxId, jobId, orgId, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs/${jobId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof JobGetResponseSchema>>(
+		url,
+		JobGetResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId, jobId: params.jobId });
+}
+
+export const JobListDataSchema = z.object({
+	jobs: z.array(JobSchema).describe('List of jobs'),
+});
+export type JobListResponse = z.infer<typeof JobListDataSchema>;
+
+export const JobListResponseSchema = APIResponseSchema(JobListDataSchema);
+
+export const JobListParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	orgId: z.string().optional().describe('Organization ID'),
+	limit: z.number().optional().describe('Maximum number of results'),
+	signal: z.custom<AbortSignal>().optional().describe('Abort signal for cancellation'),
+});
+export type JobListParams = z.infer<typeof JobListParamsSchema>;
+
+export async function jobList(client: APIClient, params: JobListParams): Promise<JobListResponse> {
+	const { sandboxId, orgId, limit, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	if (limit !== undefined) {
+		queryParams.set('limit', String(limit));
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.get<z.infer<typeof JobListResponseSchema>>(
+		url,
+		JobListResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId });
+}
+
+export const JobStopDataSchema = JobSchema;
+
+export const JobStopResponseSchema = APIResponseSchema(JobStopDataSchema);
+
+export const JobStopParamsSchema = z.object({
+	sandboxId: z.string().describe('Sandbox ID'),
+	jobId: z.string().describe('Job ID'),
+	force: z.boolean().optional().describe('Force termination (SIGKILL)'),
+	orgId: z.string().optional().describe('Organization ID'),
+	signal: z.custom<AbortSignal>().optional().describe('Abort signal for cancellation'),
+});
+export type JobStopParams = z.infer<typeof JobStopParamsSchema>;
+
+export async function jobStop(client: APIClient, params: JobStopParams): Promise<Job> {
+	const { sandboxId, jobId, force, orgId, signal } = params;
+	const queryParams = new URLSearchParams();
+	if (orgId) {
+		queryParams.set('orgId', orgId);
+	}
+	if (force) {
+		queryParams.set('force', 'true');
+	}
+	const queryString = queryParams.toString();
+	const url = `/sandbox/sandboxes/${sandboxId}/jobs/${jobId}${queryString ? `?${queryString}` : ''}`;
+
+	const resp = await client.delete<z.infer<typeof JobStopResponseSchema>>(
+		url,
+		JobStopResponseSchema,
+		signal
+	);
+
+	if (resp.success) {
+		return resp.data;
+	}
+
+	throwSandboxError(resp, { sandboxId, jobId: params.jobId });
+}

package/src/services/sandbox/types.ts

@@ -167,6 +167,35 @@ export const ExecutionStatusSchema = z.enum([
 ]);
 export type ExecutionStatus = z.infer<typeof ExecutionStatusSchema>;
 
+export const JobStatusSchema = z.enum(['pending', 'running', 'completed', 'failed', 'cancelled']);
+export type JobStatus = z.infer<typeof JobStatusSchema>;
+
+export const JobSchema = z.object({
+	jobId: z.string().describe('Unique identifier for the job'),
+	sandboxId: z.string().describe('ID of the sandbox where the job is running'),
+	command: z.array(z.string()).describe('Command and arguments being executed'),
+	status: JobStatusSchema.describe('Current status of the job'),
+	exitCode: z.number().optional().describe('Exit code of the job (set when completed)'),
+	startedAt: z.string().optional().describe('ISO timestamp when the job started'),
+	completedAt: z.string().optional().describe('ISO timestamp when the job completed'),
+	error: z.string().optional().describe('Error message if the job failed'),
+	stdoutStreamUrl: z.string().optional().describe('URL to stream stdout output'),
+	stderrStreamUrl: z.string().optional().describe('URL to stream stderr output'),
+});
+export type Job = z.infer<typeof JobSchema>;
+
+export const CreateJobOptionsSchema = z.object({
+	command: z.array(z.string()).describe('Command and arguments to execute'),
+	streams: z
+		.object({
+			stdout: z.string().optional().describe('Stream ID for stdout output'),
+			stderr: z.string().optional().describe('Stream ID for stderr output'),
+		})
+		.optional()
+		.describe('Stream configuration for output redirection'),
+});
+export type CreateJobOptions = z.infer<typeof CreateJobOptionsSchema>;
+
 /** Read-only stream interface for consuming streams without write access */
 export const StreamReaderSchema = z.object({
 	/** Unique stream identifier */

package/src/services/sandbox/util.ts

@@ -176,6 +176,7 @@ export const SnapshotNotFoundError = StructuredError('SnapshotNotFoundError')<{
 export const SandboxErrorContextSchema = z.object({
 	sandboxId: z.string().optional().describe('sandbox id'),
 	executionId: z.string().optional().describe('execution id'),
+	jobId: z.string().optional().describe('job id'),
 	sessionId: z.string().nullish().describe('session id'),
 	snapshotId: z.string().optional().describe('snapshot id'),
 });